Que pouvons-nous vous aider à trouver ? Produits Documentation produit Coupa Documentation technique sur l'intégration L'API Coupa Core Intégration des factures dans votre ERP

Intégration des factures dans votre ERP

Instructions étape par étape pour intégrer vos factures Coupa à votre ERP.

Introduction

Vous pouvez également télécharger ce document en tant que document Microsoft Word : Factures Coupa à ERP.docx

Considérations générales sur la configuration de l'API

Commencez avec l'API Coupa
Sécurité de la clé API (sera éventuellement obsolète)
Accès à l'API Open Connect (à partir de R29)
JSON/XML
GraphQL (à partir de R30)

Charge utile limitée : champs et filtres API

L'API de Coupa renvoie beaucoup de données par défaut (par exemple : objets complets pour les objets associés). Les charges utiles de retour de l'API peuvent être très grandes et donc lentes. Cela peut être un problème pour les clients qui n'ont pas besoin des données superflues, sans parler de la consommation inutile de ressources.

Pour faciliter les choses, Coupa a le concept du paramètre « champs » et des filtres API qui renvoient une réponse JSON ou XML limitée au lieu de l'ensemble du schéma et de toutes les associations pour un objet.

Cas d'utilisation décrits dans cet article

Les factures ont généralement un numéro interne dans l'ERP. Dans ce document, nous supposons que ce numéro de document ERP est un champ personnalisé dans l'en-tête de la facture Coupa. Dans notre exemple, le champ personnalisé cf_erp_invoice_number a été créé avec le nom ERP Invoice Number. Cet article décrit les 3 options différentes pour intégrer les factures Coupa dans votre ERP(pour la création et les mises à jour).

Ces options changeront la façon dont vous pouvez surveiller vos intégrations à partir de Coupa :

Option 1 : Surveillance simple basée sur le (s) champ(s) personnalisé (s) que vous définissez dans l'en-tête de facture
Option 2 : Surveillance avancée à l'aide des enregistrements de l'historique d'intégration
Option 3 : Tirer parti de la surveillance complète des intégrations Coupa

Pour les 3 options, les factures Coupa sont poussées vers l'ERP en fonction de l'indicateur d'exportation. En cas d'erreur, dans l'intégration d'une facture, une modification manuelle sera nécessaire sur la facture dans l'interface utilisateur Coupa : cette modification réinitialisera l'indicateur d'exportation, et la facture sera donc prise en compte lors de la prochaine exécution.

Conseil

Coupa suggère que vous contactiez le support Coupa pour qu'il active cette option : Réinitialiser la date de dernière date d'exportation de la facture lors de chaque modification. Ce paramètre s'applique uniquement à l'interface utilisateur. Les modifications apportées avec l'API ne modifient pas le statut Exporté.

Créer une intégration et un contact dédiés pour l'API

Pour les options 2 et 3, vous devrez créer :

Une intégration dédiée pour chaque orchestration d'API que vous implémentez
Un ou plusieurs contact(s) d'intégration pour chaque intégration, qui sera (seront) alerté (s) en cas d'échec de l'intégration

Conseil

Coupa suggère que vous contactiez le support Coupa pour qu'il active cette option : Activer le lien vers l'historique d'intégration selon le type de document. Ce paramètre ajoute un lien dans la page de configuration pour afficher l'historique d'intégration complet par type de document.

Option 1 : Surveillance simple basée sur le (s) champ(s) personnalisé (s)

Description

Dans ce scénario, pour chaque facture, nous ajoutons le statut d'intégration actuel dans un ou plusieurs champs personnalisés d'en-tête de facture. Nous avons ajouté le champ personnalisé cf-integration-status créé avec le nom Integration Status. Utilisez le tableau de données de facture standard pour suivre l'état d'intégration de vos documents à cette URL : https ://<your instance hostname>/factures.

Diagramme d'orchestration

Étapes /détails des appels API

Étape 1	Obtenez la liste et les détails des factures Coupa à créer/mettre à jour dans l'ERP. Les critères de sélection comprennent l'indicateur d'exportation et le statut de la facture.
Méthode	OBTENIR
API	`https ://<your instance hostname>/api/invoices/`
Demander les paramètres	`fields=``<your API filter name>` `offset=10` `exporté=faux` `statut[in]=approuvé,annulé`
Exemple d'URL	`https ://<your instance hostname>/api/invoices ?filter=<your API filter name>&offset=10&exported=false&status[in]=approuvé,annulé`
Échantillon de corps de requête	S/O
Échantillon du corps de

