API Dûment v1

Créez une clé dans Paramètres › API et développeurs (administrateurs uniquement). Envoyez-la dans l'en-tête Authorization: Bearer …. Les clés dum_live_ écrivent réellement ; les clés dum_test_ valident vos requêtes et renvoient une réponse simulée (livemode: false) sans rien enregistrer ni contacter aucun débiteur.

Chaque appel autorisé apparaît dans le journal de la page Développeurs. Une clé révoquée est refusée immédiatement. Les droits actuels du créateur sont contrôlés à chaque demande : quitter une société retire l'accès ; un rôle lecture seule ne peut pas écrire. Les demandes sont limitées à 120 par minute et par clé, et les corps JSON à 1 Mo.

Une clé standard appartient à une seule société ; une clé cabinet permet de viser plusieurs sociétés accessibles à son créateur. Chaque clé porte des permissions ; sans choix à la création, elle les reçoit toutes. Une permission manquante renvoie une erreur 403.

Spécification OpenAPI 3.1 complète : /api/public/v1/openapi.json (importable dans Postman, Insomnia ou un générateur de client).

Ajoutez un en-tête Idempotency-Key de 1 à 255 caractères unique à chaque POST ou PATCH. Une nouvelle demande identique (même méthode, adresse et corps JSON) pour la même société restitue la réponse enregistrée avec Idempotent-Replayed: true. Une demande différente avec la même clé renvoie 409. Les clés cabinet peuvent réutiliser une valeur dans deux sociétés distinctes.

Deux demandes simultanées ne lancent pas deux opérations : la seconde renvoie 409 tant que la première n'est pas terminée. Si le résultat est incertain après une interruption, la réservation reste bloquée pour éviter un doublon ; vérifiez le résultat avant toute nouvelle clé. Les paiements et leur réponse sont enregistrés dans la même transaction.

Le débiteur est retrouvé par SIREN/SIRET, puis par votre référence client, puis par e-mail ; le nom seul ne suffit jamais. Sinon il est créé. Montants en centimes TTC, dates AAAA-MM-JJ.

Avec auto_launch (vrai par défaut), la facture rejoint le dossier ouvert du débiteur ou en ouvre un, et le recouvrement démarre selon votre scénario — uniquement si l'identité est certaine (SIREN fourni) et qu'un e-mail est connu. Sinon le dossier reste en attente dans l'application et case.not_launched_reason en donne la raison (identity_unverified, missing_email…).

JSON requis : debtor et invoice. Le débiteur exige legal_name (1 à 200 caractères). La facture exige number (1 à 64 caractères), issue_date, due_date et amount_cents (entier de 1 à 100 000 000 000). L'échéance doit être postérieure ou égale à l'émission. currency accepte uniquement EUR (valeur par défaut), pdf_url est facultative (URL valide, 2 000 caractères maximum) et auto_launch est facultatif (vrai par défaut).

curl -X POST https://dument.eu/api/public/v1/invoices \
  -H "Authorization: Bearer dum_live_..." \
  -H "Idempotency-Key: f-2026-001" \
  -H "Content-Type: application/json" \
  -d '{
    "debtor": { "legal_name": "Exemple SAS", "siren": "123456789",
                "email": "compta@exemple.fr", "external_ref": "CLI-042" },
    "invoice": { "number": "F-2026-001", "issue_date": "2026-09-01",
                 "due_date": "2026-10-01", "amount_cents": 120000 },
    "auto_launch": true
  }'

201 Created
{
  "livemode": true,
  "invoice_id": "8c1e…",
  "status": "echue",
  "debtor": { "id": "a42f…", "created": false, "matched_by": "siren" },
  "case": { "case_id": "d9b0…", "reference": "DOS-2026-0042",
            "state": "active", "launched": true, "not_launched_reason": null }
}

Renvoie le montant payé, le reste dû, le statut, une éventuelle contestation et l'état du dossier.

curl https://dument.eu/api/public/v1/invoices/8c1e… -H "Authorization: Bearer dum_live_..."

