Aller au contenu principal

Ruptures d'API

Cette page recense les changements de l'API v1 qui cassent une intégration en place : une clé renommée, une clé retirée, un appel désormais refusé. Les entrées sont datées et classées de la plus récente à la plus ancienne.

Si votre intégration a cessé de fonctionner sans que vous ayez rien changé de votre côté, commencez ici, puis revenez à la page de la ressource concernée.

30 septembre 2026 : une remise refusée par Scribee avant tout envoi répond 422, et non plus 202​

Ce qui change​

Sur POST /api/v1/payment_batches/{id}/submit, quand Scribee ne peut pas construire la demande au prestataire de paiement de son côté, l'appel répondait un 202 portant un lot failed. Il répond désormais un 422 validation_failed, exactement comme le refus d'un lot que le canal ne peut pas exprimer en l'état : details.instructions porte le message du refus, rien n'a été envoyé au prestataire, et l'Idempotency-Key n'est pas consommée. Le lot passe toujours à failed, avec submission_refused_by à local.

Deux ajouts accompagnent ce changement, sans rien retirer :

  • le lot publie submission_refused_by : provider, local ou null ;
  • une instruction d'un lot failed qui ne porte aucun statut de la banque publie submission_failed, et non plus submitted, et payment_instruction.updated annonce ce passage.

Les ressources concernées​

  • POST /api/v1/payment_batches/{id}/submit et GET /api/v1/payment_batches/{id} (Lots de paiement).
  • GET /api/v1/payment_batches/{id}/instructions, son filtre status, et GET /api/v1/payment_instructions/{id} (Le statut d'une instruction).
  • L'événement payment_instruction.updated (Webhooks).

Ce que vous devez faire​

  1. Traitez un 422 sur submit comme un refus qui peut avoir changé le lot : relisez-le, et lisez submission_refused_by quand il est failed.
  2. Acceptez submission_failed dans le status des instructions et dans les événements. Ce n'est pas un résultat bancaire : il ne confirme ni n'exclut un rejet ou une exécution à la banque, et la raison du refus se lit dans l'error_message du lot.

Comment reconnaître le symptôme​

  • Un submit qui répondait 202 avec un lot failed répond aujourd'hui 422 validation_failed.
  • Des instructions d'un lot failed que vous lisiez submitted se lisent submission_failed.

22 septembre 2026 : amount_with_taxes devient amount_without_taxes​

Ce qui change​

Dans chaque entrée de tax_subtotals, la ventilation par taux de TVA, la clé amount_with_taxes s'appelle désormais amount_without_taxes. Le changement porte sur la lecture comme sur l'écriture, sans alias et sans période de compatibilité : l'ancien nom n'est plus accepté en entrée et n'apparaît plus dans aucune réponse.

{
  "tax_subtotals": [
    {
      "tax_category_id": "S",
      "vat_rate": 20.0,
      "amount_without_taxes": 1000.0,
      "vat_amount": 200.0,
      "currency_code": "EUR"
    }
  ]
}

La valeur, elle, ne change pas : c'est toujours la base hors taxe du taux considéré, BT-116 dans EN 16931. Seul son nom change.

Les ressources concernées​

  • Les factures, en écriture comme en lecture : POST /api/v1/workspaces/{workspace_id}/invoices, PATCH /api/v1/invoices/{id} et GET /api/v1/invoices/{id} (Émettre une facture de vente).
  • Les devis, en lecture seule : GET /api/v1/quotes/{id} avec include=tax_subtotals. Les endpoints de devis n'ont jamais accepté de ventilation à l'écriture (Les devis).
  • Les factures d'e-reporting, en écriture comme en lecture : POST /api/v1/e_reportings/{e_reporting_id}/invoices, PATCH /api/v1/e_reportings/invoices/{id} et GET /api/v1/e_reportings/invoices/{id}.
  • Les transactions d'e-reporting, en écriture comme en lecture : POST /api/v1/e_reportings/{e_reporting_id}/transactions, PATCH /api/v1/e_reportings/transactions/{id} et GET /api/v1/e_reportings/transactions/{id} (Déclarer des transactions).
  • Les encaissements d'e-reporting, en lecture seule : GET /api/v1/e_reportings/payments/{id}. Le champ y est renvoyé sous son nouveau nom, et reste toujours nul - un encaissement ne porte que son montant encaissé (Déclarer des encaissements).

Pourquoi ce renommage​

L'ancien nom affirmait l'inverse de ce que le champ porte. amount_with_taxes se lit comme un montant toutes taxes comprises, alors que la valeur attendue est la base hors taxe par taux. Des intégrations ont rempli le champ avec le montant TTC, en toute bonne foi, et leurs factures ont été refusées bien plus tard, au dépôt. Le nom est donc corrigé plutôt que conservé.

Ce que vous devez faire​

  1. Renommez la clé dans les charges utiles que vous envoyez : amount_with_taxes devient amount_without_taxes.
  2. Renommez-la dans le code qui lit nos réponses. L'ancienne clé est absente du JSON, pas présente à null : un accès qui ne teste pas la présence renverra une valeur vide plutôt qu'une erreur.
  3. Vérifiez la valeur que vous y placez. Elle doit être la base hors taxe du taux, jamais le montant TTC.

Comment reconnaître le symptôme​

  • Une création ou une modification de facture qui passait hier répond aujourd'hui 422 : la charge utile envoie encore amount_with_taxes, cette clé inconnue est ignorée, et le sous-total se retrouve sans la base hors taxe que Scribee exige.
  • Vos lecteurs de réponses trouvent la ventilation vide ou à zéro : ils cherchent encore amount_with_taxes dans un objet qui expose amount_without_taxes.