Reservierungen in CentralPlanner

API Navigation

Allgemeines: Grundlagen Authentifizierung Fehlerbehandlung Datenstruktur

Hauptmodelle: Kontakte Reservierungen

Sonstiges: Schlagwörter

Bei den Reservierungen sowie den meisten sonstigen Objekten in CentralPlanner stehen die folgenden Actions zur Verfügung: index, show, create, update und delete. Jede Kontakt enthält die folgenden Felder:

Feldname Feldtyp Beschreibung
id INTEGER ID der Reservierung (Read only)
account_id INTEGER ID des Accounts (Read only)
type VARCHAR(20) Typ der Reservierung (SingleBooking oder RecurringBooking) (Pflichtfeld)
group_id INTEGER ID der ersten Reservierung, wenn es sich um einen Serientermin (type=RecurringBooking) handelt. Ansonsten nil.
area_id INTEGER ID des Raumes / Platzes der Reservierung (Pflichtfeld)
contact_id INTEGER ID des Kontaktes der Reservierung (Pflichtfeld)
date DATE Datum der Reservierung (Pflichtfeld)
hour INTEGER Stunde der Reservierung (Pflichtfeld)
minute INTEGER Minute der Reservierung (0-59) (Pflichtfeld)
number_guests INTEGER Anzahl der Gäste (Pflichtfeld)
note TEXT Notiz zur Reservierung
duration INTEGER Dauer des Besuchs in Minuten (default: 90)
created_by_user_id INTEGER ID des Nutzers, der die Reservierung erstellt hat
company VARCHAR(100) Firmenname
mail_confirmation BOOLEAN true / false, je nachdem ob der Gast Bestätigungen per E-Mail erhalten möchte
status VARCHAR(20) Status der Reservierung (open, accepted, auto_accepted, currently_active, declined, completed, no_show)
webform BOOLEAN true / false, je nachdem ob die Reservierung über ein Online Formular eingegangen ist
created_at TIMESTAMP Zeitpunkt der Erstellung (automatisch gesetzt, read only)
updated_at TIMESTAMP Zeitpunkt des letzten Updates (automatisch gesetzt, read only)

Action: Index

GET /api/bookings.json
Mit der Index Action kann eine Liste aller Reservierungen in einem Account abgefragt werden. Als Default werden immer 50 Elemente ausgegeben. Die Zahl der Elemente pro Seite / Request kann über den Parameter perpage verändert werden. Durch Angabe des Parameters page (z.B. page=2) kann die Seitenzahl angegeben werden. Die Sortierung kann mit dem Parameter order beeinflusst werden. Möglich sind zum Beispiel "created-at-asc" für absteigend nach Erstellungsdatum. Wenn das order Statement übergeben wird, ist die Sortierreihenfolge (asc, desc) eine Pflichtangabe. Sortiert werden kann nach created_at (Erstellungsdatum), updated_at (Bearbeitungsdatum) oder name (Alphabetisch). Standard ist asc (aufsteigend) nach name (Alphabet).

Beispiel
curl https://centralplanner.net/api/bookings
-H 'Authorization: Token token="my-api-token"'

[{
    "id": 222,
    "account_id": 8,
    "type": "SingleBooking",
    "group_id": null,
    "area_id": 14,
    "contact_id": 187,
    "date": "2011-06-17",
    "hour": 16,
    "minute": 30,
    "number_guests": 6,
    "note": "Frau Bachmann möchte gerne einen Tisch am Fenster und kommt nur zum Kaffee & Kuchen. Kein warmes Essen!",
    "created_by_user_id": null,
    "duration": 90,
    "mail_confirmation": false,
    "created_at": "2011-06-15T09:41:58.000+02:00",
    "updated_at": "2011-06-15T10:37:23.000+02:00",
    "status": "accepted",
    "webform": false,
    "contact": {
        "id": 187,
        "account_id": 8,
        "completed_bookings_count": 12,
        "title": "Frau",
        "first": "Stefanie",
        "last": "Dachmann",
        "note": "Kommt regelmäßig zum A la Carte Essen.",
        "phone": "006074-3000098",
        "phone_clean": "0060743000098",
        "phone2": "",
        "phone2_clean": "",
        "mail": "stefanie.bachmann@example.com",
        "company": null,
        "street": "",
        "zip": null,
        "city": "Vorstätten",
        "newsletter": false,
        "newsletter_double_opt_in_hash": null,
        "created_at": "2011-06-15T09:39:56.000+02:00",
        "updated_at": "2013-05-15T16:56:24.000+02:00",
        "import_id": null,
        "deleted_at": null
    }
}, ...]

