BdC et modifications de BdC Intégration dans votre ERP

Instructions étape par étape pour intégrer vos bons de commande Coupa et vos modifications de bons de commande à votre ERP.

Introduction

Vous pouvez également télécharger ce document en tant que document Microsoft Word : Bons de commande 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

L'hypothèse dans ce document est que le numéro de bon de commande dans l'ERP est déterminé par le numéro de bon de commande Coupa. Cet article décrit les 3 options différentes pour intégrer les bons de commande 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 :

Pour les 3 options, les bons de commande Coupa sont poussés vers l'ERP en fonction de l'indicateur d'exportation.

En cas d'erreur, dans l'intégration d'un bon de commande, un changement manuel sera nécessaire sur le bon de commande dans l'interface utilisateur Coupa : ce changement réinitialisera l'indicateur d'exportation, et le bon de commande sera donc pris 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 exportation du BdC pour 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
    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
    integration-02.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 complet de l'intégration par type de document

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

Description

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

po-integration-01.png

Diagramme d'orchestration

po-orchistration.png

Étapes /détails des appels API

Étape 1

Obtenez la liste et les détails des bons de commande Coupa à créer/mettre à jour dans l'ERP.
Les critères de sélection comprennent l'indicateur d'exportation et le statut du BdC.
Le paramètre de requête show_deleted_lines peut être nécessaire pour gérer la mise à jour du bon de commande dans l'ERP

Méthode

OBTENIR

API

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

Query Params

filter=<your API filter name>
offset=10
exporté=false
show_deleted_lines=true*
status[in]=émis,annulé,fermé

Exemple d'URL

https ://<your instance hostname>/api/purchase_orders ?filter=<your API filter name>&offset=10&exported=false&show_deleted_lines=true&status[in]=émis,annulé,fermé

Échantillon de corps de la requête

S/O

Réponse Échantillon corporel

step-1.png

Remarque

* = show_deleted_lines=true est pour les changements de commande

Étape 2

Marquer le bon de commande individuel comme exporté

Méthode

METTRE

API

https ://<your instance hostname>/api/purchase_orders/<Purchase Order id>

Query Params

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

Exemple d'URL

https ://<your instance hostname>/api/purchase_orders/<Purchase Order id>?exported=true&fields=["id","exporté"]

Échantillon de corps de requête

S/O *

Échantillon du corps de



{

	"id" :<Purchase Order id>,

	"exporté" : vrai

	}
Remarque

* Pour cet appel, vous n'avez pas besoin d'une charge utile si vous incluez « ?export=true » dans l'URL. C'est là que se produit la création/mise à jour du bon de commande dans l'ERP.
 

Étape 3

Mettre à jour un champ personnalisé pour le rapport

Méthode

METTRE

API

https ://<your instance hostname>/api/purchase_orders/<Purchase Order id>

Params de requête

fields=["id","exporté",{ "custom_fields" : {} }]

Exemple d'URL

https ://<your instance hostname>/api/purchase_orders/<Purchase Order id>?fields=["id","exporté",{ "custom_fields" : {} }]

Query Body sample



{ "custom-fields" : {

		"<your custom-field name>": « Succès : Le BC a été correctement répliqué dans votre ERP"

}}

ou



{ "custom-fields" : {

		"<your custom-field name>": "Erreur : Le BC a été correctement répliqué dans votre ERP"

}}

Échantillon du corps de



{ "id" :<Purchase Order id>,

		"exporté" : true,

		"custom-fields" : {

				"<your custom-field name>": « Succès : Le BC a été correctement répliqué dans votre ERP"

}}

ou



{ "id" :<Purchase Order id>,

		"exporté" : true,

		"custom-fields" : {

				"<your custom-field name>": "Erreur : Le BC a été correctement répliqué dans votre ERP"

}}

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

Description

Dans ce scénario, pour chaque bon de commande, 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 :

 po-history-01.png

po-history-02.png

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

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

po-int-records-02.png

Diagramme d'orchestration

po-int-orchistration.png

Étapes /détails des appels API

Étape 1