Indiquez un paiement reçu dans votre logiciel : il est inscrit au grand livre de la société, imputé sur la facture (jamais au-delà du reste dû ; l'excédent reste non imputé) et les relances devenues inutiles s'arrêtent. Paiement partiel accepté. Identifiez la facture par invoice_id ou invoice_number.

amount_cents est obligatoire : entier de 1 à 100 000 000 000. Au moins un identifiant est obligatoire : invoice_id (UUID valide) ou invoice_number (1 à 64 caractères). Si les deux sont fournis, invoice_id est utilisé. received_on est facultatif (AAAA-MM-JJ, aujourd'hui par défaut, aucune date future), method vaut virement par défaut et reference est facultative (140 caractères maximum).

curl -X POST https://dument.eu/api/public/v1/payments \
  -H "Authorization: Bearer dum_live_..." \
  -H "Idempotency-Key: pay-7781" \
  -H "Content-Type: application/json" \
  -d '{ "invoice_number": "F-2026-001", "amount_cents": 120000,
        "received_on": "2026-10-05", "method": "virement",
        "reference": "VIR SEPA 7781" }'

method : virement, carte, cheque, prelevement, autre. Réponse : payment_id, allocated_cents, unallocated_cents, invoice_status, invoice_outstanding_cents.

Corps JSON obligatoire et non vide. Seuls email, phone, address, postal_code, city et external_ref sont acceptés. Un champ omis est conservé ; null efface sa valeur. Les espaces en début et fin sont retirés.

Limites : e-mail valide, 254 caractères ; téléphone, 32 ; adresse, 300 ; code postal, 16 ; ville et référence externe, 120 chacun. La raison sociale, le SIREN et tout champ inconnu sont refusés (400). Les anciennes valeurs modifiées sont conservées dans l'historique.

curl -X PATCH https://dument.eu/api/public/v1/clients/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer dum_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "compta@exemple.fr", "phone": null }'

Trois listes en lecture, de la plus récente à la plus ancienne. Paramètres communs : limit (1 à 100, 25 par défaut) et offset. La réponse contient data, has_more et next_offset à repasser pour la page suivante.

GET /cases — filtres state (ex. active, paid, closed) et debtor_id.

curl "https://dument.eu/api/public/v1/cases?state=active&limit=10" \
  -H "Authorization: Bearer dum_test_..."

{ "data": [ { "case_id": "d9b0…", "reference": "DOS-2026-0042", "state": "active",
              "debtor_id": "a42f…", "opened_on": "2026-10-01", "closed_on": null,
              "closure_kind": null, "reminders_suspended": false,
              "next_action_on": "2026-10-08", "invoice_ids": ["8c1e…"] } ],
  "has_more": false, "next_offset": null }

GET /clients — filtres siren et external_ref.

curl "https://dument.eu/api/public/v1/clients?siren=552100554" \
  -H "Authorization: Bearer dum_test_..."

{ "data": [ { "debtor_id": "a42f…", "name": "Exemple Industrie SAS",
              "siren": "552100554", "vat_number": "FR12552100554",
              "external_ref": "pennylane:1842", "email": "compta@exemple.fr",
              "postal_code": "69002", "city": "Lyon", "country": "FR",
              "type": "entreprise" } ],
  "has_more": false, "next_offset": null }

Pagination reproductible : tant que has_more vaut true, rappelez la même URL avec offset=next_offset.

curl "https://dument.eu/api/public/v1/cases?state=paid&limit=25&offset=25" \
  -H "Authorization: Bearer dum_test_..."

GET /events?type=case.closed — un événement par dossier clos, avec le motif de clôture. Filtre since=AAAA-MM-JJ pour ne récupérer que les nouveautés depuis votre dernier passage.

curl "https://dument.eu/api/public/v1/events?type=case.closed&since=2026-10-01" \
  -H "Authorization: Bearer dum_test_..."

{ "data": [ { "event_id": "evt_closed_d9b0…", "type": "case.closed",
              "occurred_on": "2026-10-05",
              "case": { "case_id": "d9b0…", "reference": "DOS-2026-0042",
                        "debtor_id": "a42f…", "closure_kind": "paid",
                        "closure_reason": null } } ],
  "has_more": false, "next_offset": null }

Avec une clé de test, ces listes lisent les données réelles de la société sans jamais rien modifier.

Format : { "error": { "code", "message", "details"? } }

Dans Intégrations, ajoutez une adresse de réception (Zapier « Catch Hook », Make « Custom webhook » ou votre propre URL HTTPS). Dûment y envoie un POST JSON pour chaque événement : payment.received, dispute.opened, payment_plan.accepted, case.opened, case.closed, reminder.sent, promise.created.

{
  "id": "evt uuid (identique à chaque nouvel essai)",
  "type": "payment.received",
  "created_at": "2026-10-06T12:55:00Z",
  "company_id": "…",
  "data": { "case_id": "…", "case_reference": "DOS-2026-0032",
            "amount_cents": 150000, "currency": "EUR", "received_on": "2026-10-06" }
}

En-tête Dument-Signature: t=…,v1=… : HMAC-SHA256 de {t}.{corps} avec votre secret whsec_. Répondez en 2xx ; sinon Dûment réessaie après 1 min, 5 min, 30 min, 2 h, 12 h et 24 h. Utilisez id pour ignorer les doublons.

Pour protéger les destinations, les notifications sortantes sont limitées aux adresses de réception Make et Zapier autorisées. Les adresses personnalisées ne sont pas prises en charge ; leurs événements restent dans le journal sans être transmis.

Même pagination que les autres listes (limit, offset, réponse {data, has_more, next_offset}).

curl "https://dument.eu/api/public/v1/disputes?status=open&limit=10" \
  -H "Authorization: Bearer dum_live_..."

{
  "data": [{ "id": "…", "case_id": "…", "invoice_id": "…", "category": "montant",
             "status": "open", "opened_at": "2026-10-02T09:12:00Z" }],
  "has_more": false, "next_offset": null
}

Les connecteurs utilisent le même moteur que l'API : rapprochement du débiteur par SIREN, identifiant du logiciel puis e-mail, jamais par le nom seul ; une facture déjà connue n'est pas réimportée.

Synchronisation chaque matin avant les relances, et à la demande. Le reste à payer est repris : un règlement saisi dans le logiciel après l'import est enregistré comme paiement et arrête les relances. Après deux échecs consécutifs, les administrateurs reçoivent une notification.

Pour les cabinets d'expertise comptable : une clé cabinet agit sur toutes les sociétés où son créateur est membre (hors rôle lecture seule). Créez-la dans Paramètres › API et développeurs en cochant « Clé cabinet ».

Lister les sociétés accessibles — GET /companies (permission cases:read)

curl https://dument.eu/api/public/v1/companies \
  -H "Authorization: Bearer dum_test_…"

{ "cabinet": true, "data": [ { "company_id": "…", "name": "Société exemple SAS" } ] }

Agir pour une société : ajoutez l'en-tête facultatif Dument-Company: <company_id> pour viser une société précise. Sans cet en-tête, la société de la clé est utilisée, y compris avec une clé cabinet. Une société hors de votre périmètre, ou cet en-tête avec une clé standard, renvoie 403 ; un identifiant mal formé renvoie 400. Les droits, la facturation et le journal d'appels restent ceux de la société visée.

curl https://dument.eu/api/public/v1/cases \
  -H "Authorization: Bearer dum_test_…" \
  -H "Dument-Company: <company_id>"

• Correctif sécurité — 18 octobre 2026 — contrôle des droits actuels, réservations anti-doublon par société, paiements atomiques, limitation des demandes et du volume JSON.
• 1.3.0 — 17 octobre 2026 — schémas des factures et paiements alignés sur les corps JSON, contraintes de modification des clients et en-tête cabinet facultatif documentés ; aucun changement du comportement de l'API.
• Octobre 2026 — clé cabinet et GET /companies, annulation de facture, historique des communications, mise à jour des coordonnées d'un débiteur, événements case.opened, case.closed, reminder.sent et promise.created.
• Octobre 2026 — permissions par clé, listes des contestations, échéanciers et promesses, spécification OpenAPI, reprise des règlements depuis les connecteurs.
• Septembre 2026 — listes des dossiers, clients et événements ; webhooks sortants et mode test.
• Septembre 2026 — v1 : envoi de factures, consultation, signalement de paiement, idempotence.