FR icône globe
icône utilisateur
Sur cette page
  • Dernière modification le: 05 August 2021
Que pouvons-nous faire pour vous ? Produits Documentation produit Coupa Documentation technique sur l'intégration API Coupa Core Intégration des factures dans votre ERP

Intégration des factures dans votre ERP

Des instructions détaillées pour intégrer vos factures Coupa à votre ERP.

Introduction

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

Considérations générales sur la configuration API

Charge utile limitée : champs et filtres API

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

Pour faciliter les choses, Coupa utilise le concept de paramètres « fields » et de filtres API qui renvoient une réponse JSON ou XML limitée au lieu du schéma entier, 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 partons du principe que ce numéro de document ERP est un champ personnalisé dans l'en-tête de facture Coupa. Dans notre exemple , le champ personnalisé a cf_erp_invoice_number été créé avec le nom ERP Invoice Number. Cet article décrit les 3 différentes options d'intégration des factures Coupa dans votre ERP (pour la création et les mises à jour).

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

  • Option 1: Surveillance simple basée sur le ou les champs personnalisés que vous définissez dans l'en-tête de facture
  • Option 2: Surveillance avancée à l'aide des historiques d'intégration
  • Option 3: bénéficier d’une surveillance complète des intégrations Coupa

Pour les 3 options, les factures Coupa sont transmises à l'ERP en fonction de l'indicateur d'exportation. En cas d'erreur, dans l'intégration d'une facture, une modification manuelle sera requise sur la facture dans l'interface utilisateur de 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 vous suggère de contacter l'assistance Coupa pour lui demander d'activer cette option : Réinitialisezla dernière exportation de la facture à chaque modification. Ce paramètre s'applique uniquement à l'interface utilisateur. Les modifications apportées à l'API ne modifieront 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 devez créer :

  1. Une intégration dédiée pour chaque orchestration API que vous mettez en oeuvre
    invoice-integration-01.png
  2. Un ou plusieurs contacts d'intégration pour chaque intégration, qui seront alertés en cas d'échec d'intégration
    invoice-integration-contact.png
Conseil

Coupa suggère de contacter l'assistance Coupa pour lui demander d'activer cette option : Activer le lien vers l'historiquede l'intégration par typede 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 des champs personnalisés

Description

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

invoices-01.png

Diagramme d'orchestration

orchestration-01.png

Détails des étapes/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 incluent l' indicateur Export et le statut de la facture.

Méthode

OBTENIR

API

https://<your instance hostname>/api/invoices/

Paramètres de requête

fields=<your API filter name>
offset=10
exported=false
status[in]=approved,voided

URL exemple

https://<your instance hostname>/api/invoices?filter=<your API filter name>&offset=10&exported=false&status[in]=approved,voided

Exemple de corps de requête

S/O

Corps de réponse échantillon

response-01.png

Étape 2

Marquer la facture individuelle comme exportée

Méthode

METTRE

API

https :///api/invoices/

Paramètres de requête

exported=true
fields=["id","exported"]

URL exemple

https://<your instance hostname>/api/invoices/<Invoice id>?exported=true&fields=["id","exported"]

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

{
		"id": <Invoice id>,
		"exported": true
}

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

Paramètres de requête

fields=["id","exported",{ "custom_fields": {} }]

URL exemple

https://<your instance hostname>/api/invoices/<Invoice id>?fields=["id","exported",{ "custom_fields": {} }]

Exemple de corps de requête

 

{ 
		"id": <Invoice_id>,
		"exported": true,
		"custom-fields": {
		"cf-erp-invoice-number": "<Invoice number in the ERP>",
		"cf-integration-status": "Success: The Invoice was replicated in your ERP"
			}
	}

ou


{
		"custom-fields": {
		"cf-integration-status": "Failure: The Invoice could not be replicated in your ERP"
	}
}

Corps de réponse échantillon

 

{ 
		"id": <Invoice_id>,
		"exported": true,
		"custom-fields": {
				"cf-erp-invoice-number": "<Invoice number in the ERP>",
				"cf-integration-status": "Success: The Invoice was replicated in your ERP"
		}
}

ou


