API ouverte pour les rendez-vous
L’API Appointment Open est une API de télécommunication qui vous permet d’interagir avec l’application de prise de rendez-vous. Utilisez cette API pour prendre des rendez-vous et rechercher des créneaux horaires disponibles.
L’API Appointment Open est une ServiceNow® implémentation de la spécification de l’API REST Open API TMForum TMF646 Appointment et est certifiée par TM Forum. Cette implémentation est basée sur la spécification REST R16.0.1 de l’API de rendez-vous TMF646.
- Réservation de rendez-vous (com.snc.appointment_booking)
- Field Service Management (com.snc.work_management)
- Gestion des services sur site pour les télécommunications (com.sn_fsmt)
- API ouvertes de télécommunication (com.sn_tmf_api)
Avant d’utiliser cette API, la configuration de Prise de rendez-vous et la configuration de service doivent être configurées. En outre, une tâche pour laquelle le rendez-vous est pris doit exister.
Cette API est fournie dans l’espace de noms sn_tmf_api . L’utilisateur appelant doit disposer du rôle sn_tmf_api.appointment_integrator.
Rendez-vous ouvert : GET /api/sn_tmf_api/appointment/searchTimeSlot
Renvoie les créneaux horaires configurés dans la configuration du service de réservation de rendez-vous ainsi que leur disponibilité.
Format d'URL
/api/sn_tmf_api/appointment/searchTimeSlot
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| Aucun |
| Nom | Description |
|---|---|
| catalog_id | Requis. Sys_id du créateur d’enregistrement configuré avec une configuration de service de réservation de rendez-vous. Type de données : chaîne Table : Créateur d’enregistrement [sc_cat_item_producer] |
| end_date | Requis. Date et heure de fin de la période pendant laquelle vous souhaitez rechercher le rendez-vous. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, |
| emplacement | Sys_id du lieu du rendez-vous. Table : Emplacement [cmn_location] Type de données : chaîne Par défaut : renvoie tous les emplacements s’ils ne sont pas spécifiés. |
| opened_for | Requis. Sys_id de l’utilisateur pour lequel le rendez-vous est réservé. Table : Contact [customer_contact] Type de données : chaîne |
| start_date | Requis. Date et heure de début de la période pendant laquelle vous souhaitez rechercher le rendez-vous. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, |
| Nom | Description |
|---|---|
| Néant |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Prend uniquement en charge application/json. |
| En-tête | Description |
|---|---|
| Aucun |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 400 | Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de réponse
| Nom | Description |
|---|---|
| availableTimeSlot | Liste des créneaux de rendez-vous dans le bloc de temps spécifié demandé. Type de données : tableau d’objets |
| availableTimeSlot.available | Marqueur indiquant si le créneau horaire associé est disponible. Valeurs possibles :
Type de données : booléennes |
| availableTimeSlot.end_date | Date et heure de fin du rendez-vous associé. Le fuseau horaire est basé sur la valeur du timeZone paramètre. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
| availableTimeSlot.end_date_display | Affichez la date et l’heure de fin du rendez-vous associé. Le fuseau horaire est basé sur la valeur du timeZone paramètre. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
| availableTimeSlot.end_dateUTC | Date et heure de fin du rendez-vous associé. Type de données : chaîne Format : UTC |
| availableTimeSlot.start_date | Date et heure de début du rendez-vous associé. Reflète la timeZone valeur du paramètre. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
| availableTimeSlot.start_date_display | Affichez la date et l’heure de début du rendez-vous associé. Reflète la timeZone valeur du paramètre. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
| availableTimeSlot.start_dateUTC | Date et heure de début du rendez-vous associé. Type de données : chaîne Format : UTC |
| hasMore | Marqueur indiquant s’il existe plus de créneaux de rendez-vous à extraire après avoir renvoyé la limite. La limite est spécifiée dans la propriété Prise de rendez-vous, sn_apptmnt_booking.max_appointments_returned (par défaut : 100). Pour en savoir plus sur cette propriété, reportez-vous à la section Appointment booking components . Valeurs possibles :
Type de données : booléennes |
| noApptDisponible | Marqueur indiquant s’il existe plus de créneaux de rendez-vous disponibles pour la date et l’heure spécifiées. Valeurs valides :
Type de données : booléennes |
| Résultat de recherche | Résultats pour la disponibilité des rendez-vous dans le créneau horaire de recherche désigné. Valeurs possibles :
Type de données : chaîne |
| statut | État d’achèvement de la recherche des créneaux horaires disponibles. Par exemple, terminé. Type de données : chaîne |
| Fuseau horaire | Fuseau horaire utilisé lors de la réservation ou de la mise à jour du créneau de rendez-vous spécifié. Type de date : chaîne Format : format pays/ville ou zone, tel que États-Unis/Est |
Demande cURL
L’exemple de code suivant montre comment appeler ce point de terminaison.
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'Résultat :
{
"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"
}Rendez-vous ouvert : POST /api/sn_tmf_api/appointment/appointment
Vous permet de prendre rendez-vous pour une commande de travaux.
Format d'URL
/api/sn_tmf_api/rendez-vous/rendez-vous
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| Aucun |
| Nom | Description |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| catégorie | Requis. Sys_id du créateur d’enregistrement configuré pour la configuration de service de Prise de rendez-vous. Type de données : chaîne Table : dans le champ Élément de catalogue de la table Configuration du service Prise de rendez-vous [sn_apptmnt_booking_service_config]. |
| Entité connexe | Requis. Liste des commandes de travaux impactées à associer au rendez-vous. Type de données : tableau d’objets |
| relatedEntity.@referredType | Requis. Type d’élément ou de service. Seule valeur valide : WorkOrder Type de données : chaîne Table : commande de travaux [wm_order] |
| relatedEntity.id | Requis. Sys_id de l’entité associée. Type de données : chaîne Table : workOrder [wm_order] Valeur par défaut : renvoie tout si sys_id n’est pas fourni. |
| relatedEntity.role | Requis. Description du rôle de l’entité connexe. Seule valeur valide : commande de travaux Type de données : chaîne Table : commande de travaux [wm_order] |
| Fête connexe | Requis. Liste des contacts pour le rendez-vous. Chaque contact est un objet dans le tableau. La demande doit répertorier au moins un élément contenant des informations de compte client. Type de données : tableau d’objets |
| relatedParty.@referredType | Type de client. Seule valeur valide : Individuel Type de données : chaîne |
| relatedParty.id | Requis. Sys_id ou external_id du contact associé à la commande de travaux. Type de données : chaîne Table : Contact [customer_contact] |
| relatedParty.name | Nom du contact. Type de données : chaîne Table : Contact [customer_contact] |
| relatedParty.role | Requis. Rôle du contact. Valeurs possibles :
Type de données : chaîne Table : Contact [customer_contact] |
| relatedPlace | Requis. Liste des lieux associés au rendez-vous. Type de données : tableau d’objets |
| relatedPlace.@referredType | Requis. Type d’emplacement. Par exemple, Ville. Type de données : chaîne Table : Emplacements [cmn_location] |
| relatedPlace.id | Requis. Sys_id de l’emplacement connexe. Type de données : chaîne Table : Emplacements [cmn_location] |
| relatedPlace.name | Nom de l’emplacement associé au contact. Par exemple, 251 Reddy St, Darwin, CA 93522. Type de données : chaîne Table : Emplacements [cmn_location] |
| relatedPlace.role | Requis. Description du rôle de l’emplacement. Par exemple, commande de travaux. Type de données : chaîne |
| Fuseau horaire | Requis. Fuseau horaire à utiliser lors de la réservation du créneau de rendez-vous spécifié. Type de date : chaîne Format : format pays/ville ou zone, tel que États-Unis/Est |
| valide pour | Requis. Plage de dates pour laquelle le rendez-vous est valide. Type de données : objet |
| validFor.endDateTime | Requis. Date et heure de fin du créneau horaire. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
| validFor.startDateTime | Requis. Date et heure de début du créneau horaire. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Prend uniquement en charge application/json. |
| En-tête | Description |
|---|---|
| Content-Type | Format de données du corps de la demande. Prend uniquement en charge application/json. |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de réponse
| Nom | Description |
|---|---|
| catégorie | Sys_id du créateur d’enregistrement configuré pour la configuration de service de Prise de rendez-vous. Type de données : chaîne Stocké dans : champ Élément de catalogue de la table Configuration du service Prise de rendez-vous [sn_apptmnt_booking_service_config]. |
| creationDate | Date et heure de création du rendez-vous. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
| href | Lien hypertexte vers l’enregistrement du rendez-vous. Utilisez ce lien dans un autre rendez-vous Ouvrez une demande d’API pour replanifier ou supprimer le rendez-vous. Type de données : chaîne |
| id | Sys_id du rendez-vous. Type de données : chaîne Stocké dans : Table Configuration de service de Prise de rendez-vous [sn_apptmnt_booking_service_config] |
| lastUpdate | Date et heure de la dernière mise à jour du rendez-vous. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
| Entité connexe | Détails sur l’entité connexe de la nomination. Type de données : tableau d’objets |
| relatedEntity.@referredType | Type d’élément ou de service. Type de données : chaîne Stockée dans : table workOrder [wm_order] |
| relatedEntity.id | Sys_id de l’entité associée. Type de données : chaîne Stockée dans : table workOrder [wm_order] |
| relatedEntity.role | Description du rôle de l’entité connexe. Valeur possible : commande de travaux Type de données : chaîne Stockée dans : table workOrder [wm_order] |
| Fête connexe | Liste des contacts pour le rendez-vous. Chaque contact est un objet dans le tableau. Type de données : tableau d’objets |
| relatedParty.@referredType | Type de client. Type de données : chaîne Stocké dans : Table du contact [customer_contact] |
| relatedParty.id | Sys_id du contact client associé à la commande de travaux. Type de données : chaîne Stocké dans : Table du contact [customer_contact] |
| relatedParty.name | Nom du contact client. Type de données : chaîne Stocké dans : Table du contact [customer_contact] |
| relatedParty.role | Rôle du contact client. Valeurs possibles :
Type de données : chaîne Stocké dans : Table du contact [customer_contact] |
| relatedPlace | Détails du lieu du rendez-vous associé. Type de données : objet |
| relatedPlace.@referredType | Adresse géographique du rendez-vous. Valeur possible : GeographicLocation. Type de données : chaîne Stocké dans : Table d’emplacement [cmn_location] |
| relatedPlace.id | Sys_id de l’emplacement. Type de données : chaîne Stocké dans : Table d’emplacement [cmn_location] |
| relatedPlace.name | Nom de l’emplacement associé au contact. Par exemple, 100 South Charles Street, Baltimore, MD. Type de données : chaîne Stocké dans : Table d’emplacement [cmn_location] |
| relatedPlace.role | Rôle du lieu de rendez-vous en tant qu’adresse d’intervention. Valeur possible : InterventionAddress Type de données : chaîne Stocké dans : Table d’emplacement [cmn_location] |
| succès | Marqueur indiquant si la demande a abouti. Valeurs possibles :
Type de données : booléennes |
| Fuseau horaire | Fuseau horaire utilisé lors de la réservation ou de la mise à jour du créneau de rendez-vous spécifié. Type de date : chaîne Format : format pays/ville ou zone, tel que États-Unis/Est |
| valide pour | Plage de dates pour laquelle le rendez-vous est valide. Type de données : objet |
| validFor.endDateTime | Date et heure de fin du rendez-vous. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
| validFor.startDateTime | Date et heure de début du rendez-vous. Type de données : chaîne Format : JJ-MM-AAAA 00:00:00. Par exemple, 2025-01-31 09:35:43. |
Demande cURL
L’exemple suivant montre comment créer une nouvelle réservation de rendez-vous.
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'Réponse :
{
"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"
}