Guide de migration de l’API REST d’image

Emburse Enterprise interrompra les anciennes API d’image de dépenses et de factures basées sur SOAP. Ce guide de transition aidera les clients à migrer vers la nouvelle API d’image basée sur REST. Il explique les modifications concernant l’authentification, répertorie les points de terminaison mis à jour et fournit des exemples pratiques pour récupérer des fichiers PDF et des fichiers image à l’aide de l’interface moderne de REST.

Pour connaître tous les détails sur la sécurité de l’API REST, consultez la FAQ sur la sécurité de la migration vers l’API REST d’image.

Prérequis

Avant de passer à l’API REST d’image, assurez-vous que les étapes de configuration suivantes ont été effectuées par l’équipe d’assistance d’Emburse et votre organisation.

1. Configuration requise par Emburse

Activer l’accès à l’API REST : Emburse doit activer le point de terminaison REST pour votre organisation.
Activer la gestion des clés API : Dans Autorisations d’accès, Emburse doit accorder l’autorisation d’utiliser l’écran Gestion des clés API.

2. Générer des clés API

Si votre organisation utilise déjà des API REST pour d’autres intégrations de données, vous pouvez ignorer cette étape et utiliser votre ou vos clés API existantes pour les environnements de production (PROD) et de test d’acceptation utilisateur (User Acceptance Testing, UAT).

Si votre organisation n’utilise pas encore d’API REST, un administrateur pourra suivre les étapes ci-dessous pour générer des clés API.

1. Dans le menu Paramètres administrateur, sélectionnez Sécurité > Gestion des clés API.

2. Cliquez sur GÉNÉRER UNE CLÉ API. La clé API générée sera copiée automatiquement dans le presse-papiers. Une fois que vous avez cliqué sur Copiée, la fenêtre se ferme et la clé ne sera plus disponible.

Voir Écran d’administration Gestion des clés API pour plus de détails.

3. API de factures uniquement : Affecter une Personne responsable du filet de sécurité de routage des factures

Les clients qui passent à l’API REST de factures doivent vérifier qu’une Personne responsable du filet de sécurité de routage des factures leur a été affectée.

Dans le menu Paramètres administrateur, cliquez sur Configuration Préférences du client > Routage d’approbation.

CPA - FindMeFixMe.png

Si personne n’est affecté à côté de « Personne responsable du filet de sécurité de routage des factures », cliquez sur Modifier et utilisez la liste déroulante pour sélectionner l’utilisateur approprié. Appuyez ensuite sur Enregistrer.

Principales différences en un coup d’œil

Le tableau ci-dessous utilise l’API de factures comme exemple des différences entre l’ancienne API d’image et la nouvelle API REST.

Caractéristique	Ancienne API d’image de facture	Nouvelle API d’image de facture
Authentification	identifiant utilisateur & Mot de passe (champs de formulaire : un, pw)	Clé API + Code client + Identifiant de chaîne (en-têtes HTTP)
Style de communication	Formulaire en plusieurs parties POST	RESTful GET avec paramètres de requête
URL de base	https://pt.ca1.chromeriver.com/receipts/doit	https://service.chromeriver.com/v1/invoice-api
Récupération d’images/PDF	method=getInvoiceImages	GET /factures/images/pdf
Type de contenu	multipart/form-data	application/json
Sécurité	Session basée sur les cookies + identifiants de formulaire	Authentification API sans état basée sur l’en-tête

Authentification dans la nouvelle API REST

En-têtes obligatoires

Remplacez les espaces réservés ci-dessous par les identifiants fournis à votre organisation par Emburse Enterprise.

x-api-key : [votre-clé-api]

customerCode : [votre-code-client]

chain-id : [votre-identifiant-de-chaîne]

Content-Type : application/json

Exemple de dépense : Récupération des reçus

Exemple de dépense dans l’ancienne API SOAP

curl --location ’https ://api.ca1.chromeriver.com/receipts/doit’ \

--form ’un="APIDemo"’ \

