Vue d'ensemble de l'API CCW
L'API REST de la CCW permet aux clients et aux partenaires de créer de nouvelles applications et de s'intégrer à la CCW de nouvelles manières pour améliorer leurs capacités en matière de gestion d'une main-d' œuvre temporaire.
En utilisant l'API REST de CCW, les clients et les partenaires peuvent créer de nouvelles applications et s'intégrer à CCW de nouvelles manières, afin d'améliorer leurs capacités en matière de gestion d'une main-d' œuvre temporaire. Les API de CCW sont des API RESTful basées sur HTTP qui utilisent OAuth 2.0 pour l'authentification et TLS 1.2 pour la sécurité de la couche transport. Cette documentation explique comment accéder à l'API de CCW et faire des demandes pour obtenir les données dont vous avez besoin.
Authentification
Les clients qui souhaitent accéder à l'API REST de la CCW peuvent enregistrer leur application utilisateur de l'API et recevoir les informations d'identification du client OAuth 2.0 à utiliser en combinaison avec deux couches de sécurité supplémentaires - Portées et Droits d'accès des utilisateurs/rôles - pour authentifier les demandes à l'API de la CCW.
| Exigence d'authentification | Description |
|---|---|
| Identifiants OAuth 2.0 | Comprend un ID client et un secret client |
| Portées | Les points d'extrémité pointant vers le module/la fonctionnalité spécifique au sein de la CCW demandée |
| Droits d'accès des utilisateurs/rôles | Affecté dans l'application CCW. Une fois que vous êtes authentifié par l'API (voir ci-dessous), une autre couche de sécurité détermine l'accès à la fonctionnalité spécifique demandée |
Jeton d'accès
La première étape pour accéder à l'API CCW consiste à demander un jeton d'accès en effectuant un appel avec les informations d'identification et la (les) portée(s) OAuth, comme dans l'exemple suivant :
curl -XPOST -H "Type de contenu : application/json" -d '{"client_id" :<<clientID>> "", "client_secret" : "<<secret>>",
"scope" :"ccw.candidate", "grant_type" :"client_credential"}' 'Auth_Url'
Pour « Auth_Url », utilisez ce qui suit, en fonction de votre environnement :
-
Sandbox : https://sso-stg1.coupahost.
com/as/token.oauth2 -
Production : https://sso-prd1.coupahost.
com/as/token.oauth2
Le serveur d'autorisation renvoie une charge utile JSON contenant les éléments suivants :
| Propriété | Valeur |
|---|---|
| token_type | Préfixé par « Porteur » |
| access_token | Chaîne à inclure dans l'en-tête d'autorisation lors de la création de demandes d'API |
| expires_in | Nombre de secondes jusqu'à l'expiration du jeton (généralement 3600, ou 1 heure) |
Points de terminaison de l'API
Inclure le jeton d'accès reçu dans les appels aux points de terminaison de l'API CCW. La demande est validée (ou renvoie une erreur - voir Codes d'erreur).
Format du point final : https ://<instance>/api/<resource path>
Exemples :
- Confirmation du candidat : https ://{hostname}/API/candidates/{id}/confirm
- Recherche de candidats : https ://{hostname}/API/candidates/search
- Recherche de travailleurs occasionnels : https ://{hostname}/API/contingent_workers
En-têtes de la demande
Les en-têtes de requête HTTP suivants sont requis :
| En-tête | Description |
|---|---|
| Autorisation | Utilisé pour demander l'accès aux appels API. Inclure le jeton porteur avec le schéma d'authentification : Porteur : <Token> |
| Type de contenu | Définir sur : application/json dans toutes les demandes. JSON est le seul format d'échange actuellement pris en charge |
| X-Correlation-id | Un identifiant de 36 caractères maximum, généré pour permettre le suivi et l'audit de la demande d'API |
Réponses d'erreur
Exemple de réponse en cas d'erreur
{
"error_code" : "chaîne",
"error_summary" : "chaîne",
"error_causes" : [
{
"error_sub_code" : "chaîne",
"error_sub_code_desc" : "chaîne"
}
]
}
Codes d'erreur
Veuillez vous reporter aux sections Codes d'erreur de chaque API CCW spécifique :
- API de recherche de candidat - Codes d'erreur
- API de confirmation du candidat - Codes d'erreur
- API de recherche CW - Codes d'erreur
Limitation du taux
Les API REST CCW n'ont pas de limitation de débit explicite, cependant, la limitation des demandes d'API est recommandée pour une réponse rapide. Bientôt, les points de terminaison individuels de l'API seront mis à jour avec la limitation de débit recommandée.
Meilleures pratiques
Vous trouverez ci-dessous quelques conseils pour obtenir les meilleurs résultats lors de la création d'applications sur CCW à l'aide de nos API REST :
- Éviter la validation du schéma : Les API CCW sont en constante évolution, avec de nouvelles propriétés facultatives ajoutées à l'API. À des fins d'extensibilité, les applications ne doivent pas effectuer de validation de schéma, ce qui peut déclencher des erreurs lorsque l'API envoie de nouvelles propriétés qui ne sont peut-être pas requises.
- Utiliser les codes d'état HTTP : Les applications grand public doivent s'appuyer sur les codes d'état HTTP pour gérer les erreurs d'API, plutôt que sur le contenu du corps de la réponse qui est à des fins de diagnostic et de journalisation uniquement.
- Évitez de dépendre de l'ordre des propriétés dans la réponse de l'API : L'API CCW ne prend en charge que le contenu JSON. L'ordre des propriétés dans une réponse API peut changer en raison de l'introduction de nouvelles propriétés.