{ "openapi": "3.1.0", "info": { "title": "API de signature électronique — v1", "version": "1.0.0", "description": "Signature électronique simple et avancée (eIDAS), émargement de formation. Une enveloppe = une requête. Base : `https://app.exemple.fr/api/v1`. Authentification : `Authorization: Bearer sk_live_…` ou `sk_test_…` (bac à sable). Erreurs : `{ \"error\": { \"code\", \"message\" } }`." }, "servers": [ { "url": "https://preprod.signatik.com/api/v1" } ], "tags": [ { "name": "Enveloppes", "description": "Documents à signer, signataires, champs, cycle de vie" }, { "name": "Vérification", "description": "Retrouver la preuve d’un PDF par empreinte, même après purge" }, { "name": "Identités", "description": "Identités attestées, réutilisables (signature avancée)" }, { "name": "Mandats et lots", "description": "Mandats de signature et cachets d’organisation en lot" }, { "name": "Émargement", "description": "Sessions de formation, créneaux, feuille scellée" }, { "name": "Webhooks", "description": "Notifications signées HMAC" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Clé API : `sk_live_…` (production, facturée) ou `sk_test_…` (bac à sable, jamais facturé). Créée dans la console. Seul un hash est stocké." } }, "schemas": { "Envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "expired", "canceled" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "test = bac à sable (clé sk_test_), jamais facturé" }, "message": { "type": [ "string", "null" ] }, "signature_level": { "type": "string", "enum": [ "simple", "advanced", "organization_seal" ] }, "pades_level": { "type": [ "string", "null" ] }, "qualified_timestamp": { "type": "boolean" }, "mandate_id": { "type": [ "string", "null" ], "format": "uuid" }, "batch_id": { "type": [ "string", "null" ], "format": "uuid" }, "prepared": { "type": "boolean" }, "created_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "sealed_at": { "type": [ "string", "null" ], "format": "date-time" }, "retention_days": { "type": "integer" }, "documents_available": { "type": "boolean" }, "purge_after": { "type": [ "string", "null" ], "format": "date-time" }, "purged_at": { "type": [ "string", "null" ], "format": "date-time" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sha256": { "type": "string", "description": "Empreinte du PDF original" }, "sealed_sha256": { "type": [ "string", "null" ], "description": "Empreinte du PDF scellé" }, "revision": { "type": "integer" }, "current_sha256": { "type": [ "string", "null" ] }, "sealed_download_url": { "type": [ "string", "null" ], "format": "uri", "description": "Lien temporaire (1 h), null avant scellement ou après purge" } }, "required": [ "id", "name", "sha256", "sealed_sha256", "revision", "current_sha256", "sealed_download_url" ] } }, "evidence_download_url": { "type": [ "string", "null" ], "format": "uri", "description": "Dossier de preuve scellé (lien 1 h)" }, "signers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "order": { "type": "integer" }, "role": { "type": "string", "enum": [ "signer", "agent" ] }, "status": { "type": "string", "enum": [ "pending", "notified", "signed" ] }, "signed_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_url": { "type": [ "string", "null" ], "format": "uri", "description": "URL personnelle de signature (marque blanche : à injecter dans votre produit)" }, "signature": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "advanced", "organization_seal" ] }, "identity_id": { "type": [ "string", "null" ], "format": "uuid" }, "authentication": { "type": "array", "items": { "type": "string" } }, "authentication_used": { "type": "array", "items": { "type": "string" } }, "identity_confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "certificate_serial": { "type": [ "string", "null" ] }, "certificate_subject": { "type": [ "string", "null" ] }, "certificate_fingerprint_sha256": { "type": [ "string", "null" ] }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "timestamp": { "type": [ "object", "null" ], "properties": { "issuer": { "type": [ "string", "null" ] }, "serial": { "type": [ "string", "null" ] }, "gen_time": { "type": "string" }, "qualified": { "type": "boolean" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "issuer", "serial", "gen_time", "qualified", "provider" ] } }, "required": [ "level", "identity_id", "authentication", "authentication_used", "identity_confirmed_at", "certificate_serial", "certificate_subject", "certificate_fingerprint_sha256", "applied_at", "timestamp" ], "description": "Présent en signature avancée et cachet d’organisation" } }, "required": [ "id", "email", "name", "order", "role", "status", "signed_at", "sign_url" ] } } }, "required": [ "id", "name", "status", "mode", "message", "signature_level", "pades_level", "qualified_timestamp", "mandate_id", "batch_id", "prepared", "created_at", "expires_at", "completed_at", "sealed_at", "retention_days", "documents_available", "purge_after", "purged_at", "documents", "evidence_download_url", "signers" ] }, "CreateEnvelope": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "message": { "type": "string", "maxLength": 2000 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 90 }, "send": { "type": "boolean", "default": false }, "signature_level": { "type": "string", "enum": [ "simple", "advanced", "organization_seal" ], "default": "simple" }, "qualified_timestamp": { "type": "boolean", "default": true }, "mandate_id": { "type": "string", "format": "uuid" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "pdf_base64": { "type": "string", "minLength": 1 } }, "required": [ "name", "pdf_base64" ] }, "minItems": 1, "maxItems": 5 }, "signers": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "order": { "type": "integer", "minimum": 0, "maximum": 20, "default": 0 }, "phone": { "type": "string", "maxLength": 30 }, "authentication": { "type": "array", "items": { "type": "string", "enum": [ "otp_email", "otp_sms" ] }, "minItems": 1 }, "identity_id": { "type": "string", "format": "uuid" }, "identity": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "partner_attested", "remote_id_check", "france_identite" ] }, "given_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "family_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 }, "document_type": { "type": "string", "enum": [ "id_card", "passport", "residence_permit", "driving_licence", "other" ] }, "document_number_hash": { "type": "string", "pattern": "^(sha256:)?[a-f0-9]{64}$" }, "document_expires_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "verified_at": { "type": "string", "format": "date-time" }, "verified_by": { "type": "string", "maxLength": 200 }, "attestation_ref": { "type": "string", "maxLength": 200 }, "external_ref": { "type": "string", "maxLength": 200 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "required": [ "method", "given_name", "family_name" ] } }, "required": [ "email", "name" ] }, "minItems": 1, "maxItems": 10 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "document_index": { "type": "integer", "minimum": 0 }, "signer_index": { "type": "integer", "minimum": 0 }, "type": { "type": "string", "enum": [ "signature", "text", "date", "checkbox" ] }, "page": { "type": "integer", "minimum": 1 }, "x": { "type": "number", "minimum": 0, "maximum": 100 }, "y": { "type": "number", "minimum": 0, "maximum": 100 }, "width": { "type": "number", "minimum": 0.5, "maximum": 100 }, "height": { "type": "number", "minimum": 0.5, "maximum": 100 }, "value": { "type": "string", "maxLength": 1000 } }, "required": [ "document_index", "signer_index", "type", "page", "x", "y", "width", "height" ] }, "default": [] } }, "required": [ "name", "documents", "signers" ] }, "VerifyResult": { "type": "object", "properties": { "known": { "type": "boolean" }, "sha256": { "type": "string" }, "matches": { "type": "string", "enum": [ "original_document", "sealed_document", "signed_revision" ] }, "document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sha256": { "type": "string" }, "sealed_sha256": { "type": [ "string", "null" ] }, "current_sha256": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "sha256", "sealed_sha256", "current_sha256" ] }, "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "signature_level": { "type": "string" }, "pades_level": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "sealed_at": { "type": [ "string", "null" ], "format": "date-time" }, "documents_available": { "type": "boolean" } }, "required": [ "id", "name", "status", "signature_level", "pades_level", "completed_at", "sealed_at", "documents_available" ] }, "signers": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "actor": { "type": "string" }, "at": { "type": "string" }, "hash": { "type": "string" }, "prev_hash": { "type": [ "string", "null" ] } }, "required": [ "type", "actor", "at", "hash", "prev_hash" ] }, "description": "Chronologie chaînée par empreinte" }, "chain_valid": { "type": "boolean" }, "proof": { "type": "object", "additionalProperties": {}, "description": "Signature avancée : horodatages, mandat, chaîne de confiance" } }, "required": [ "known", "sha256" ] }, "VerifyRequest": { "type": "object", "properties": { "pdf_base64": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "Identity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "partner_attested", "remote_id_check", "france_identite" ] }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "expired", "deleted" ] }, "given_name": { "type": "string" }, "family_name": { "type": "string" }, "birth_date": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "document_type": { "type": [ "string", "null" ] }, "document_number_hash": { "type": [ "string", "null" ], "description": "Empreinte sha256 du numéro de pièce — jamais le numéro" }, "document_expires_on": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verified_by": { "type": [ "string", "null" ] }, "attestation_ref": { "type": [ "string", "null" ] }, "external_ref": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string" } }, "required": [ "id", "method", "status", "given_name", "family_name", "birth_date", "email", "phone", "document_type", "document_number_hash", "document_expires_on", "verified_at", "verified_by", "attestation_ref", "external_ref", "expires_at", "created_at" ] }, "CreateIdentity": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "partner_attested", "remote_id_check", "france_identite" ] }, "given_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "family_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 }, "document_type": { "type": "string", "enum": [ "id_card", "passport", "residence_permit", "driving_licence", "other" ] }, "document_number_hash": { "type": "string", "pattern": "^(sha256:)?[a-f0-9]{64}$" }, "document_expires_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "verified_at": { "type": "string", "format": "date-time" }, "verified_by": { "type": "string", "maxLength": 200 }, "attestation_ref": { "type": "string", "maxLength": 200 }, "external_ref": { "type": "string", "maxLength": 200 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "required": [ "method", "given_name", "family_name" ] }, "SigningMandate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "active", "revoked", "expired" ] }, "principal": { "type": "object", "properties": { "legal_name": { "type": "string" }, "siren": { "type": [ "string", "null" ] }, "is_merchant": { "type": "boolean" }, "representative": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "email": { "type": "string" } }, "required": [ "name", "role", "email" ] } }, "required": [ "legal_name", "siren", "is_merchant", "representative" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] } }, "scope": { "type": "array", "items": { "type": "string" } }, "valid_from": { "type": "string" }, "valid_until": { "type": "string" }, "envelope_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Enveloppe de l’acte de mandat, signée en avancé par le représentant" }, "document_sha256": { "type": [ "string", "null" ] }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string" } }, "required": [ "id", "status", "principal", "agents", "scope", "valid_from", "valid_until", "envelope_id", "document_sha256", "activated_at", "revoked_at", "created_at" ] }, "CreateSigningMandate": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "siren": { "type": "string", "pattern": "^\\d{9}$" }, "is_merchant": { "type": "boolean", "default": true }, "representative": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "role": { "type": "string", "maxLength": 100 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 }, "identity_id": { "type": "string", "format": "uuid" }, "identity": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "partner_attested", "remote_id_check", "france_identite" ] }, "given_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "family_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 }, "document_type": { "type": "string", "enum": [ "id_card", "passport", "residence_permit", "driving_licence", "other" ] }, "document_number_hash": { "type": "string", "pattern": "^(sha256:)?[a-f0-9]{64}$" }, "document_expires_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "verified_at": { "type": "string", "format": "date-time" }, "verified_by": { "type": "string", "maxLength": 200 }, "attestation_ref": { "type": "string", "maxLength": 200 }, "external_ref": { "type": "string", "maxLength": 200 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "required": [ "method", "given_name", "family_name" ] } }, "required": [ "name", "email", "phone" ] } }, "required": [ "legal_name", "representative" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 } }, "required": [ "name", "email", "phone" ] }, "minItems": 1, "maxItems": 20 }, "scope": { "type": "array", "items": { "type": "string", "enum": [ "cmad", "contrat_mission", "avenant", "releve_heures", "autre" ] }, "minItems": 1 }, "valid_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "valid_until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "message": { "type": "string", "maxLength": 2000 } }, "required": [ "principal", "agents", "scope", "valid_from", "valid_until" ] }, "SealBatch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "authorized", "applied", "expired", "canceled" ] }, "mandate_id": { "type": "string", "format": "uuid" }, "principal": { "type": "string" }, "agent": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ] }, "envelope_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "batch_sha256": { "type": "string", "description": "Empreinte de la liste des empreintes : l’ajout d’un document invalide le jeton" }, "authorization_url": { "type": [ "string", "null" ], "format": "uri" }, "expires_at": { "type": "string" }, "authorized_at": { "type": [ "string", "null" ], "format": "date-time" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string" } }, "required": [ "id", "status", "mandate_id", "principal", "agent", "envelope_ids", "batch_sha256", "authorization_url", "expires_at", "authorized_at", "applied_at", "created_at" ] }, "CreateSealBatch": { "type": "object", "properties": { "mandate_id": { "type": "string", "format": "uuid" }, "agent_email": { "type": "string", "format": "email" }, "envelope_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 500 }, "expires_in_hours": { "type": "integer", "minimum": 1, "maximum": 168, "default": 72 } }, "required": [ "mandate_id", "envelope_ids" ] }, "AttendanceSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "modality": { "type": "string", "enum": [ "onsite", "remote", "hybrid" ] }, "location": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "closed", "sealed" ] }, "trainer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri", "description": "Espace formateur (ouverture et fermeture des créneaux, QR code)" } }, "required": [ "name", "email", "url" ] }, "retention_days": { "type": "integer" }, "created_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "sealed_at": { "type": [ "string", "null" ], "format": "date-time" }, "sheet_sha256": { "type": [ "string", "null" ] }, "sheet_download_url": { "type": [ "string", "null" ], "format": "uri" }, "evidence_download_url": { "type": [ "string", "null" ], "format": "uri" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "starts_at": { "type": "string" }, "ends_at": { "type": "string" }, "module": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "scheduled", "open", "closed" ] }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "trainer_signed_at": { "type": [ "string", "null" ], "format": "date-time" }, "present": { "type": "integer" }, "expected": { "type": "integer" }, "rate": { "type": "integer", "description": "Taux de présence, en %" } }, "required": [ "id", "label", "starts_at", "ends_at", "module", "status", "opened_at", "closed_at", "trainer_signed_at", "present", "expected", "rate" ] } }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "external_ref": { "type": [ "string", "null" ] }, "sign_url": { "type": "string", "format": "uri", "description": "Lien personnel d’émargement, valable toute la session" }, "marks": { "type": "array", "items": { "type": "object", "properties": { "slot_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "method": { "type": "string" }, "signed_at": { "type": "string" }, "out_of_window": { "type": "boolean" } }, "required": [ "slot_id", "status", "method", "signed_at", "out_of_window" ] } } }, "required": [ "id", "name", "email", "external_ref", "sign_url", "marks" ] } }, "marks_count": { "type": "integer" } }, "required": [ "id", "name", "reference", "modality", "location", "status", "trainer", "retention_days", "created_at", "closed_at", "sealed_at", "sheet_sha256", "sheet_download_url", "evidence_download_url", "slots", "attendees", "marks_count" ] }, "CreateAttendanceSession": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "reference": { "type": "string", "maxLength": 100 }, "modality": { "type": "string", "enum": [ "onsite", "remote", "hybrid" ], "default": "onsite" }, "location": { "type": "string", "maxLength": 200 }, "trainer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email" } }, "required": [ "name" ] }, "slots": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "module": { "type": "string", "maxLength": 200 } }, "required": [ "label", "starts_at", "ends_at" ] }, "minItems": 1, "maxItems": 200 }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email" }, "external_ref": { "type": "string", "maxLength": 100 } }, "required": [ "name" ] }, "minItems": 1, "maxItems": 500 }, "retention_days": { "type": "integer", "minimum": 30, "maximum": 3650, "default": 1095 }, "notify": { "type": "boolean", "default": true } }, "required": [ "name", "trainer", "slots", "attendees" ] }, "AddAttendee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email" }, "external_ref": { "type": "string", "maxLength": 100 } }, "required": [ "name" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "active": { "type": "boolean" }, "secret": { "type": "string" } }, "required": [ "id", "url", "active", "secret" ] }, "CreateWebhookEndpoint": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } }, "parameters": {} }, "paths": { "/envelopes": { "post": { "tags": [ "Enveloppes" ], "summary": "Créer une enveloppe (et l’envoyer)", "description": "Une enveloppe = une requête : PDF en base64, signataires, champs. `send: true` envoie immédiatement. Le niveau se choisit par `signature_level` : `simple` (défaut), `advanced` (identité attestée obligatoire, sinon `422 identity_required`) ou `organization_seal` (cachet sous mandat, signé en lot). En libre-service, le coût maximal est réservé à l’envoi (`402 insufficient_credits` sinon), débité à la complétion, rendu à l’annulation ou à l’expiration. Scope `envelopes:write`.", "security": [ { "apiKey": [] } ], "requestBody": { "description": "Enveloppe à créer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvelope" } } } }, "responses": { "201": { "description": "Enveloppe créée, avec `sign_url` par signataire", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Corps invalide, PDF invalide, index de champ hors limites", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "402": { "description": "Crédits insuffisants (libre-service)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Corps trop volumineux (5 PDF de 10 Mo max)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "`identity_required`, `phone_required`, `mandate_required`, `agent_not_in_mandate`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Enveloppes" ], "summary": "Lister les enveloppes", "description": "Plus récentes d’abord. Scope `envelopes:read`.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "status", "created_at", "completed_at" ] } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "data", "limit", "offset" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/envelopes/{id}": { "get": { "tags": [ "Enveloppes" ], "summary": "Lire une enveloppe", "description": "Statut, signataires, documents avec liens de téléchargement temporaires (1 h) une fois scellée. Après purge, les liens sont `null` mais la preuve reste vérifiable via `/verify`.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Enveloppe introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/envelopes/{id}/send": { "post": { "tags": [ "Enveloppes" ], "summary": "Envoyer un brouillon", "description": "Passe l’enveloppe de `draft` à `sent` et notifie les signataires. Réserve les crédits en libre-service.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "402": { "description": "Crédits insuffisants", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_status` : déjà envoyée", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/envelopes/{id}/cancel": { "post": { "tags": [ "Enveloppes" ], "summary": "Annuler", "description": "Possible en `draft` ou `sent`. Les liens de signature deviennent inactifs (`410 gone`) et les crédits réservés sont rendus.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_status`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/verify": { "post": { "tags": [ "Vérification" ], "summary": "Vérifier un document par empreinte", "description": "Soumettez le PDF (base64) ou son empreinte SHA-256. Retrouve l’enveloppe (document original, scellé ou révision intermédiaire), renvoie signataires, chronologie chaînée et `chain_valid`. Fonctionne **même après purge des documents**. Scope `envelopes:read`.", "security": [ { "apiKey": [] } ], "requestBody": { "description": "PDF ou empreinte", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } } }, "responses": { "200": { "description": "`known: false` si l’empreinte est inconnue de votre organisation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" } } } }, "400": { "description": "Ni PDF ni empreinte", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/identities": { "post": { "tags": [ "Identités" ], "summary": "Établir une identité réutilisable", "description": "Mode `partner_attested` : vous avez vérifié la pièce, vous transmettez les attributs et l’empreinte du numéro (jamais le numéro). L’identité est réutilisable sur toutes les enveloppes suivantes du même signataire (`identity_id`). Scope `identities:manage`.", "security": [ { "apiKey": [] } ], "requestBody": { "description": "Identité", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIdentity" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Identity" }, { "type": "object", "properties": { "verification_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "verification_url" ] } ] } } } }, "400": { "description": "Corps invalide", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "`idv_not_configured` (vérification à distance non contractualisée)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Identités" ], "summary": "Lister les identités", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "external_ref", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": [ "data", "limit", "offset" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/identities/{id}": { "get": { "tags": [ "Identités" ], "summary": "Lire une identité", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "Identités" ], "summary": "Effacer une identité (droit à l’effacement)", "description": "Les signatures déjà émises restent valides : la preuve est dans le certificat et le dossier de preuve.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/signing-mandates": { "post": { "tags": [ "Mandats et lots" ], "summary": "Créer un mandat de signature", "description": "Le représentant légal signe l’acte de mandat en signature avancée (identité attestée requise). Une fois activé, les mandataires peuvent cacheter en lot les documents du périmètre. Scope `mandates:manage`.", "security": [ { "apiKey": [] } ], "requestBody": { "description": "Mandat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSigningMandate" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningMandate" } } } }, "400": { "description": "Corps invalide", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "`identity_required`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Mandats et lots" ], "summary": "Lister les mandats", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SigningMandate" } } }, "required": [ "data" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/signing-mandates/{id}": { "get": { "tags": [ "Mandats et lots" ], "summary": "Lire un mandat", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningMandate" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/signing-mandates/{id}/revoke": { "post": { "tags": [ "Mandats et lots" ], "summary": "Révoquer un mandat", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningMandate" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_status`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/seal-batch": { "post": { "tags": [ "Mandats et lots" ], "summary": "Cacheter un lot sous mandat", "description": "Jusqu’à 500 enveloppes `organization_seal` du même mandat. Le mandataire reçoit une `authorization_url`, vérifie la liste et saisit **un seul** code à usage unique. Le jeton porte sur l’empreinte de la liste des empreintes : ajouter un document invalide le lot (`409 batch_mismatch`).", "security": [ { "apiKey": [] } ], "requestBody": { "description": "Lot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSealBatch" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SealBatch" } } } }, "400": { "description": "Corps invalide", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Mandat ou enveloppe introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`mandate_not_active`, `mandate_expired`, `invalid_status`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "`agent_not_in_mandate`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/attendance-sessions": { "post": { "tags": [ "Émargement" ], "summary": "Créer une session d’émargement", "description": "Aucun PDF en entrée : la feuille est générée par la plateforme. Réponse : `sign_url` par stagiaire, `trainer.url` pour le formateur. Scope `attendance:write`.", "security": [ { "apiKey": [] } ], "requestBody": { "description": "Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttendanceSession" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceSession" } } } }, "400": { "description": "Corps invalide", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Émargement" ], "summary": "Lister les sessions", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "reference", "status", "created_at" ] } }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": [ "data", "limit", "offset" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/attendance-sessions/{id}": { "get": { "tags": [ "Émargement" ], "summary": "Lire une session (présences en temps réel)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceSession" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/attendance-sessions/{id}/attendees": { "post": { "tags": [ "Émargement" ], "summary": "Ajouter un inscrit en cours de session", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "description": "Stagiaire", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAttendee" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceSession" } } } }, "400": { "description": "`name` requis", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Session close", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/attendance-sessions/{id}/slots/{slotId}/open": { "post": { "tags": [ "Émargement" ], "summary": "Ouvrir un créneau", "description": "Le QR code n’existe qu’entre l’ouverture et la fermeture.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "slotId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceSession" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`slot_closed`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/attendance-sessions/{id}/slots/{slotId}/close": { "post": { "tags": [ "Émargement" ], "summary": "Fermer un créneau", "description": "Un créneau clos ne peut plus être rempli, jamais.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "slotId", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceSession" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_status`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/attendance-sessions/{id}/close": { "post": { "tags": [ "Émargement" ], "summary": "Clôturer la session", "description": "Feuille générée, **un seul** scellement, **un seul** dossier de preuve, webhook `attendance.session_closed`. Irréversible.", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceSession" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_status`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/attendance-sessions/{id}/sheet": { "get": { "tags": [ "Émargement" ], "summary": "Feuille scellée (lien 1 h)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sheet_sha256": { "type": [ "string", "null" ] }, "sheet_download_url": { "type": "string", "format": "uri" }, "evidence_download_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "sheet_sha256", "sheet_download_url", "evidence_download_url" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Pas encore scellée", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "Feuille purgée (fin de rétention)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/attendance-sessions/{id}/export": { "get": { "tags": [ "Émargement" ], "summary": "Export CSV pour le contrôle de service fait", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "csv" ] }, "required": false, "name": "format", "in": "query" } ], "responses": { "200": { "description": "CSV (séparateur `;`)", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/webhook-endpoints": { "post": { "tags": [ "Webhooks" ], "summary": "Créer un endpoint", "description": "La réponse contient `secret` (affiché une seule fois). Chaque livraison porte `X-Esign-Event` et `X-Esign-Signature: sha256=` ; 8 tentatives avec attente exponentielle tant que vous ne répondez pas 2xx. Événements : `envelope.completed`, `envelope.expired`, `mandate.activated`, `seal_batch.applied`, `attendance.session_closed`. Scope `webhooks:manage`.", "security": [ { "apiKey": [] } ], "requestBody": { "description": "Endpoint HTTPS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpoint" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "URL https:// requise", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "Webhooks" ], "summary": "Lister les endpoints", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "active": { "type": "boolean" } }, "required": [ "id", "url", "active" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/webhook-endpoints/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Supprimer un endpoint", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "active": { "type": "boolean", "enum": [ false ] } }, "required": [ "id", "active" ] } } } }, "401": { "description": "Clé absente, mal formée ou révoquée (`unauthorized`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Scope manquant sur la clé (`forbidden`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Limitation de débit (`rate_limited`, en-tête `Retry-After`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "available_credits": { "type": "number" }, "required_credits": { "type": "number" }, "purchase_url": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": {} }