--form ’pw="xxxxx"’ \

--form ’method="getReceipts"’ \

--form ’invoiceID="050018911471"’

Exemple de dépense dans la nouvelle API REST

curl --location ’https ://service.chromeriver.com/expense-image-api/getReceipts ?reportID=050018911471’ \

--header ’x-api-key : 1a234b56-7c89-1234-5678-d9e1fghijk23’ \

--header ’customerCode : 0XX0’ \

--header ’chain-id : APIDemo’ \

--header ’Content-Type : application/json’

Options de paramètres de requête de dépense

Paramètre	Description
voucherInvoice	Numéro de facture du bon d’achat.
IDRapport	L’ID du rapport est un numéro à douze chiffres généré par Emburse Enterprise, qui commence par 0100. Faites en sorte d’omettre les tirets.
getMileageDetails	Si vrai, le PDF inclura les détails du kilométrage, y compris la carte et la distance, si la dépense a été créée à l’aide de Maps.
getImage	Si vrai, le PDF inclura des images des reçus joints au rapport.
getPDFReport	Si vrai, le PDF original est d’abord récupéré, si disponible.
getPDFReportWithNotes	Si vrai, le PDF original inclura des notes d’approbation.
imageFirst	Si vrai, les images seront récupérées avant les PDF.

Exemple de facture : Récupération d’images (PDF)

Exemple de facture dans l’ancienne API SOAP

curl --location ’https ://api.ca1.chromeriver.com/receipts/doit’ \

--form ’un="APIDemo"’ \

--form ’pw="xxxxx"’ \

--form ’method="getInvoiceImages"’ \

--form ’invoiceID="050018911471"’

Exemple de facture dans la nouvelle API REST

curl --location ’https ://service.chromeriver.com/v1/invoice-api/invoices/images/pdf ?imageFirst=true&invoiceId=050018911471&getPDFReport=true&getImage=true’ \

--header ’x-api-key : 1a234b56-7c89-1234-5678-d9e1fghijk23’ \

--header ’customerCode : 0XX0’ \

--header ’chain-id : APIDemo’ \

--header ’Content-Type : application/json’

Options de paramètres de requête d’image de facture

Paramètre	Description
invoiceId	L’Identifiant de facture à récupérer
getPDFReport	Si vrai, inclut un rapport PDF de la facture
getImage	Si vrai, inclut les images jointes
imageFirst	Si vrai, donne la priorité au renvoi de l’image avant le rapport

Mappage des anciennes méthodes vers les points de terminaison REST

Ancienne méthode SOAP	Point de terminaison API REST
getInvoiceImages	GET /v1/invoice-api/invoices/images/pdf
getInvoices	/v1/invoice-api/invoices
getLineItemReceipts	/expense-image-api/getLineItemReceipts
getLineItemReceiptsWithMileageDetails	/expense-image-api/getLineItemReceiptsWithMileageDetails
getLineItemVoucherInvoices	/expense-image-api/getLineItemVoucherInvoices
getReceipts	/expense-image-api/getReceipts
getReceiptsForXML	/expense-image-api/getReceiptsForXML
getReceiptsWithCoverPage	/expense-image-api/getReceiptsWithCoverPage
getVoucherInvoices	/expense-image-api/getVoucherInvoices
getVoucherInvoicesForXML	/expense-image-api/getVoucherInvoicesForXML

Test et validation

Pour tester l’API REST :

Utilisez des outils tels que Postman, curl ou Insomnia.
Fournissez tous les en-têtes requis, en particulier x-api-key et customerCode.
Vérifiez l’accès aux dépenses ou aux factures à l’aide des valeurs reportId ou invoiceId connues.

Si elle est authentifiée correctement, l’API renverra ce qui suit :

Flux PDF du rapport de dépenses ou de factures
Images associées (si disponibles)

Documentation de référence

Pour connaître tous les détails sur les points de terminaison, les paramètres d’entrée et la structure de réponse, reportez-vous aux pages officielles de Swagger :