{"openapi":"3.1.0","info":{"title":"API Dûment","version":"1.3.0","description":"Factures, paiements et dossiers de recouvrement amiable B2B. Clés dum_live_ (réel) et dum_test_ (simulation). Les clés cabinet précisent la société visée avec l'en-tête Dument-Company. Webhooks : payment.received, dispute.opened, payment_plan.accepted, case.opened, case.closed, reminder.sent, promise.created."},"servers":[{"url":"https://dument.eu/api/public/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"Page":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"has_more":{"type":"boolean"},"next_offset":{"type":["integer","null"]}}},"Debtor":{"type":"object","required":["legal_name"],"properties":{"legal_name":{"type":"string","minLength":1,"maxLength":200},"siren":{"type":"string","pattern":"^\\d{9}(\\d{5})?$"},"vat_number":{"type":"string","maxLength":20},"email":{"type":"string","format":"email","maxLength":255},"phone":{"type":"string","maxLength":30},"address":{"type":"string","maxLength":300},"postal_code":{"type":"string","maxLength":10},"city":{"type":"string","maxLength":100},"external_ref":{"type":"string","maxLength":100}}},"InvoiceCreate":{"type":"object","required":["debtor","invoice"],"properties":{"debtor":{"$ref":"#/components/schemas/Debtor"},"invoice":{"type":"object","required":["number","issue_date","due_date","amount_cents"],"properties":{"number":{"type":"string","minLength":1,"maxLength":64},"issue_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"AAAA-MM-JJ"},"due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"AAAA-MM-JJ ; postérieure ou égale à issue_date (contrôle effectué par l'API)."},"amount_cents":{"type":"integer","minimum":1,"maximum":100000000000},"currency":{"type":"string","const":"EUR","default":"EUR"},"pdf_url":{"type":"string","format":"uri","maxLength":2000}}},"auto_launch":{"type":"boolean","default":true}}},"PaymentCreate":{"type":"object","required":["amount_cents"],"anyOf":[{"required":["invoice_id"]},{"required":["invoice_number"]}],"description":"invoice_id ou invoice_number requis ; si les deux sont fournis, invoice_id est utilisé.","properties":{"invoice_id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string","minLength":1,"maxLength":64},"amount_cents":{"type":"integer","minimum":1,"maximum":100000000000},"received_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"AAAA-MM-JJ ; aujourd'hui par défaut, aucune date future (contrôle effectué par l'API)."},"method":{"type":"string","enum":["virement","carte","cheque","prelevement","autre"],"default":"virement"},"reference":{"type":"string","maxLength":140}}},"ClientUpdate":{"type":"object","minProperties":1,"additionalProperties":false,"description":"Seuls ces six champs sont modifiables. Chaînes nettoyées des espaces en début et fin. null efface une valeur ; un champ omis est conservé. Raison sociale, SIREN et tout autre champ refusés.","properties":{"email":{"type":["string","null"],"format":"email","maxLength":254},"phone":{"type":["string","null"],"maxLength":32},"address":{"type":["string","null"],"maxLength":300},"postal_code":{"type":["string","null"],"maxLength":16},"city":{"type":["string","null"],"maxLength":120},"external_ref":{"type":["string","null"],"maxLength":120}}}},"responses":{"Error":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"Company":{"name":"Dument-Company","in":"header","required":false,"description":"Facultatif, réservé aux clés cabinet : identifiant de la société visée (voir GET /companies). Sans cet en-tête, la société de la clé est utilisée. Société inaccessible ou clé non cabinet : 403.","schema":{"type":"string","format":"uuid"}},"Idem":{"name":"Idempotency-Key","in":"header","description":"POST/PATCH : réservation par clé et société, liée à la méthode, l'adresse et au corps JSON exact. 409 si demande différente ou en cours ; ne pas changer de valeur si le résultat reste incertain.","schema":{"type":"string","minLength":1,"maxLength":255}}}},"paths":{"/invoices":{"post":{"summary":"Envoyer une facture échue","security":[{"bearer":["invoices:write"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"$ref":"#/components/parameters/Idem"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Facture créée"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/invoices/{id}":{"get":{"summary":"Consulter une facture","security":[{"bearer":["invoices:read"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Facture"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/payments":{"post":{"summary":"Signaler un paiement","security":[{"bearer":["payments:write"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"$ref":"#/components/parameters/Idem"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentCreate"}}}},"responses":{"201":{"description":"Paiement enregistré"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"422":{"$ref":"#/components/responses/Error"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/invoices/{id}/cancel":{"post":{"summary":"Annuler une facture non réglée (arrête les relances si le dossier n'a plus de facture due)","security":[{"bearer":["invoices:write"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Idem"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":3,"maxLength":500}}}}}},"responses":{"200":{"description":"Facture annulée"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"422":{"$ref":"#/components/responses/Error"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/clients/{id}":{"patch":{"summary":"Mettre à jour les coordonnées d'un débiteur (raison sociale et SIREN non modifiables)","security":[{"bearer":["clients:write"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Idem"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientUpdate"}}}},"responses":{"200":{"description":"Débiteur mis à jour"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/cases/{id}/communications":{"get":{"summary":"Historique des communications d'un dossier","security":[{"bearer":["cases:read"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Liste paginée"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/companies":{"get":{"summary":"Lister les sociétés accessibles à la clé (clé cabinet : toutes les sociétés du cabinet)","security":[{"bearer":["cases:read"]}],"responses":{"200":{"description":"Sociétés","content":{"application/json":{"schema":{"type":"object","properties":{"cabinet":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}},"parameters":[{"$ref":"#/components/parameters/Company"}]}},"/cases":{"get":{"summary":"Lister les dossiers","security":[{"bearer":["cases:read"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"state","in":"query","schema":{"type":"string"}},{"name":"debtor_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Liste paginée","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/clients":{"get":{"summary":"Lister les débiteurs","security":[{"bearer":["clients:read"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"siren","in":"query","schema":{"type":"string"}},{"name":"external_ref","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Liste paginée","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/events":{"get":{"summary":"Lister les événements","security":[{"bearer":["events:read"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Liste paginée","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/disputes":{"get":{"summary":"Lister les contestations","security":[{"bearer":["disputes:read"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"case_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Liste paginée","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/payment-plans":{"get":{"summary":"Lister les échéanciers","security":[{"bearer":["cases:read"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"case_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Liste paginée","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}},"/promises":{"get":{"summary":"Lister les promesses","security":[{"bearer":["cases:read"]}],"parameters":[{"$ref":"#/components/parameters/Company"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"case_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Liste paginée","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"description":"Corps JSON supérieur à 1 Mo"},"429":{"description":"120 demandes par minute par clé","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"$ref":"#/components/responses/Error"}}}}}}