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:

  1. un appel POST permet de soumettre un fichier a Conciliator. En retour Conciliator fournit un ID identifiant le fichier

  2. lorsque le fichier est traité, Conciliator envoi un appel POST en spécifiant l'identifiant du fichier dont le traitement est terminé

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

https://app.expert.conciliator.ai/api/v0/files/upload

Header

Authorization la clé d'API

Method

POST

Body

multipart/form-data:

  • file

  • entity: identifiant du dossier

Response Code

200: OK

Response

JSON (extrait)

{
"files":
[
{
"id": "1e7ca4e6-8b69-c166-90a5-d4b587bd2db4",
"name": "file.pdf"
}
]
}

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

Authorization la clé d'API

Method

POST

Body

JSON

{
"file":
{
"id": "1e7ca4e6-8b69-c166-90a5-d4b587bd2db4",
"name": "file.pdf"
}
}

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

https://app.expert.conciliator.ai/api/v0/files/<file_id>/download

Header

Authorization la clé d'API

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/
incomplete/
unreadable/
...
other/
bank/
misc/
...

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": "",
"subType": "",
"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'objet document indique la raison du rejet lorsqu'il s'agit d'une facture (par exemple incomplete s'il manque une page ou illegible 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

Avez-vous trouvé votre réponse?