Étape 2	Marquer la facture individuelle comme exportée
Méthode	METTRE
API	https ://<your instance hostname>/api/invoices/<Invoice id>
Params de requête	`exported=true` `fields=["id","exporté"]`
Exemple d'URL	`https ://<your instance hostname>/api/invoices/<Invoice id>?exported=true&fields=["id","exporté"]`
Échantillon de corps de requête	S/O
Échantillon du corps de	`{ "id" :<Invoice id>, "exporté" : vrai }`

Étape 3	Mettre à jour un champ personnalisé pour le rapport et le numéro de document ERP
Méthode	METTRE
API	`https ://<your instance hostname>/api/invoices/<Invoice id>`
Demander les paramètres	`fields=["id","exporté",{ "custom_fields" : {} }]`
Exemple d'URL	`https ://<your instance hostname>/api/invoices/<Invoice id>?fields=["id","exporté",{ "custom_fields" : {} }]`
Échantillon de corps de requête	`{ "id" :<Invoice_id>, "exporté" : true, "custom-fields" : { "cf-erp-invoice-number" : "<Invoice number in the ERP>", "cf-integration-status" : « Succès : La facture a été répliquée dans votre ERP" } }` ou `{ "custom-fields" : { "cf-integration-status" : « Échec : La facture n'a pas pu être répliquée dans votre ERP" } }`
Réponse Échantillon corporel	`{ "id" :<Invoice_id>, "exporté" : true, "custom-fields" : { "cf-erp-invoice-number" : "<Invoice number in the ERP>", "cf-integration-status" : « Succès : La facture a été répliquée dans votre ERP" } }` ou `{ "id" :<Invoice id>, "exporté" : true, "custom-fields" : { "cf-erp-invoice-number" : null, "cf-integration-status" : « Erreur[2] : La facture a été correctement répliquée dans votre ERP" } }`

Option 2 : Surveillance avancée à l'aide de l'historique d'intégration

Description

Dans ce scénario, pour chaque facture, nous :

Résoudre l'enregistrement d'historique d'intégration précédent pour le document
Créer un enregistrement d'historique d'intégration
Créer une alerte au contact d'intégration en cas d'erreur

Chaque document comprend les détails de l'historique d'intégration

Utilisez le tableau de données de l'historique d'intégration des factures standard pour suivre l'état d'intégration de vos documents. Vous pouvez le trouver sur : https ://<your instance hostname>/integration_history_records/invoices.

Vous pouvez utiliser un filtre sur le code de réponse pour différencier les documents répliqués avec succès des documents qui ont échoué.

Diagramme d'orchestration

Étapes /détails des appels API

Étape 1	Obtenez la liste et les détails des factures Coupa à créer/mettre à jour dans l'ERP. Les critères de sélection comprennent l'indicateur d'exportation et le statut de la facture.
Méthode	OBTENIR
API	`https ://<your instance hostname>/api/invoices/`
Query Params	`filter=<your API filter name> offset=10 exporté=faux statut[in]=approuvé,annulé`
Exemple d'URL	`https ://<your instance hostname>/api/invoices ?filter=<your API filter name>&offset=10&exported=false&status[in]=approuvé,annulé`
Échantillon de corps de requête	S/O
Échantillon de corps de

Étape 2	Marquer la facture individuelle comme exportée
Méthode	METTRE
API	`https ://<your instance hostname>/api/invoices/<Invoice id>`
Query Params	`exported=true` `fields=["id","exporté"]`
Exemple d'URL	`https ://<your instance hostname>/api/invoices/<Invoice id>?exported=true&fields=["id","exporté"]`
Échantillon de corps de requête	S/O
Réponse Échantillon corporel	`{ "id" :<Invoice id>, "exporté" : vrai }`

C'est ici que la création/mise à jour de la facture dans l'ERP a lieu.

