Signature et suivi TTN

La signature et la soumission à TTN suivent toujours la configuration propre de l'organisation cliente — votre application déclenche le processus mais ne manipule jamais ses identifiants de signature.

Déclencher la signature

POST /api/core-proxy/invoices/:id/sign-and-send

L'endpoint principal : signe la facture et la soumet à TTN en une opération asynchrone.

Nécessite invoice:write, plus seal:sign (si signatureType: "SEAL") ou digigo:sign (si "DIGIGO") selon la configuration du client.

{ "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"
}

jobType dépend du fournisseur de signature

SIGN_AND_SUBMIT_SEAL pour signatureType: "SEAL", SIGN_AND_SUBMIT_DIGIGO pour "DIGIGO" — ce n'est pas une valeur générique.

Suivre le job

GET /api/core-proxy/jobs/:jobId
GET /api/core-proxy/jobs/:jobId/logs?limit=50

status transite PENDING → COMPLETED ou FAILED. En cas d'échec, outputData nomme l'étape fautive (ex. certificat DigiGO non configuré côté client — 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 d'une facture soumise par votre application (ou par l'organisation cliente que vous représentez). Utilise le même token org-scoped que le reste de cette page — aucun header X-Org-ID à gérer manuellement.

Nouvelle capacité

Auparavant réservée aux clés API propres de l'organisation (401 PARTNER_CONTEXT_NOT_ALLOWED), la gestion des webhooks est désormais ouverte à toute application partenaire autorisée pour l'organisation cible — même vérification d'autorisation que pour les factures.

curl -X POST "https://<base_url>/api/core-proxy/webhooks" \
  -H "Authorization: Bearer ORG_SCOPED_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/core-proxy/webhooks	invoice:write
GET	/api/core-proxy/webhooks	invoice:read
POST	/api/core-proxy/webhooks/:id/test	invoice:write
DELETE	/api/core-proxy/webhooks/:id	invoice:write

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/core-proxy/invoices/batch/sign-and-send   { "invoiceIds": [...], "signatureType": "SEAL" }
POST /api/core-proxy/invoices/batch/delete           [ "inv_1", "inv_2" ]

Quota de signature

Chaque sign-and-send consomme une unité du quota de signature mensuel de l'organisation cliente (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. Il s'agit d'un quota propre au client, distinct de votre propre limite mensuelle de documents Partner API.

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