Ce connecteur permet une intégration avec des plateformes tierces voulant bénéficier de la puissance de lecture de factures de Conciliator. Il permet d'une part d'envoyer un ou plusieurs fichiers de documents associés à un dossier et d'autre part de récupérer l'ensemble de ces documents découpés, triés et traités par Conciliator (donc PDF + données extraites en format électronique).
Ce connecteur peut fonctionner en parallèle des connecteurs habituels de sortie vers le logiciel comptable.
Principes
Le connecteur est basé sur des appels API REST permettant de gérer le caractère asynchrone du traitement de Conciliator:
un appel POST permet de soumettre un fichier a Conciliator. En retour Conciliator fournit un ID identifiant le fichier
lorsque le fichier est traité, Conciliator envoi un appel POST en spécifiant l'identifiant du fichier dont le traitement est terminé
un appel GET vers Conciliator, avec l'identifiant du fichier permet de récupérer l'ensemble des données et métadonnées des documents identifiés par Conciliator à partir du fichier, incluant les découpes, les bannettes et les données de la facture au format Factur-X
Configuration
Bearer (read-only): la clé d'API nécessaire pour l'utilisation du connecteur
Webhook URL: l'URL qui sera notifiée dès qu'un fichier sera traité par Conciliator. L'URL doit impérativement être sécurisée en HTTPS.
https://api.example.com/conciliator
Détails de l'API
Soumettre un fichier
L'API est identique au Connecteur d'entrée API REST. Voir xxx pour plus de détails.
URL | |
Header |
|
Method | POST |
Body | multipart/form-data:
|
Response Code | 200: OK |
Response | JSON (extrait) { Note : la réponse peut contenir plusieurs fichiers si le fichier téléversé est une archive. |
Recevoir la notification de fin de traitement
URL | URL du Webhook configuré dans les paramètres du connecteur |
Header |
|
Method | POST |
Body | JSON {
|
Response Code Attendue | 200: OK |
Afin de sécuriser l'appel, il est conseillé de vérifier le token passé dans le header.
Dans le cas ou le code réponse n'est pas 200, Conciliator ne réitérera pas son appel. L'application tierce pourra consulter l'état du document au bout de 48h avec l'appel suivant.
Dans le cas ou un des documents lié au fichier d'origine est modifié (changement de bannette, signalement d'une erreur), le webhook sera a nouveau appelé. L'intégralité des documents sera alors disponible, comportant les documents modifiés mais aussi les documents qui auraient pu être déjà récupérés.
Télécharger les documents
URL | |
Header |
|
Method | GET |
Path Parameters | file_id = file ID |
Response Code | 200: OK |
Response | Fichier ZIP |
Structure du fichier ZIP:
L'arborescence des fichiers PDF se calque sur l'arborescence des bannettes de l'interface graphique. Les fichiers PDF se trouvent dans un de ces répertoires.
description.json
invoice/
sale/
purchase/
rejected/
duplicate/
incomplete/
illegal/
illegible/
other/
bank/
bank_statement/
employee/
miscellaneous/
trash/
Les PDF dans les répertoires invoice/sale et invoice/purchase sont au format Factur-X. Ils comportent donc en pièce jointe un fichier XML contenant toutes les données extraites de la facture.
Structure du fichier de métadonnées:
Situé à la racine du fichier ZIP, un fichier JSON description.json
décrit le lien entre les pages du fichier initial, et les pages de chacun des documents issus de ce fichier.
Dans l'exemple ci-dessous, un fichier comportant trois pages a généré deux documents après traitement : une facture d'achat (pages 1 et 2) et un relevé de compte (page 3).
{
"files":
[
{
"id": "",
"name": "file.pdf",
"entity": "entity_identifier"
}
],
"documents":
[
{
"id": "1e7ca4e6-8b69-c166-976c-954e77aa1a56",
"name": "file_1-2.pdf",
"entity": "entity_identifier",
"pages":
[
{
"fileId": "1e7ca4e6-8b69-c166-90a5-d4b587bd2db4",
"filePageNumber": "1"
},
{
"fileId": "1e7ca4e6-8b69-c166-90a5-d4b587bd2db4",
"filePageNumber": "2"
}
],
"type": "invoice",
"subType": "purchase",
"reason": null,
"path": "invoice/purchase/file_1-2.pdf"
},
{
"id": "1e7ca4e6-8b69-c166-8ba8-b72c37105aaf",
"name": "file_3-3.pdf",
"entity": "entity_identifier",
"pages":
[
{
"fileId": "1e7ca4e6-8b69-c166-90a5-d4b587bd2db4",
"filePageNumber": "3"
}
],
"type": "other",
"subType": "bank",
"reason": null,
"path": "other/bank/file_3-3.pdf"
}
]
}
Notes :
Il est possible d'avoir plusieurs fichiers dans
files
si un ou plusieurs documents sont issus de fusions de pages provenant de différents fichiers.Le champ
reason
de l'objetdocument
indique la raison du rejet lorsqu'il s'agit d'une facture (par exempleincomplete
s'il manque une page ouillegible
si la facture n'est pas lisible). Dans les autres cas, il reste ànull
.
Codes de réponse:
200: OK
404: Identifiant de fichier inconnu
204: fichier en cours de traitement. Aucun document n'est disponible
206: résultats partiels, tous les documents du fichier n'ont pas encore été traités