Étape 3a	Obtenir l'enregistrement de l'historique d'intégration non résolu
Méthode	OBTENIR
API	`https ://<your instance hostname>/api/integration_history_records`
Params de requête	`resolved=false` `document-type=InvoiceHeader` `document-id=<Invoice id>` `fields=["id","document-id","status","resolved"]`
Exemple d'URL	`https ://<your instance hostname>/api/integration_history_records ?resolved=false&document-type=InvoiceHeader&document-id=<Invoice id>&fields=["id","document-id","status","resolved"]`
Échantillon de corps de la requête	S/O
Échantillon du corps de	`[ { "id" :<Old Integration History Record id>, "document-id" :<Invoice id>, "statut" : "Erreur", "resolved" : false } ]`

Étape 3b	Résoudre l'enregistrement précédent de l'historique d'intégration
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_history_records/<Old Integration History Record id>/résoudre`
Query Params	`fields=["id","document-id","status","resolved"]`
Exemple d'URL	`https ://<your instance hostname>/api/integration_history_records/<Old Integration History Record id>/resolve ?fields=["id","document-id","status","resolved"]`
Échantillon de corps de requête	S/O
Réponse Échantillon de corps	`[ { "id" :<Old Integration History Record id>, "document-id" :<Invoice id>, "status" : "Erreur", "resolved" : true } ]`

Étape 4a	Mettre à jour un champ personnalisé pour le numéro de document ERP (succès)
Méthode	METTRE
API	`https ://<your instance hostname>/api/invoices/<Invoice id>`
Demander les paramètres	`fields=["id","exporté",{ "custom_fields" : {} }]`
URL d'exemple	`https ://<your instance hostname>/api/invoices/<Invoice id>&fields=["id","exporté",{ "custom_fields" : {} }]`
Échantillon de corps de la requête	`{ "custom-fields" : { "cf-erp-invoice-number" : "<Invoice number in the ERP>" } }`
Réponse Échantillon corporel	`{ "id" :<Invoice id>, "exporté" : true, "custom-fields" : { "cf-erp-invoice-number" : "<Invoice number in the ERP>" } }`

Étape 4b	Créer un historique d'intégration (succès)
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_history_records`
Params de requête	`fields=["id","document-id","status"]`
Exemple d'URL	`https ://<your instance hostname>/api/integration_history_records ?fields=["id","document-id","status"]`
Échantillon de corps de requête	`{ "document-type" : "InvoiceHeader", "document-id" :<Invoice id>, "statut-document" :"<Invoice status>", "contact-alert-type" : "Fonctionnel", "status" : "Succès", "integration" : {"code" :"<Customer Integration id>"}, "responses" : [ { "code de réponse" : "Succès-1234", "response-message" : « L'intégration dans l'ERP s'est bien passée » } ] }`
Réponse Échantillon corporel	`{ "id" :<New Integration History Record id>, "document-id" :<Invoice id>, "status" : "Réussi" }`

Étape 4c	Créer un historique d'intégration (erreur) et alerter le contact d'intégration
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_history_records/create_alert`
Params de requête	`fields=["id","document-id","status"]`
Exemple d'URL	`https ://<your instance hostname>/api/integration_history_records/create_alert ?fields=["id","document-id","status"]`
Query Body sample	{ "document-type" : "InvoiceHeader", "document-id" :<Invoice id>, "statut-document" :"<Invoice status>", "contact-alert-type" : "Fonctionnel", "status" : "Erreur", "integration" : {"code" :"<Customer Integration id>"}, "responses" : [ { "code de réponse" : "Failure-CC", "response-message" : "En-tête : La période est actuellement fermée pour la réservation" }, { "code de réponse" : "Failure-CC", "response-message" : "Ligne 1 : Le centre de coûts CA234 est fermé pour facturation" } ] }
Échantillon du corps de	`{ "id" :<New Integration History Record id>, "document-id" :<Invoice id>, "statut" : "Erreur" }`

Option 3 : Tirer parti de la surveillance complète des intégrations Coupa

Description

Dans ce scénario, nous créons un cycle d'intégration qui suit

État de l'intégration (en attente/démarré/erroné/réussi/échoué)
Le nombre total de factures traitées
Le nombre de succès et d'erreurs
La liste des Erreurs d'Intégration et leurs statuts (résolus ou non)

Pour chaque facture, nous :

Résoudre l'enregistrement d'historique d'intégration précédent pour le document
Créer un enregistrement d'historique d'intégration
En cas d'erreur, créez une erreur d'intégration et une alerte au contact d'intégration

Vous serez en mesure de surveiller tous les cycles d'intégration pour votre intégration avec cette URL : https :/<your instance hostname>//integrations/<your integration id>/integration_runs.