{
		"id": <Invoice id>,
		"exported": true,
		"custom-fields": {
				"cf-erp-invoice-number": null,
				"cf-integration-status": "Error[2] : The Invoice was properly replicated in your 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 historique d'intégration
  • Créer une alerte pour le contact d'intégration en cas d'erreur

Chaque document inclut les détails de l'historique d'intégrationinvoice-int-hist-02.png

invoice-int-hist-01.png

Utilisez la table de données de l'historique d'intégration des factures standard pour suivre le statut 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

Détails des étapes/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 incluent l' indicateur Export et le statut de la facture.

Méthode

OBTENIR

API

https://<your instance hostname>/api/invoices/

Paramètres de requête

filter=<your API filter name>
offset=10
exported=false
status[in]=approved,voided

URL exemple

https://<your instance hostname>/api/invoices?filter=<your API filter name>&offset=10&exported=false&status[in]=approved,voided

Exemple de corps de requête

S/O

Corps de réponse échantillon

response-02.png

Étape 2

Marquer la facture individuelle comme exportée

Méthode

METTRE

API

https://<your instance hostname>/api/invoices/<Invoice id>

Paramètres de requête

exported=true
fields=["id","exported"]

URL exemple

https://<your instance hostname>/api/invoices/<Invoice id>?exported=true&fields=["id","exported"]

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

{
		"id": <Invoice id>,
		"exported": true
}

C'est là que la création/mise à jour de la facture dans l'ERP se produit.

Étape 3a

Obtenir un historique d'intégration non résolu

Méthode

OBTENIR

API

https://<your instance hostname>/api/integration_history_records

Paramètres de requête

resolved=false
document-type=InvoiceHeader
document-id=<Invoice id>
fields=["id","document-id","status","resolved"]

URL exemple

https://<your instance hostname>/api/integration_history_records?resolved=false&document-type=InvoiceHeader&document-id=<Invoice id>&fields=["id","document-id","status","resolved"]

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

[
		{
				"id": <Old Integration History Record id>,
				"document-id": <Invoice id>,
				"status": "Error",
				"resolved": false
		}
]

Étape 3b

Résoudre l'historique d'intégration précédent

Méthode

METTRE

API

https://<your instance hostname>/api/integration_history_records/<Old Integration History Record id>/resolve

Paramètres de requête

fields=["id","document-id","status","resolved"]

URL exemple

https://<your instance hostname>/api/integration_history_records/<Old Integration History Record id>/resolve?fields=["id","document-id","status","resolved"]

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

[
		{
				"id": <Old Integration History Record id>,
				"document-id": <Invoice id>,
				"status": "Error",
				"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>

Paramètres de requête

fields=["id","exported",{ "custom_fields": {} }]

URL exemple

https://<your instance hostname>/api/invoices/<Invoice id>&fields=["id","exported",{ "custom_fields": {} }]

Exemple de corps de requête

 

{
		"custom-fields": {
		"cf-erp-invoice-number": "<Invoice number in the ERP>"
		}
}

Corps de réponse échantillon

 

{
		"id": <Invoice id>,
		"exported": true,
		"custom-fields": {
		"cf-erp-invoice-number": "<Invoice number in the ERP>"
		}
}

Étape 4b

Créer un historique d'intégration (réussite)

Méthode

METTRE

API

https://<your instance hostname>/api/integration_history_records

Paramètres de requête

fields=["id","document-id","status"]

URL exemple

https://<your instance hostname>/api/integration_history_records?fields=["id","document-id","status"]

Exemple de corps de requête

 

{
		"document-type": "InvoiceHeader",
		"document-id": <Invoice id>,
		"document-status":"<Invoice status>",
		"contact-alert-type": "Functional",
		"status": "Success",
		"integration": {"code":"<Customer Integration id>"},
		"responses": [
				{
						"response-code": "Success-1234",
						"response-message": "The integration in the ERP went well"
				}
		]
}

Corps de réponse échantillon

 

{
		"id": <New Integration History Record id>,
		"document-id": <Invoice id>,
		"status": "Success"
}

É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

Paramètres de requête

fields=["id","document-id","status"]

URL exemple

https://<your instance hostname>/api/integration_history_records/create_alert?fields=["id","document-id","status"]

Exemple de corps de requête

 

{
		"document-type": "InvoiceHeader",
		"document-id": <Invoice id>,
		"document-status":"<Invoice status>",
		"contact-alert-type": "Functional",
		"status": "Error",
		"integration": {"code":"<Customer Integration id>"},
		"responses": [
				{
						"response-code": "Failure-CC",
						"response-message": "Header: Period is currently closed for Booking"
				},
				{
				"response-code": "Failure-CC",
				"response-message": "Line 1: Cost center CA234 is closed for invoicing"
				}
		]
}

Corps de réponse échantillon

 

{
		"id": <New Integration History Record id>,
		"document-id": <Invoice id>,
		"status": "Error"
}

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

Description

Dans ce scénario, nous créons une exécution d'intégration qui suit

  • Statut de l'intégration (en attente/démarrée/en erreur/réussie/échouée)
  • Nombre total de factures traitées
  • Le nombre de succès et d'erreurs
  • La liste des erreurs d'intégration et leur statut (résolues ou non)

Pour chaque facture, nous :

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

Vous pourrez surveiller toutes les exécutions 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 la table de données d'erreurs d'intégration des factures standard pour répertorier toutes les factures avec des erreurs d'intégration en attente de résolution. Vous pouvez le trouver sur : https://<your instance hostname>/integration_errors.

inoice-int-records-03.png

Diagramme d'orchestration

orchestration-03.png

Détails des étapes/appels API

Étape 1

Créer une exécution d'intégration

Méthode

POSTE

API

https://<your instance hostname>/api/integration_runs

Paramètres de requête

S/O

Exemple de corps de requête

 

{
		"integration": {
				"code": "{{integration_code}}"
		}
}

Corps de réponse échantillon

 

{
		"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 incluent l' indicateur Export et le statut de la facture.

Méthode

OBTENIR

API

https://<your instance hostname>/api/invoices/

Paramètres de requête

filter=<your API filter name>
offset=10
exported=false
status[in]=approved,voided

URL exemple

https://<your instance hostname>/api/invoices?filter=<your API filter name>&offset=10&exported=false&status[in]=approved,voided

Exemple de corps de requête

S/O

Corps de réponse échantillon

response-03.png

Étape 3

Démarrer l'exécution d'intégration

Méthode

METTRE

API

https://<your instance hostname>/api/integration_runs/<Integration Run ID>/run

Paramètres de requête

S/O

Exemple de corps de requête

 

{
		"total_records": <Total Number of Invoices from Step 2>
}

Corps de réponse échantillon

 

{
		"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>

Paramètres de requête

exported=true
fields=["id","exported"]

URL exemple

https://<your instance hostname>/api/invoices/<Invoice id>?exported=true&fields=["id","exported"]

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

{
		"id": <Invoice id>,
		"exported": true
}

C'est là que la création/mise à jour de la facture dans l'ERP se produit.

Étape 5a

Obtenir un historique d'intégration non résolu

Méthode

OBTENIR

API

https://<your instance hostname>/api/integration_history_records

Paramètres de requête

resolved=false
document-type=InvoiceHeader
document-id=<Invoice id>
fields=["id","document-id","status","resolved"]

URL exemple

https://<your instance hostname>/api/integration_history_records?resolved=false&document-type=InvoiceHeader&document-id=<Invoice id>&fields=["id","document-id","status","resolved"]

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

[
		{
				"id": <Old Integration History Record id>,
				"document-id": <Invoice id>,
				"status": "Error",
				"resolved": false
		}
]

Étape 5b

Résoudre l'historique d'intégration précédent

Méthode

METTRE

API

https://<your instance hostname>/api/integration_history_records/<Old Integration History Record id>/resolve

Paramètres de requête

fields=["id","document-id","status","resolved"]

URL exemple

https://<your instance hostname>/api/integration_history_records/<Old Integration History Record id>/resolve?fields=["id","document-id","status","resolved"]

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

[
		{
				"id": <Old Integration History Record id>,
				"document-id": <Invoice id>,
				"status": "Error",
				"resolved": true
		}
]

Étape 6a

Obtenir enregistrement des erreurs d'intégration non résolues

Méthode

OBTENIR

API

https://<your instance hostname>/api/integration_errors

Paramètres de requête

resolved=false
document-type=InvoiceHeader
document-id=<Invoice id>

URL exemple

https://<your instance hostname>/api/integration_errors?resolved=false&document-type=InvoiceHeader&document-id=<Invoice id>

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

[
		{
				"id": <Old Integration Error Record id>,
				"document-type": ”InvoiceHeader”,
				"document-id": <Invoice id>,
				"status": "Error",
				"resolved": false
				...
		}
]

Étape 6b

Résoudre l'historique d'intégration précédent

Méthode

METTRE

API

https :///api/integration_errors//resolve

Paramètres de requête

S/O

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

[
		{
				"id": <Old Integration Error Record id>,
				"document-id": <Invoice id>,
				"status": "Error",
				"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>

Paramètres de requête

fields=["id","exported",{ "custom_fields": {} }]

URL exemple

https://<your instance hostname>/api/invoices/<Invoice id>?fields=["id","exported",{ "custom_fields": {} }]

Exemple de corps de requête

 

{
		"custom-fields": {
		"cf-erp-invoice-number": "<Invoice number in the ERP>"
		}
}

Corps de réponse échantillon

 

{
		"id": <Invoice id>,
		"exported": true,
		"custom-fields": {
				"cf-erp-invoice-number": "<Invoice number in the ERP>"
		}
}

Étape 7b

Créer un historique d'intégration (réussite)
Il doit faire référence à la série d'intégration

Méthode

METTRE

API

https://<your instance hostname>/api/integration_history_records

Paramètres de requête

fields=["id","document-id","status"]

URL exemple

https://<your instance hostname>/api/integration_history_records?fields=["id","document-id","status"]

Exemple de corps de requête

 

{
		"document-type": "InvoiceHeader",
		"document-id": <Invoice id>,
		"document-status":"<Invoice status>",
		"contact-alert-type": "Functional",
		"status": "Success",
		"integration": {"code":"<Customer Integration id>"},
		"integration-run": {"id":<Integration Run ID>},
		"responses": [
				{
						"response-code": "Success-1234",
						"response-message": "The integration in the ERP went well"
				}
		]
}

Corps de réponse échantillon

 

{
		"id": <New Integration History Record id>,
		"document-id": <Invoice id>,
		"status": "Success"
}

Étape 7c

Créer une erreur d'intégration et alerter le contact d'intégration
Il doit faire référence à la série d'intégration

Méthode

METTRE

API

https://<your instance hostname>/api/integration_errors/create_alert

Paramètres de requête

S/O

Exemple de corps de requête

 

{
		"document-type": "InvoiceHeader",
		"document-id": <Invoice id>,
		"document-status":"<Invoice status>",
		"contact-alert-type": "Functional",
		"status": "Error",
		"integration-run-id": "<Integration Run ID>",
		"responses": [
				{
						"response-code": "Failure-CC",
						"response-message": "Header: Period is currently closed for Booking"
				},
				{
						"response-code": "Failure-CC",
						"response-message": "Line 1: Cost center CA234 is closed for invoicing"
				}
		]
}

Corps de réponse échantillon

 

{
		"id": <New Integration Error Record id>,
		"document-id": <Invoice id>,
		"status": "Error"
		...
}

Étape 8

Terminer l'exécution d'intégration

Méthode

METTRE

API

https://<your instance hostname>/api/integration_runs/<Integration Run ID>/success

Paramètres de requête

S/O

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

{
		"id": <Integration Run ID>,
		"status": "successful"
		...
}

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

Étape x

Déclencher un échec pour l'exécution d'intégration

Méthode

METTRE

API

https://<your instance hostname>/api/integration_runs/<Integration Run ID>/fail

Paramètres de requête

S/O

Exemple de corps de requête

S/O

Corps de réponse échantillon

 

{
		"id": <Integration Run ID>,
		"status": "failed"
		...
}

Veuillez noter que certaines parties de ce contenu peuvent avoir été générées par traduction automatique.

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.

En savoir plus

Démarrez avec l'API

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

En savoir plus

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.

En savoir plus

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.

En savoir plus