Obtenez la liste et les détails des bons de commande Coupa à créer/mettre à jour dans l'ERP.
Les critères de sélection comprennent l'indicateur d'exportation et le statut du BdC.
Le paramètre de requête show_deleted_lines peut être nécessaire pour gérer la mise à jour du bon de commande dans l'ERP

Méthode

OBTENIR

API

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

Query Params

filter=<your API filter name>
offset=10
exporté=false
show_deleted_lines=true
status[in]=buyer_hold,issued,annulated,closed,soft_closed

Exemple d'URL

https ://<your instance hostname>/api/purchase_orders ?filter=<your API filter name>&offset=10&exported=false&show_deleted_lines=true&status[in]=buyer_hold,issued,annulated,closed,soft_closed

Échantillon de corps de requête

S/O

Réponse Échantillon corporel

step-2.png

 

Étape 2

Marquer le bon de commande individuel comme exporté

Méthode

METTRE

API

https ://<your instance hostname>/api/purchase_orders/<Purchase Order id>

Demander les paramètres

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

Exemple d'URL

https ://<your instance hostname>/api/purchase_orders/<Purchase Order id>?exported=true&fields=["id","exporté"]

Query Body sample

S/O

Réponse Échantillon corporel



{

		"id" :<Purchase Order id>,

		"exporté" : vrai

}

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

É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

Demander les paramètres

resolved=false
document-type=OrderHeader
document-id=<Purchase Order id>
fields=["id","document-id","status","resolved"]

Exemple d'URL

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

Échantillon de corps de requête

S/O

Échantillon de corps de



[

		{

				"id" :<Old Integration History Record id>,

				"document-id" :<Purchase Order 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

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

Query Body sample

S/O

Échantillon de corps de



[

		{

				"id" :<Old Integration History Record id>,

				"document-id" :<Purchase Order id>,

				"status" : "Erreur",

				"resolved" : true

		}

]

Étape 4a

Créer un historique d'intégration (succès)

Méthode

METTRE

API

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

Demander les paramètres

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

URL d'exemple

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

Échantillon de corps de la requête



{

		"document-type" : "OrderHeader",

		"document-id" :<Purchase Order id>,

		"statut-document" :"<Purchase Order 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 »

				}

		]

}

Échantillon du corps de



{

		"id" :<New Integration History Record id>,

		"document-id" :<Purchase Order id>,

		"statut" : "Réussi"

}

Étape 4b

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" : "OrderHeader",

		"document-id" :<Purchase Order id>,

		"statut-document" :"<Purchase Order status>",

		"contact-alert-type" : "Fonctionnel",

		"status" : "Erreur",

		"integration" : {"code" :"<Customer Integration id>"},

		"responses" : [

				{

						"code de réponse" : "Failure-CC",

						"response-message" : "Ligne 1 : Le centre de coûts CA234 est fermé pour la commande"

				},

				{

						"code de réponse" : "Date d'échec",

						"response-message" : « Ligne 2 : La date de livraison ne peut pas être dans le passé"

				}

		]

}

Échantillon de corps de



{

		"id" :<New Integration History Record id>,

		"document-id" :<Purchase Order id>,

		"status" : "Erreur"

}

Option 3 : Tirer parti de la surveillance complète de l'intégration 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 BC traités
  • Le nombre de succès et d'erreurs
  • La liste des Erreurs d'Intégration et leurs statuts (résolus ou non)

Pour chaque bon de commande, 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 pouvez surveiller toutes les exécutions d'intégration pour votre intégration à l'adresse : https :/<your instance hostname>//integrations<your integration id>//integration_runs.

po-api-integration-01.png

Utilisez la table de données d'erreur d'intégration de BC standard pour lister tous les BC avec une erreur d'intégration en attente de résolution. Il se trouve à l'adresse : https :/<your instance hostname>//integration_errors.
po-integration-errors.png

Utilisez la table de données d'historique d'intégration de BC standard pour lister tous les BC intégrés avec succès. Il se trouve à l'adresse : https :/<your instance hostname>//integration_history_records/purchase_orders.

Diagramme po-integration-records.png
d'orchestration

orchestration-3.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

Params de requête

S/O

Query Body sample