Vous utiliserez le tableau de données d'erreur d'intégration de facture standard pour répertorier toutes les factures avec une erreur d'intégration en attente de résolution. Vous pouvez le trouver à l'adresse : https :/<your instance hostname>//integration_errors.

Diagramme d'orchestration

Étapes /détails des appels API

Étape 1	Créer une exécution d'intégration
Méthode	PUBLIER
API	`https ://<your instance hostname>/api/integration_runs`
Demander les paramètres	S/O
Échantillon de corps de requête	`{ "integration" : { "code" : "{{integration_code}}" } }`
Réponse Échantillon corporel	`{ "id" :<Integration Run ID>, ... }`

Étape 2	Obtenez la liste et les détails des factures Coupa à créer/mettre à jour dans l'ERP. Les critères de sélection comprennent l'indicateur d'exportation et le statut de la facture.
Méthode	OBTENIR
API	`https ://<your instance hostname>/api/invoices/`
Query Params	`filter=``<your API filter name>` `offset=10` `exporté=faux` `statut[in]=approuvé,annulé`
URL d'exemple	`https ://<your instance hostname>/api/invoices ?filter=<your API filter name>&offset=10&exported=false&status[in]=approuvé,annulé`
Échantillon de corps de requête	S/O
Réponse Échantillon de corps

Étape 3	Démarrer l'exécution de l'intégration
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_runs/<Integration Run ID>/run`
Demander les paramètres	S/O
Query Body sample	`{ "total_records" : <Total Number of Invoices from Step 2> }`
Échantillon du corps de	`{ "id" :<Integration Run ID>, ... }`

Étape 4	Marquer la facture individuelle comme exportée
Méthode	METTRE
API	`https ://<your instance hostname>/api/invoices/<Invoice id>`
Demander les paramètres	`exported=true` `fields=["id","exporté"]`
URL d'exemple	`https ://<your instance hostname>/api/invoices/<Invoice id>?exported=true&fields=["id","exporté"]`
Échantillon de corps de requête	S/O
Réponse Échantillon de corps	`{ "id" :<Invoice id>, "exporté" : vrai }`

C'est ici que la création/mise à jour de la facture dans l'ERP a lieu.

Étape 5a	Obtenir l'enregistrement de l'historique d'intégration non résolu
Méthode	OBTENIR
API	`https ://<your instance hostname>/api/integration_history_records`
Params de requête	`resolved=false` `document-type=InvoiceHeader` `document-id=``<Invoice id>` `fields=["id","document-id","status","resolved"]`
URL d'exemple	`https ://<your instance hostname>/api/integration_history_records ?resolved=false&document-type=InvoiceHeader&document-id=<Invoice id>&fields=["id","document-id","status","resolved"]`
Échantillon de corps de requête	S/O
Échantillon du corps de	`[ { "id" :<Old Integration History Record id>, "document-id" :<Invoice id>, "status" : "Erreur", "resolved" : false } ]`

Étape 5b	Résoudre l'enregistrement précédent de l'historique d'intégration
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_history_records/<Old Integration History Record id>/résoudre`
Params de requête	`fields=["id","document-id","status","resolved"]`
Exemple d'URL	`https ://<your instance hostname>/api/integration_history_records/<Old Integration History Record id>/resolve ?fields=["id","document-id","status","resolved"]`
Échantillon de corps de requête	S/O
Réponse Échantillon corporel	`[ { "id" :<Old Integration History Record id>, "document-id" :<Invoice id>, "status" : "Erreur", "resolved" : true } ]`

Étape 6a	Obtenir un enregistrement d'erreur d'intégration non résolu
Méthode	OBTENIR
API	`https ://<your instance hostname>/api/integration_errors`
Demander les paramètres	`resolved=false` `document-type=InvoiceHeader` `document-id=<Invoice id>`
URL d'exemple	`https ://<your instance hostname>/api/integration_errors ?resolved=false&document-type=InvoiceHeader&document-id=<Invoice id>`
Query Body sample	S/O
Échantillon du corps de	`[ { "id" :<Old Integration Error Record id>, "document-type" : "En-tête de facture", "document-id" :<Invoice id>, "status" : "Erreur", "resolved" : false ... } ]`

