Signature et suivi TTN

Déclencher la signature

POST /api/v2/invoices/:id/sign-and-send — recommandé, un seul appel

Nécessite invoice:write, plus seal:sign (si signatureType: "SEAL") ou digigo:sign (si "DIGIGO") selon votre plan.

{ "signatureType": "SEAL" }

Réponse 200 OK (un job est créé, pas le résultat final) :

{
  "jobId": "...",
  "invoiceId": "...",
  "jobType": "SIGN_AND_SUBMIT_SEAL",
  "status": "PENDING",
  "success": true,
  "message": "Invoice queued for signature and TTN submission"
}

Alternative manuelle en deux étapes

Si vous devez inspecter le document signé avant de l'envoyer à TTN :

POST /api/v2/invoices/:id/sign          { "provider": "seal" }   # ou "digigo"
POST /api/v2/invoices/:id/submit-ttn

Contrairement à Partner API

Votre propre clé API peut appeler submit-ttn directement — cette restriction ne s'applique qu'aux tokens partenaires.

Suivre le job

GET /api/v2/jobs/:jobId
GET /api/v2/jobs/:jobId/logs?limit=50

status transite PENDING → COMPLETED ou FAILED. En cas d'échec, outputData nomme l'étape fautive (ex. certificat non configuré — un échec fréquent, pas un bug). Une fois le job terminé, rechargez la facture : status sera ACCEPTED_TTN en cas de succès.

Statuts source autorisés

Le sign-and-send n'est accepté que si la facture est actuellement DRAFT, VALIDATED, VALIDATION_FAILED, SIGNATURE_FAILED, REJECTED_TTN, ERROR_TTN ou TIMEOUT_TTN — sinon vous obtenez un 409.

Suivre les évènements par webhook

Plutôt que d'interroger l'API en boucle, enregistrez un webhook pour recevoir une notification à chaque changement de statut de vos factures. Utilise le même token que le reste de cette page.

curl -X POST "https://<base_url>/api/v2/webhooks" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-erp.example.com/webhooks/fatoora",
    "events": ["invoice.validated", "invoice.signed", "invoice.accepted_ttn", "invoice.rejected_ttn"]
  }'

Le secret retourné n'apparaît qu'une seule fois, à la création — conservez-le pour vérifier la signature X-HMAC-Signature (Base64, HmacSHA256) de chaque évènement livré. Types d'évènements envoyés par défaut si events est omis : invoice.created, invoice.validated, invoice.signed, invoice.submitted_ttn, invoice.accepted_ttn, invoice.rejected_ttn, webhook.test (ajoutez invoice.validation_failed explicitement si besoin).

Méthode	Chemin	Scope
POST	/api/v2/webhooks	invoice:write
GET	/api/v2/webhooks	invoice:read
POST	/api/v2/webhooks/:id/test	invoice:write
DELETE	/api/v2/webhooks/:id	invoice:write

Utilisez POST /webhooks/:id/test (déclenche un évènement webhook.test) pour valider votre récepteur, vérification de signature comprise, avant de traiter de vrais évènements.

Alternative : mode « pull » (polling)

Si vous préférez ne pas exposer d'endpoint HTTP public, basculez en mode POLLING (PUT /api/v2/event-delivery/mode) et consommez GET /api/v2/notifications + POST /api/v2/notifications/ack à la place. Les deux modes sont mutuellement exclusifs.

Le guide PDF complet (téléchargeable depuis la page Référence) détaille le format exact de la signature et un exemple de payload livré.

Opérations en lot

POST /api/v2/invoices/batch/sign-and-send   { "invoiceIds": [...], "signatureType": "SEAL" }
POST /api/v2/invoices/batch/delete          [ "inv_1", "inv_2" ]

Quota de signature

Chaque sign-and-send consomme une unité de votre quota de signature mensuel (ou, à défaut, un crédit de pack de signatures). Si les deux sont épuisés :

{
  "error": "NO_SIGNATURE_CREDITS",
  "message": "No signing quota or signature-pack credits available. Buy a pack or subscribe/upgrade to sign and submit to TTN.",
  "packsRemaining": 0
}

avec un statut HTTP 402.

Étape suivante : consultez la page Référence pour la gestion des erreurs, les limites de débit et le téléchargement du guide complet.