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	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 { "id": "1e7ca4e6-8b69-c166-90a5-d4b587bd2db4", "name": "file.pdf", "entity": "entity_identifier" }
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/
        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'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