Étape 6b	Résoudre l'enregistrement précédent de l'historique d'intégration
Méthode	METTRE
API	https ://<your instance hostname>/api/integration_errors/<Old Integration Error Record id>/résoudre
Query Params	S/O
Échantillon de corps de requête	S/O
Réponse Échantillon corporel	`[ { "id" :<Old Integration Error Record id>, "document-id" :<Invoice id>, "statut" : "Erreur", "resolved" : true ... } ]`

Étape 7a	Mettre à jour un champ personnalisé pour le numéro de document ERP (succès)
Méthode	METTRE
API	`https ://<your instance hostname>/api/invoices/<Invoice id>`
Demander les paramètres	`fields=["id","exporté",{ "custom_fields" : {} }]`
Exemple d'URL	`https ://<your instance hostname>/api/invoices/<Invoice id>?fields=["id","exporté",{ "custom_fields" : {} }]`
Échantillon de corps de requête	`{ "custom-fields" : { "cf-erp-invoice-number" : "<Invoice number in the ERP>" } }`
Réponse Échantillon corporel	`{ "id" :<Invoice id>, "exporté" : true, "custom-fields" : { "cf-erp-invoice-number" : "<Invoice number in the ERP>" } }`

Étape 7b	Créer un historique d'intégration (Succès) Il doit faire référence à l'exécution d'intégration
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_history_records`
Query Params	`fields=["id","document-id","status"]`
Exemple d'URL	`https ://<your instance hostname>/api/integration_history_records ?fields=["id","document-id","status"]`
Échantillon de corps de requête	`{ "document-type" : "InvoiceHeader", "document-id" :<Invoice id>, "statut-document" :"<Invoice status>", "contact-alert-type" : "Fonctionnel", "status" : "Succès", "integration" : {"code" :"<Customer Integration id>"}, "integration-run" : {"id" :<Integration Run ID>}, "responses" : [ { "code de réponse" : "Succès-1234", "response-message" : « L'intégration dans l'ERP s'est bien passée » } ] }`
Réponse Échantillon corporel	`{ "id" :<New Integration History Record id>, "document-id" :<Invoice id>, "status" : "Réussi" }`

Étape 7c	Créer une erreur d'intégration et alerter le contact d'intégration Il doit faire référence à l'exécution d'intégration
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_errors/create_alert`
Query Params	S/O
Échantillon de corps de requête	{ "document-type" : "InvoiceHeader", "document-id" :<Invoice id>, "statut-document" :"<Invoice status>", "contact-alert-type" : "Fonctionnel", "statut" : "Erreur", "integration-run-id" : "<Integration Run ID>", "responses" : [ { "code de réponse" : "Failure-CC", "response-message" : "En-tête : La période est actuellement fermée pour la réservation" }, { "code de réponse" : "Failure-CC", "response-message" : "Ligne 1 : Le centre de coûts CA234 est fermé pour facturation" } ] }
Réponse Échantillon corporel	`{ "id" :<New Integration Error Record id>, "document-id" :<Invoice id>, "statut" : "Erreur" ... }`

Étape 8	Fin de l'exécution de l'intégration réussie
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_runs/<Integration Run ID>/success`
Demander les paramètres	S/O
Échantillon de corps de requête	S/O
Réponse Échantillon de corps	`{ "id" :<Integration Run ID>, "status" : "réussi" ... }`

En cas de défaillance générale pendant l'exécution de l'intégration.

Étape x	Échec d'élévation pour l'exécution d'intégration
Méthode	METTRE
API	`https ://<your instance hostname>/api/integration_runs/<Integration Run ID>/fail`
Demander les paramètres	S/O
Échantillon de corps de requête	S/O
Réponse Échantillon de corps	`{ "id" :<Integration Run ID>, "status" : "échec" ... }`

Articles associés

API Coupa Core

Notre API RESTful fournit un accès fiable pour lire, modifier ou intégrer vos données à la plateforme Coupa.

Démarrez avec l'API

Informations générales sur l'utilisation de l'API Coupa et quand vous devez envisager d'utiliser CSV.

Transition vers OAuth 2.0 et OIDC

Coupa désapprouve les API Keys héritées et nécessite l'utilisation d'OAuth 2.0 / OIDC. À partir de R34, aucune nouvelle clé API ne sera émise et les clés API ne seront plus prises en charge avec R35.

Ressources

Nous avons organisé nos points de terminaison API par type d'objet : données de référence, données transactionnelles et ressources partagées.