• Dernière modification le: 05 August 2021

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

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 :

  1. Une intégration dédiée pour chaque orchestration d'API que vous implémentez
    invoice-integration-01.png
  2. 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
    invoice-integration-contact.png
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.

invoices-01.png

Diagramme d'orchestration

orchestration-01.png

É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

response-01.png

É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égrationinvoice-int-hist-02.png

invoice-int-hist-01.png

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.

invoice-int-records-01.png

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é.

invoice-int-records-02.png

Diagramme d'orchestration

orchestration-02.png

É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

response-02.png

É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.

po-api-integration-01.png

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.

inoice-int-records-03.png

Diagramme d'orchestration

orchestration-03.png

É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

response-03.png

É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


Options de requête

21 October 2016

Découvrez comment utiliser les requêtes pour identifier et extraire rapidement les données dont vous avez besoin.

Actions spéciales et notes API

21 October 2016

Informations supplémentaires sur l'utilisation de l'API Coupa.

Différences entre XML et JSON dans Coupa

16 December 2016

API d'exécution d'intégration

24 April 2017

Utilisez cette API pour créer, interroger ou mettre à jour une exécution d'intégration, ainsi que pour mettre à jour le statut.

Une partie ou la totalité de cette page peut avoir été traduite par machine. Toutes nos excuses pour les inexactitudes.