{

		"integration" : {

				"code" : "{{integration_code}}"

		}}

Réponse Échantillon corporel



{

		"id" :<Integration Run ID>,

		...

}

Étape 2

Obtenez la liste et les détails des bons de commande Coupa à créer/mettre à jour dans l'ERP.
Les critères de sélection comprennent l'indicateur d'exportation et le statut du BdC.
Le paramètre de requête show_deleted_lines peut être nécessaire pour gérer la mise à jour du bon de commande dans l'ERP

Méthode

OBTENIR

API

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

Params de requête

filter=<your API filter name>
offset=10
exporté=false
show_deleted_lines=true
status[in]=buyer_hold,issued,annulated,closed,soft_closed

Exemple d'URL

https ://<your instance hostname>/api/purchase_orders ?filter=<your API filter name>&offset=10&exported=false&show_deleted_lines=true&status[in]=buyer_hold,issued,annulated,closed,soft_closed

Query Body sample

S/O

Échantillon du corps de

step-3.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

Params de requête

S/O

Échantillon de corps de requête



{

		"total_records" : <Total Number of POs from Step 2>

}

Réponse Échantillon corporel



{

		"id" :<Integration Run ID>,

		...

}

Étape 4

Marquer le bon de commande individuel comme exporté

Méthode

METTRE

API

https ://<your instance hostname>/api/purchase_orders/<Purchase Order id>

Params de requête

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

URL d'exemple

https ://<your instance hostname>/api/purchase_orders/<Purchase Order id>?exported=true&fields=["id","exporté"]

Échantillon de corps de requête

S/O

Réponse Échantillon corporel



{

		"id" :<Purchase Order id>,

		"exporté" : vrai

}

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

É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=OrderHeader
document-id=<Purchase Order id>
fields=["id","document-id","status","resolved"]

Exemple d'URL

https ://<your instance hostname>/api/integration_history_records ?resolved=false&document-type=OrderHeader&document-id=<Purchase Order id>&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" :<Purchase Order 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

Demander les paramètres

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" :<Purchase Order 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=OrderHeader
document-id=<Purchase Order id>

Exemple d'URL

https ://<your instance hostname>/api/integration_errors ?resolved=false&document-type=OrderHeader&document-id=<Purchase Order id>

Query Body sample

S/O

Échantillon de corps de



[

		{

				"id" :<Old Integration Error Record id>,

				"document-type" : "OrderHeader",

				"document-id" :<Purchase Order 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

Params de requête

S/O

Échantillon de corps de requête

S/O

Réponse Échantillon corporel



[

		{

				"id" :<Old Integration Error Record id>,

				"document-id" :<Purchase Order id>,

				"status" : "Erreur",

				"resolved" : true

				...

		}

]

Étape 7a

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

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

Query Body sample



{

		"document-type" : "OrderHeader",

		"document-id" :<Purchase Order id>,

		"statut-document" :"<Purchase Order 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 de corps



{

		"id" :<New Integration History Record id>,

		"document-id" :<Purchase Order id>,

		"status" : "Réussi"

}

Étape 7b

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" : "OrderHeader",

		"document-id" :<Purchase Order id>,

		"statut-document" :"<Purchase Order status>",

		"contact-alert-type" : "Fonctionnel",

		"statut" : "Erreur",

		"integration-run-id" : "<Integration Run ID>",

		"responses" : [

				{

						"code de réponse" : "Failure-CC",

						"response-message" : "Ligne 1 : Le centre de coûts CA234 est fermé pour la commande"

				},

				{

						"code de réponse" : "Date d'échec",

						"response-message" : « Ligne 2 : La date de livraison ne peut pas être dans le passé"

				}

		]

}

Échantillon du corps de



{

		"id" :<New Integration Error Record id>,

		"document-id" :<Purchase Order id>,

		"status" : "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

Params de requête

S/O

Échantillon de corps de la requête

S/O

Réponse Échantillon corporel



{

		"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

Params de requête

S/O

Échantillon de corps de requête

S/O

Réponse Échantillon corporel



{

		"id" :<Integration Run ID>,

		"status" : "échec"

		...

}

 

  • Table des matières