Open API des Termins
Die Appointment Open -API ist eine Telekommunikations-API, die Ihnen die Interaktion mit der Terminbuchungsanwendung ermöglicht. Verwenden Sie diese API, um Termine zu buchen und verfügbare Zeitfenster zu durchsuchen.
Die offene Appointment -API ist eine ServiceNow® -Implementierung der REST-API-Spezifikation Open API TMForum TMF646 Appointment REST API und wurde vom TM Forum für ihre Konformität zertifiziert. Diese Implementierung basiert auf der REST-Spezifikation R16.0.1 der TMF646-Termin-API.
- Terminbuchung (com.snc.appointment_booking)
- Field Service Management (com.snc.work_management_pa)
- Außendienst-Management für die Telekommunikation (com.sn_fsmt)
- Offene Telekommunikations-APIs (com.sn_tmf_api)
Vor der Verwendung dieser API müssen die Konfiguration für die Terminbuchung und die Servicekonfiguration eingerichtet werden. Darüber hinaus muss eine Aufgabe vorhanden sein, für die der Termin gebucht wird.
Diese API wird im Namespace sn_tmf_api bereitgestellt. Der anrufende Benutzer muss über die Rolle sn_tmf_api.appointment_integrator verfügen.
Termin offen: GET /api/sn_tmf_api/appointment/searchTimeSlot
Gibt Zeitfenster zurück, die in der Konfiguration des Terminbuchungsservices zusammen mit ihrer Verfügbarkeit konfiguriert wurden.
URL-Format
/api/sn_tmf_api/appointment/searchTimeSlot
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| catalog_id | Erforderlich. Sys_id des Datensatzerstellers, der mit einer Konfiguration für einen Terminbuchungsservice konfiguriert ist. Datentyp: Zeichenfolge Tabelle: Datensatzersteller [sc_cat_item_producer] |
| end_date | Erforderlich. Enddatum und -uhrzeit des Zeitraums, in dem Sie nach dem Termin suchen möchten. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: |
| location | Sys_id des Standorts des Termins. Tabelle: Standort [cmn_location] Datentyp: Zeichenfolge Standard: Gibt alle Standorte zurück, wenn keine angegeben sind. |
| opened_for | Erforderlich. Sys_id des Anwenders, für den der Termin gebucht wird. Tabelle: Kontakt [customer_contact] Datentyp: Zeichenfolge |
| start_date | Erforderlich. Startdatum und -uhrzeit des Zeitraums, in dem Sie nach dem Termin suchen möchten. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: |
| Name | Beschreibung |
|---|---|
| Keine |
Kopfzeilen
Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.
| Kopfzeile | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützt nur application/json. |
| Kopfzeile | Beschreibung |
|---|---|
| Keine |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| 400 | Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt. |
| 500 | Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler. |
Parameter des Antwort-Haupttexts
| Name | Beschreibung |
|---|---|
| VerfügbaresZeitfenster | Liste der Terminfenster innerhalb des angegebenen angeforderten Zeitblocks Datentyp: Array von Objekten |
| VerfügbaresZeitfenster.verfügbar | Kennzeichnung, die angibt, ob das zugeordnete Zeitfenster verfügbar ist. Mögliche Werte:
Datentyp: Boolesch |
| VerfügbareZeitSlot.Enddatum | Enddatum und -uhrzeit des zugeordneten Termins. Die Zeitzone basiert auf dem Wert im Parameter timeZone. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
| availableTimeSlot.end_date_display | Zeigt Enddatum und -uhrzeit des zugeordneten Termins an. Die Zeitzone basiert auf dem Wert im Parameter timeZone. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
| availableTimeSlot.end_dateUTC | Enddatum und -uhrzeit des zugeordneten Termins. Datentyp: Zeichenfolge Format: UTC |
| VerfügbareZeitSlot.start_date | Startdatum und -uhrzeit des zugeordneten Termins. Entspricht dem Wert des timeZone -Parameters. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
| availableTimeSlot.start_date_display | Zeigt Startdatum und -uhrzeit des zugeordneten Termins an. Entspricht dem Wert des timeZone -Parameters. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
| availableTimeSlot.start_dateUTC | Startdatum und -uhrzeit des zugeordneten Termins. Datentyp: Zeichenfolge Format: UTC |
| hasMore | Kennzeichnung, die angibt, ob nach der Rückgabe des Grenzwerts weitere Terminfenster zum Abrufen vorhanden sind. Der Grenzwert ist in der Eigenschaft Terminbuchung sn_apptmnt_booking.max_appointments_returned (Standard: 100) angegeben. Weitere Informationen zu dieser Eigenschaft finden Sie unter Appointment booking components. Mögliche Werte:
Datentyp: Boolesch |
| noApptAvailable | Kennzeichnung, die angibt, ob für das angegebene Datum und die angegebene Uhrzeit weitere Terminfenster verfügbar sind. Gültige Werte:
Datentyp: Boolesch |
| searchResult | Ergebnisse für Terminverfügbarkeit innerhalb des angegebenen Suchzeitfensters. Mögliche Werte:
Datentyp: Zeichenfolge |
| status | Abschlussstatus der Suche nach verfügbaren Zeitfenstern. Beispiel: done. Datentyp: Zeichenfolge |
| Zeitzone | Zeitzone, die beim Buchen oder Aktualisieren des angegebenen Terminfensters verwendet wird. Datumstyp: Zeichenfolge Format: Länder-/Stadt- oder Gebietsformat, z. B. USA/Ost |
cURL-Anforderung
Das folgende Codebeispiel zeigt, wie dieser Endpunkt aufgerufen wird.
curl --location --request GET 'https://instance.service-now.com/api/sn_tmf_api/appointment/searchTimeSlot?
start_date=2024-07-10 09:00:00&end_date=2024-07-20 23:00:00&catalog_id=ada50a93f0220210f8776517d8c8e776&
opened_for=51670151c35420105252716b7d40ddfe&location=f48b21850a0a0ba7004182b18099696d ' \
--user 'username':'password'Ergebnis:
{
"searchResult": "success",
"status": "done",
"availableTimeSlot": [
{
"start_date": "2024-07-10 09:00:00",
"end_date": "2024-07-10 12:00:00",
"start_date_display": "09:00",
"end_date_display": "12:00",
"start_dateUTC": "2024-07-10 16:00:00",
"end_dateUTC": "2024-07-10 19:00:00",
"available": false
},
{
"start_date": "2024-07-11 13:00:00",
"end_date": "2024-07-11 16:00:00",
"start_date_display": "13:00",
"end_date_display": "16:00",
"start_dateUTC": "2024-07-11 20:00:00",
"end_dateUTC": "2024-07-11 23:00:00",
"available": true
},
{
"start_date": "2024-07-12 09:00:00",
"end_date": "2024-07-12 12:00:00",
"start_date_display": "09:00",
"end_date_display": "12:00",
"start_dateUTC": "2024-07-12 16:00:00",
"end_dateUTC": "2024-07-12 19:00:00",
"available": true
},
{
"start_date": "2024-07-12 13:00:00",
"end_date": "2024-07-12 16:00:00",
"start_date_display": "13:00",
"end_date_display": "16:00",
"start_dateUTC": "2024-07-12 20:00:00",
"end_dateUTC": "2024-07-12 23:00:00",
"available": true
},
{
"start_date": "2024-07-19 13:00:00",
"end_date": "2024-07-19 16:00:00",
"start_date_display": "13:00",
"end_date_display": "16:00",
"start_dateUTC": "2024-07-19 20:00:00",
"end_dateUTC": "2024-07-19 23:00:00",
"available": true
}
],
"hasMore": false,
"noApptAvailable": false,
"timeZone": "US/Arizona"
}Termin offen: POST /api/sn_tmf_api/appointment/appointment
Ermöglicht das Buchen von Terminen für einen Arbeitsauftrag.
URL-Format
/api/sn_tmf_api/appointment/appointment
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Kategorie | Erforderlich. Sys_id des Datensatzerstellers, der für die Konfiguration des Terminbuchungsservice konfiguriert ist. Datentyp: Zeichenfolge Tabelle: Im Feld Katalogelement der Tabelle Konfigurationen für Terminbuchungsservice [sn_apptmnt_booking_service_config] |
| ZugehörigeEntität | Erforderlich. Liste der betroffenen Arbeitsaufträge, die dem Termin zugeordnet werden sollen. Datentyp: Array von Objekten |
| relatedEntity.@referredType | Erforderlich. Art des Artikels oder Services. Einziger gültiger Wert: WorkOrder Datentyp: Zeichenfolge Tabelle: Arbeitsauftrag [wm_order] |
| relatedEntity.id | Erforderlich. Sys_id der zugehörigen Entität. Datentyp: Zeichenfolge Tabelle: workOrder [wm_order] Standard: Gibt alle zurück, wenn sys_id nicht angegeben ist. |
| ZugehörigeEntität.Rolle | Erforderlich. Rollenbeschreibung der zugehörigen Entität. Einziger gültiger Wert: Arbeitsauftrag Datentyp: Zeichenfolge Tabelle: Arbeitsauftrag [wm_order] |
| Zugehörige Partei | Erforderlich. Liste der Kontakte für den Termin Jeder Kontakt ist ein Objekt im Array. In der Anforderung muss mindestens ein Artikel aufgeführt werden, der Kunden-Account-Informationen enthält. Datentyp: Array von Objekten |
| zugehörigepartei.@referenztyp | Typ des Kunden Einziger gültiger Wert: „Individual“. Datentyp: Zeichenfolge |
| relatedParty.id | Erforderlich. Sys_id oder external_id des Kontakts, der dem Arbeitsauftrag zugeordnet ist. Datentyp: Zeichenfolge Tabelle: Kontakt [customer_contact] |
| relatedParty.name | Name des Kontakts Datentyp: Zeichenfolge Tabelle: Kontakt [customer_contact] |
| zugehörigePartei.Rolle | Erforderlich. Rolle des Kontakts Mögliche Werte:
Datentyp: Zeichenfolge Tabelle: Kontakt [customer_contact] |
| ZugehörigerOrt | Erforderlich. Liste der Standorte im Zusammenhang mit dem Termin Datentyp: Array von Objekten |
| relatedplace.@referredType | Erforderlich. Standorttyp Beispiel: Stadt. Datentyp: Zeichenfolge Tabelle: Standorte [cmn_location] |
| relatedPlace.id | Erforderlich. Sys_id des zugehörigen Standorts. Datentyp: Zeichenfolge Tabelle: Standorte [cmn_location] |
| relatedPlace.name | Name des Standorts im Zusammenhang mit dem Kontakt. Beispiel: 251 Reddy St, Darwin, CA 93522. Datentyp: Zeichenfolge Tabelle: Standorte [cmn_location] |
| ZugehörigerOrt.Rolle | Erforderlich. Beschreibung der Standortrolle. Beispiel: Arbeitsauftrag. Datentyp: Zeichenfolge |
| Zeitzone | Erforderlich. Zeitzone, die bei der Buchung des angegebenen Terminfensters verwendet werden soll. Datumstyp: Zeichenfolge Format: Länder-/Stadt- oder Gebietsformat, z. B. USA/Ost |
| validFor | Erforderlich. Datumsbereich, für den der Termin gültig ist. Datentyp: Objekt |
| validFor.endDateTime | Erforderlich. Enddatum und -uhrzeit des Zeitfensters. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
| validFor.startDateTime | Erforderlich. Startdatum und -uhrzeit des Zeitfensters. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
Header
Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.
| Kopfzeile | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützt nur application/json. |
| Kopfzeile | Beschreibung |
|---|---|
| Content-Type | Datenformat des Anforderungstexts. Unterstützt nur application/json. |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| 500 | Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler. |
Parameter des Antwort-Haupttexts
| Name | Beschreibung |
|---|---|
| Kategorie | Sys_id des Datensatzerstellers, der für die Konfiguration des Terminbuchungsservice konfiguriert ist. Datentyp: Zeichenfolge Gespeichert in: Feld „Katalogelement“ der Tabelle „Konfigurationen für Terminbuchungsservice“ [sn_apptmnt_booking_service_config]. |
| creationDate | Datum und Uhrzeit der Erstellung des Termins. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
| href | Hyperlink zum Termindatensatz. Verwenden Sie diesen Link in einer anderen API-Anforderung für die Terminverwaltung, um den Termin neu zu planen oder zu löschen. Datentyp: Zeichenfolge |
| id | Sys_id des Termins. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Konfigurationen für Terminbuchungsservice“ [sn_apptmnt_booking_service_config]. |
| lastUpdate | Datum und Uhrzeit der letzten Aktualisierung des Termins. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
| ZugehörigeEntität | Details zur zugehörigen Entität des Termins. Datentyp: Array von Objekten |
| relatedEntity.@referredType | Art des Artikels oder Services. Datentyp: Zeichenfolge Gespeichert in: Tabelle „workOrder“ [wm_order]. |
| relatedEntity.id | Sys_id der zugehörigen Entität. Datentyp: Zeichenfolge Gespeichert in: Tabelle „workOrder“ [wm_order]. |
| ZugehörigeEntität.Rolle | Rollenbeschreibung der zugehörigen Entität. Möglicher Wert: Arbeitsauftrag Datentyp: Zeichenfolge Gespeichert in: Tabelle „workOrder“ [wm_order]. |
| Zugehörige Partei | Liste der Kontakte für den Termin Jeder Kontakt ist ein Objekt im Array. Datentyp: Array von Objekten |
| zugehörigepartei.@referenztyp | Typ des Kunden Datentyp: Zeichenfolge Gespeichert in: Kontakttabelle [customer_contact] |
| Zugehörigepartei.id | Sys_id des Kundenkontakts, der dem Arbeitsauftrag zugeordnet ist. Datentyp: Zeichenfolge Gespeichert in: Kontakttabelle [customer_contact] |
| Zugehörigepartei.name | Name des Kundenkontakts Datentyp: Zeichenfolge Gespeichert in: Kontakttabelle [customer_contact] |
| zugehörigePartei.Rolle | Rolle des Kundenkontakts Mögliche Werte:
Datentyp: Zeichenfolge Gespeichert in: Kontakttabelle [customer_contact] |
| ZugehörigerOrt | Standortdetails des zugeordneten Termins. Datentyp: Objekt |
| relatedplace.@referredType | Geografische Adresse des Termins. Möglicher Wert: GeographicLocation. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Standort“ [cmn_location]. |
| ZugehörigerOrt.ID | Sys_id des Standorts Datentyp: Zeichenfolge Gespeichert in: Tabelle „Standort“ [cmn_location]. |
| relatedPlace.name | Name des Standorts im Zusammenhang mit dem Kontakt. Beispiel: 100 South Charles Street, Washington, DC. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Standort“ [cmn_location]. |
| ZugehörigerOrt.Rolle | Rolle des Terminstandorts als Interventionsadresse. Möglicher Wert: InterventionAddress Datentyp: Zeichenfolge Gespeichert in: Tabelle „Standort“ [cmn_location]. |
| Erfolg | Kennzeichnung, die angibt, ob die Anforderung erfolgreich war. Mögliche Werte:
Datentyp: Boolesch |
| Zeitzone | Zeitzone, die beim Buchen oder Aktualisieren des angegebenen Terminfensters verwendet wird. Datumstyp: Zeichenfolge Format: Länder-/Stadt- oder Gebietsformat, z. B. USA/Ost |
| validFor | Datumsbereich, für den der Termin gültig ist. Datentyp: Objekt |
| validFor.endDateTime | Enddatum und -uhrzeit des Termins. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
| validFor.startDateTime | Startdatum und -uhrzeit des Termins. Datentyp: Zeichenfolge Format: JJJJ-MM-TT 00:00:00. Beispiel: 31.01.2025 09:35:43. |
cURL-Anforderung
Das folgende Beispiel zeigt, wie Sie eine neue Terminbuchung erstellen.
curl "https://instance.servicenow.com/api/sn_tmf_api/appointment/appointment" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"validFor\": {
\"startDateTime\": \"2024-08-19 09:00:00\",
\"endDateTime\": \"2024-08-19 11:00:00\"
},
\"category\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
\"relatedParty\": [
{
\"id\": \"eaf68911c35420105252716b7d40ddde\",
\"name\": \"Sally Thomas\",
\"role\": \"customer\",
\"@referredType\": \"Individual\"
}
],
\"relatedPlace\": {
\"id\": \"25ab9c4d0a0a0bb300f7dabdc0ca7c1c\",
\"name\": \"100 South Charles Street, Baltimore,MD\",
\"role\": \"interventionAddress\",
\"@referredType\": \"GeographicAddress\"
},
\"relatedEntity\": [
{
\"id\": \"48dbfbf9201f0250f877303e8a020dcd\",
\"role\": \"work order\",
\"@referredType\": \"WorkOrder\"
}
],
\"timeZone\": \"US/Arizona\"
}" \
--user 'username':'password'Antwort:
{
"validFor": {
"startDateTime": "2024-07-19 09:00:00",
"endDateTime": "2024-07-19 11:00:00"
},
"category": "e4c1116b3b810300ce8a4d72f3efc40f",
"relatedParty": [
{
"id": "eaf68911c35420105252716b7d40ddde",
"name": "Sally Thomas",
"role": "customer",
"@referredType": "Individual"
}
],
"relatedPlace": {
"id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
"name": "100 South Charles Street, Baltimore,MD",
"role": "interventionAddress",
"@referredType": "GeographicAddress"
},
"relatedEntity": [
{
"id": "48dbfbf9201f0250f877303e8a020dcd",
"role": "work order",
"@referredType": "WorkOrder"
}
],
"timeZone": "US/Arizona",
"success": true,
"id": "feacb7f9201f0250f877303e8a020d38",
"href": "api/sn_tmf_api/appointment/appointment/feacb7f9201f0250f877303e8a020d38",
"creationDate": "2024-07-10 22:45:01",
"lastUpdate": "2024-07-10 22:45:01"
}