Action: Show

GET /api/bookings/{id}
Eine einzelne Reservierung kann mit der show Action geladen werden. Voraussetzung hierfür ist eine für den Account gültige booking ID. Zusätzlich zu der Reservierung wird der verknüpfte Kontakt direkt mit geschickt.

Action: Create

POST /api/bookings.json
Eine neue Kontakt kann mit der Action create angelegt werden. Im positiven Fall liefert das System die neue Kontakt zurück. Zum Anlegen einer neuen Kontakt ist die Übergabe des Nachnamens Pflicht.

Hinweis: Das System legt automatisch einen Eintrag für den Verlauf bei create, update und destroy an. Bei Massenimporten sollte dieses nicht gemacht werden. Dieses kann durch mitsenden des Parameters "no_log" erreicht werden. Dann wird kein Eintrag in den Verlauf geschrieben. Beispiel
curl -v -H "Content-type: application/json" 
-H 'Authorization: Token token="my-api-token"' 
-X POST https://centralplanner.net/api/bookings 
-d '{"booking":{"type":"SingleBooking","area_id":14,"contact_id":187,"date":"2011-06-17","hour":16,"minute":30,"number_guests":6,"note":"Frau Bachmann möchte gerne einen Tisch am Fenster und kommt nur zum Kaffee","duration":90} }'

"id": 222,
"account_id": 8,
"type": "SingleBooking",
"group_id": null,
"area_id": 14,
"contact_id": 187,
"date": "2011-06-17",
"hour": 16,
"minute": 30,
"number_guests": 6,
"note": "Frau Bachmann möchte gerne einen Tisch am Fenster und kommt nur zum Kaffee",
"created_by_user_id": null,
"duration": 90,
"mail_confirmation": false,
"created_at": "2011-06-15T09:41:58.000+02:00",
"updated_at": "2011-06-15T10:37:23.000+02:00",
"status": "accepted",
"webform": false,
"contact": {
    "id": 187,
    "account_id": 8,
    "completed_bookings_count": 12,
    "title": "Frau",
    "first": "Stefanie",
    "last": "Dachmann",
    "note": "Kommt regelmäßig zum A la Carte Essen.",
    "phone": "006074-3000098",
    "phone_clean": "0060743000098",
    "phone2": "",
    "phone2_clean": "",
    "mail": "stefanie.bachmann@example.com",
    "company": null,
    "street": "",
    "zip": null,
    "city": "Vorstätten",
    "newsletter": false,
    "newsletter_double_opt_in_hash": null,
    "created_at": "2011-06-15T09:39:56.000+02:00",
    "updated_at": "2013-05-15T16:56:24.000+02:00",
    "import_id": null,
    "deleted_at": null
}

Action: Update

PUT /api/bookings/{id}.json
Analog zur Create Action funktioniert das Update. Hierzu ist das Verb PUT erforderlich und die Route muss die ID des zu bearbeitenden Elementes erhalten. Die Rückgabe ist hier nicht das Element selber, sondern der Header :ok mit dem HTTP Code 200.

Beispiel
curl -v -H "Content-type: application/json" 
-H 'Authorization: Token token="mein-api-key"' 
-X PUT https://centralplanner.net/api/bookings/222 
-d '{"booking":{"hour":18} }'

Status: 200 OK

Action: Delete

DELETE /api/bookings/{id}.json
Zum Löschen eines Elementes muss man dieses über seine Route mit dem Verb DELETE ansprechen. Auch ist hier die Rückgabe der HTTP Code 200 mit dem Header :ok.

Beispiel
  curl -v -H "Content-type: application/json" 
-H 'Authorization: Token token="my-api-key"' 
-X DELETE https://centralplanner.net/api/bookings/222 

Status: 200 OK