API zum Öffnen des Termins
Die Termin Offen API ist eine Telekommunikations-API, mit der Sie mit der Terminbuchungsanwendung interagieren können. Verwenden Sie diese API, um Termine zu buchen und verfügbare Zeitfenster zu durchsuchen.
Die Termin Offen API ist ein ServiceNow®Implementierung der Spezifikation „Open API TMForum TMF646 Termin-REST API“ und ist von TM Forum zertifiziert. Diese Implementierung basiert auf TMF646 Termin-API REST-Spezifikation R16.0.1 .
- Terminbuchung (com.snc.appointment_booking)
- Außendienstmanagement (com.snc.work_Management)
- Außendienstmanagement für Telekommunikation (com.sn_fsmt)
- Offene APIs für Telekommunikation (com.sn_tmf_api)
Vor der Verwendung dieser API müssen die Terminbuchungskonfiguration und die Servicekonfiguration eingerichtet werden. Darüber hinaus muss eine Aufgabe vorhanden sein, für die der Termin gebucht wird.
Diese API wird in bereitgestellt sn_tmf_api Namespace. Der aufrufende Anwender 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 Terminbuchungsservice konfiguriert wurden, zusammen mit ihrer Verfügbarkeit.
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 des 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 nicht angegeben. |
| Geöffnet_für | 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 |
Header
Die folgenden Anforderungs- und Antwort-Header gelten nur für diese HTTP-Aktion oder werden auf diese Aktion in einer bestimmten Weise angewendet. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header .
| Header | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Nur unterstützt application/json. |
| Header | 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 REST-API-HTTP-Antwortcodes .
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| 400 | Ungültige Anforderung. Ein ungültiger Anforderungstyp oder eine fehlerhafte Anforderung wurde erkannt. |
| 500 | Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Die Antwort enthält zusätzliche Informationen zum Fehler. |
Antworttext-Parameter
| Name | Beschreibung |
|---|---|
| VerfügbarZeitfenster | Liste der Terminfenster innerhalb des angegebenen angeforderten Zeitblocks. Datentyp: Array von Objekten |
| VerfügbarZeitfenster.verfügbar | Kennzeichnung, die angibt, ob das zugehörige Zeitfenster verfügbar ist. Mögliche Werte:
Datentyp: Boolescher Wert |
| VerfügbarTimeSlot.end_date | Enddatum und -Uhrzeit des zugehörigen Termins. Die Zeitzone basiert auf dem Wert in timeZoneParameter. Datentyp: Zeichenfolge FORMAT: JJJJ-MM-TT 00:00:00. Beispiel: 2025-01-31 09:35:43. |
| VerfügbarTimeSlot.end_date_Display | Enddatum und -Uhrzeit des zugehörigen Termins anzeigen. Die Zeitzone basiert auf dem Wert in timeZoneParameter. Datentyp: Zeichenfolge FORMAT: JJJJ-MM-TT 00:00:00. Beispiel: 2025-01-31 09:35:43. |
| VerfügbarTimeSlot.end_dateUTC | Enddatum und -Uhrzeit des zugehörigen Termins. Datentyp: Zeichenfolge Format: UTC |
| VerfügbarTimeSlot.Start_date | Startdatum und -Uhrzeit des zugehörigen Termins. Spiegelt den Wert von wider timeZoneParameter. Datentyp: Zeichenfolge FORMAT: JJJJ-MM-TT 00:00:00. Beispiel: 2025-01-31 09:35:43. |
| VerfügbarTimeSlot.Start_date_Display | Zeigen Sie Startdatum und -Uhrzeit des zugehörigen Termins an. Spiegelt den Wert von wider timeZoneParameter. Datentyp: Zeichenfolge FORMAT: JJJJ-MM-TT 00:00:00. Beispiel: 2025-01-31 09:35:43. |
| VerfügbarTimeSlot.Start_dateUTC | Startdatum und -Uhrzeit des zugehörigen Termins. Datentyp: Zeichenfolge Format: UTC |
| hasMore | Kennzeichnung, die angibt, ob nach Rückgabe des Limits weitere Terminfenster abgerufen werden sollen. Das Limit wird in der Terminbuchungseigenschaft „sn_apptmnt_booking.max_appointments_returned“ angegeben (Standard: 100). Siehe Appointment booking componentsFür weitere Details zu dieser Eigenschaft. Mögliche Werte:
Datentyp: Boolescher Wert |
| NoApptVerfügbar | Kennzeichnung, die angibt, ob für das angegebene Datum und die angegebene Uhrzeit weitere Terminfenster verfügbar sind. Gültige Werte:
Datentyp: Boolescher Wert |
| Suchergebnis | Ergebnisse für Terminverfügbarkeit innerhalb des festgelegten Suchzeitfensters. Mögliche Werte:
Datentyp: Zeichenfolge |
| Status | Abschlussstatus der Suche nach verfügbaren Zeitfenstern. Beispiel: Fertig. Datentyp: Zeichenfolge |
| timeZone | Zeitzone, die beim Buchen oder Aktualisieren des angegebenen Terminfensters verwendet wird. Datumstyp: Zeichenfolge Format: Format für Land/Stadt oder Gebiet, z. B. USA/Osten |
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 – POSTEN /api/sn_tmf_api/Termin/Termin
Ermöglicht Ihnen, Termine für einen Arbeitsauftrag zu buchen.
URL-Format
/api/sn_tmf_api/Termin/Termin
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 „Konfiguration des Terminbuchungsservice“ [sn_apptmnt_booking_service_config]. |
| ZugehörigEntität | Erforderlich. Liste der betroffenen Arbeitsaufträge, die dem Termin zugeordnet werden sollen. Datentyp: Array von Objekten |
| RelatedEntity.@referredType | Erforderlich. Typ des Artikels oder Service. Nur gültiger Wert: Arbeitsauftrag Datentyp: Zeichenfolge Tabelle: Arbeitsauftrag [wm_order] |
| relatedEntity.id | Erforderlich. SYS_ID der zugehörigen Entität. Datentyp: Zeichenfolge Tabelle: Arbeitsauftrag [wm_order] Standard: Gibt alle zurück, wenn „sys_ID“ nicht angegeben ist. |
| RelatedEntity.role | Erforderlich. Rollenbeschreibung der zugehörigen Entität. Nur gültiger Wert: Arbeitsauftrag Datentyp: Zeichenfolge Tabelle: Arbeitsauftrag [wm_order] |
| ZugehörigPartei | Erforderlich. Liste der Kontakte für den Termin. Jeder Kontakt ist ein Objekt im Array. Die Anforderung muss mindestens ein Element auflisten, das Kundenaccount-Informationen enthält. Datentyp: Array von Objekten |
| RelatedParty.@referredType | Typ des Kunden. Nur gültiger Wert: Einzeln 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] |
| RelatedParty.role | Erforderlich. Rolle des Kontakts. Mögliche Werte:
Datentyp: Zeichenfolge Tabelle: Kontakt [Customer_contact] |
| RelatedPlace | Erforderlich. Liste der Standorte im Zusammenhang mit dem Termin. Datentyp: Array von Objekten |
| RelatedPlace.@referredType | Erforderlich. Typ des Standorts. 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, der sich auf den Kontakt bezieht. Beispiel: 251 Reddy St, Darwin, CA 93522. Datentyp: Zeichenfolge Tabelle: Standorte [cmn_location] |
| RelatedPlace.role | Erforderlich. Beschreibung der Standortrolle. Beispiel: Arbeitsauftrag. Datentyp: Zeichenfolge |
| timeZone | Erforderlich. Zeitzone, die bei der Buchung des angegebenen Terminfensters verwendet werden soll. Datumstyp: Zeichenfolge Format: Format für Land/Stadt oder Gebiet, z. B. USA/Osten |
| ValidiertFür | 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: 2025-01-31 09:35:43. |
| ValidFor.startDateTime | Erforderlich. Startdatum und -Uhrzeit des Zeitfensters. Datentyp: Zeichenfolge FORMAT: JJJJ-MM-TT 00:00:00. Beispiel: 2025-01-31 09:35:43. |
Header
Die folgenden Anforderungs- und Antwort-Header gelten nur für diese HTTP-Aktion oder werden auf diese Aktion in einer bestimmten Weise angewendet. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header .
| Header | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Nur unterstützt application/json. |
| Header | Beschreibung |
|---|---|
| Inhaltstyp | Datenformat des Anforderungstexts. Nur unterstützt 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 REST-API-HTTP-Antwortcodes .
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| 500 | Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Die Antwort enthält zusätzliche Informationen zum Fehler. |
Antworttext-Parameter
| Name | Beschreibung |
|---|---|
| Kategorie | SYS_ID des Datensatzerstellers, der für die Konfiguration des Terminbuchungsservice konfiguriert ist. Datentyp: Zeichenfolge Gespeichert in: Feld „Katalogelement“ der Tabelle „Konfiguration des Terminbuchungsservice“ [sn_apptmnt_booking_service_config]. |
| creationDate | Datum und Uhrzeit der Erstellung des Termins. Datentyp: Zeichenfolge FORMAT: JJJJ-MM-TT 00:00:00. Beispiel: 2025-01-31 09:35:43. |
| href | Hyperlink zum Termindatensatz. Verwenden Sie diesen Link in einer anderen API-Anforderung zum Öffnen von Terminen, um den Termin neu zu planen oder zu löschen. Datentyp: Zeichenfolge |
| ID | SYS_ID des Termins. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Konfiguration des 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: 2025-01-31 09:35:43. |
| ZugehörigEntität | Details zur zugehörigen Entität des Termins. Datentyp: Array von Objekten |
| RelatedEntity.@referredType | Typ des Artikels oder Service. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Arbeitsauftrag“ [wm_order] |
| RelatedEntity.ID | SYS_ID der zugehörigen Entität. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Arbeitsauftrag“ [wm_order] |
| RelatedEntity.role | Rollenbeschreibung der zugehörigen Entität. Möglicher Wert: Arbeitsauftrag Datentyp: Zeichenfolge Gespeichert in: Tabelle „Arbeitsauftrag“ [wm_order] |
| ZugehörigPartei | Liste der Kontakte für den Termin. Jeder Kontakt ist ein Objekt im Array. Datentyp: Array von Objekten |
| RelatedParty.@referredType | Typ des Kunden. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Kontakt“ [Customer_contact] |
| RelatedParty.ID | SYS_ID des Kundenkontakts, der dem Arbeitsauftrag zugeordnet ist. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Kontakt“ [Customer_contact] |
| relatedParty.name | Name des Kundenkontakts. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Kontakt“ [Customer_contact] |
| RelatedParty.role | Rolle des Kundenkontakts. Mögliche Werte:
Datentyp: Zeichenfolge Gespeichert in: Tabelle „Kontakt“ [Customer_contact] |
| RelatedPlace | Standortdetails des zugehörigen Termins. Datentyp: Objekt |
| RelatedPlace.@referredType | Geografische Adresse des Termins. Möglicher Wert: GeographicLocation. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Standort“ [cmn_location] |
| RelatedPlace.ID | SYS_ID des Standorts. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Standort“ [cmn_location] |
| relatedPlace.name | Name des Standorts, der sich auf den Kontakt bezieht. Beispiel: 100 South Charles Street, Baltimore, MD. Datentyp: Zeichenfolge Gespeichert in: Tabelle „Standort“ [cmn_location] |
| RelatedPlace.role | 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: Boolescher Wert |
| timeZone | Zeitzone, die beim Buchen oder Aktualisieren des angegebenen Terminfensters verwendet wird. Datumstyp: Zeichenfolge Format: Format für Land/Stadt oder Gebiet, z. B. USA/Osten |
| ValidiertFür | 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: 2025-01-31 09:35:43. |
| ValidFor.startDateTime | Startdatum und -Uhrzeit des Termins. Datentyp: Zeichenfolge FORMAT: JJJJ-MM-TT 00:00:00. Beispiel: 2025-01-31 09:35:43. |
Curl-Anforderung
Das folgende Beispiel zeigt, wie eine neue Terminbuchung erstellt wird.
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"
}