API de la facture électronique Digitransys

Pour les transporteurs qui émettent leurs factures électroniques par leur propre plateforme agréée.

Votre société prépare ses factures dans Digitransys, puis votre plateforme agréée les émet vers vos clients. Digitransys ne se branche jamais chez vous : c'est votre logiciel qui vient chercher les factures, ou qui les reçoit automatiquement.

Tout se règle dans Digitransys, menu Facturation, bandeau « Facture électronique », bouton « Choisir… », en choisissant « J'émets avec ma propre plateforme agréée ». Trois moyens, cumulables :

Une facture est remise quand vous cliquez sur « Envoyer » dans Digitransys. Rien ne part sans ce clic.

Chaque facture n'est remise qu'une seule fois par moyen. Si un webhook ou un mail de dépôt échoue, un nouveau clic sur « Envoyer » ne relance que le moyen en échec. Le fichier électronique ne doit être émis qu'une fois par votre plateforme : sinon votre client recevrait deux factures.

Format des factures

• Fichier électronique : XML CII (UN/CEFACT D16B), norme EN 16931, profil français (règles BR-FR). Il est accepté tel quel par les plateformes agréées.
• PDF : la représentation lisible de la même facture.
• Un avoir suit le même chemin que les factures (type: "credit_note").

Clé API

Créer une clé

Seul le responsable de la société crée les clés, dans Facturation → « Choisir… » (bandeau « Facture électronique »). La clé (dts_live_…) n'est affichée qu'une seule fois : copiez-la aussitôt. Vous pouvez la révoquer à tout moment, et avoir jusqu'à 5 clés actives.

Une clé ne donne accès qu'aux factures de votre société, et seulement à celles que vous avez remises.

Adresse de l'API

https://uggbdiwaeqmdfhcarxrv.supabase.co/functions/v1/einvoice-api

Authentification

Authorization: Bearer dts_live_xxxxxxxxxxxxxxxx

L'en-tête X-Api-Key: dts_live_… est aussi accepté.

Lister les factures remises

GET /invoices?since=2026-10-01T00:00:00Z&limit=50

• since (facultatif) : factures remises après cette date (ISO 8601).
• limit : de 1 à 100 (50 par défaut).

Les factures arrivent dans l'ordre de remise. S'il en reste, next_since donne la valeur à passer en since pour la page suivante. Sinon, il vaut null.

Réponse :

{
  "data": [
    {
      "id": "8f0c…",
      "number": "F-2026-0042",
      "type": "invoice",
      "date": "2026-10-14",
      "due_date": "2026-11-13",
      "currency": "EUR",
      "amount_ht": 1250,
      "amount_tva": 250,
      "amount_ttc": 1500,
      "credited_invoice_number": null,
      "seller": { "name": "…", "siret": "…", "vat_number": "…" },
      "buyer": { "name": "…", "siret": "…", "vat_number": "…", "country_code": "FR" },
      "handed_off_at": "2026-10-14T09:12:30.000Z",
      "status": null,
      "status_at": null,
      "paid_in_digitransys": false
    }
  ],
  "next_since": null
}

Une facture, son fichier électronique, son PDF

GET /invoices/{id}
GET /invoices/{id}/xml     → application/xml (CII EN 16931)
GET /invoices/{id}/pdf     → application/pdf

Renvoyer le statut donné par votre plateforme

Pour que le statut s'affiche sur la facture dans Digitransys :

POST /invoices/{id}/status
Content-Type: application/json

{ "code": "fr:212", "occurred_at": "2026-10-20T08:00:00Z", "message": "facultatif" }

Codes acceptés : les statuts du cycle de vie officiel, de fr:200 à fr:213 (ou simplement 200 à 213). Les plus courants :

Digitransys affiche le statut le plus parlant : « Encaissée » l'emporte sur « Reçue », même si « Reçue » arrive après.

Erreurs

{ "error": { "code": "unauthorized", "message": "Clé API absente ou invalide." } }

Webhook

Indiquez une adresse https joignable depuis Internet. À chaque facture remise, Digitransys envoie :

POST <votre adresse>
Content-Type: application/json
Digitransys-Event-Id: <id de la facture>
Digitransys-Signature: t=1760432000,v1=5b1f…

{
  "id": "8f0c…",
  "type": "invoice.ready",
  "created_at": "2026-10-14T09:12:30.000Z",
  "data": {
    "invoice": { "…": "mêmes champs que GET /invoices/{id}" },
    "xml_filename": "Facture F-2026-0042 ….xml",
    "xml_base64": "PD94bWwg…",
    "pdf_filename": "Facture F-2026-0042 ….pdf",
    "pdf_base64": "JVBERi0…"
  }
}

• Répondez par un code 2xx dans les 10 secondes. Sinon la remise est notée en échec, et un nouveau clic sur « Envoyer » la relance.
• Dédoublonnez sur Digitransys-Event-Id, qui est l'identifiant de la facture. N'émettez jamais deux fois la même facture.
• Le bouton « Tester » envoie un évènement "type": "test", sans facture.

Vérifier la signature

Le secret de signature (whsec_…) est affiché au responsable dans la même fenêtre (Facturation → « Choisir… »). Vous pouvez le renouveler.

1. Lisez t et v1 dans l'en-tête Digitransys-Signature.
2. Calculez un HMAC-SHA256, avec votre secret, de la chaîne "<t>.<corps brut de la requête>", en hexadécimal.
3. Comparez-le à v1 (comparaison à temps constant), puis refusez si t a plus de 5 minutes.

Exemple (Node.js) :

const crypto = require("crypto");
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  return ok && Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
}

Adresse mail de dépôt

La plupart des plateformes agréées donnent une adresse où déposer ses factures par mail. Saisissez-la dans la même fenêtre (Facturation → « Choisir… »). À chaque facture remise, Digitransys y envoie un mail avec en pièces jointes :

• le fichier électronique XML (CII EN 16931) ;
• le PDF.

Vérifiez auprès de votre plateforme qu'elle accepte le format CII par mail.

Une question technique : support@digitransys.com