API ouverte de rendez-vous
L’API ouverte de rendez-vous 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)
- Gestion des services sur site (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 du 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 avoir le rôle sn_tmf_api.appointment_integrator.
Rendez-vous ouvert : GET /api/sn_tmf_api/appointment/searchTimeSlot
Renvoie les créneaux horaires qui ont été configurés dans la configuration du service de prise 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 |
|---|---|
| Néant |
| 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 uniquement à cette action HTTP 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 |
|---|---|
| Néant |
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é traitée avec succès. |
| 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 horaire 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 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.start_date_display | Affichez la date et l’heure de début du rendez-vous associé. Reflète 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.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 reste 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). Consultez la rubrique Appointment booking components pour plus de détails sur cette propriété. Valeurs possibles :
Type de données : booléennes |
| noApptAvailable | Marqueur indiquant s’il y a 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 |
| searchResult (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 de 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 |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| Néant |
| Nom | Description |
|---|---|
| catégorie | Requis. Sys_id du créateur d’enregistrement configuré pour la configuration du 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 de 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é connexe. Type de données : chaîne Table : workOrder [wm_order] 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 qui contient 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 associé. 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 uniquement à cette action HTTP 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 |
|---|---|
| Type de contenu | Format des 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é traitée avec succès. |
| 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 du 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 de 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 de rendez-vous. Utilisez ce lien dans un autre rendez-vous Ouvrez une demande 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 du 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 du rendez-vous. Type de données : tableau d’objets |
| relatedEntity.@referredType | Type d’élément ou de service. Type de données : chaîne Stocké dans : table workOrder [wm_order] |
| relatedEntity.id | Sys_id de l’entité connexe. Type de données : chaîne Stocké 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é 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 des contacts [customer_contact] |
| relatedParty.id | Sys_id du contact client associé à la commande de travaux. Type de données : chaîne Stocké dans : Table des contacts [customer_contact] |
| relatedParty.name | Nom du contact client. Type de données : chaîne Stocké dans : Table des contacts [customer_contact] |
| relatedParty.role | Rôle du contact client. Valeurs possibles :
Type de données : chaîne Stocké dans : Table des contacts [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] |
| réussite | 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 prise 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"
}