Références et rejeux

Un appel peut se perdre : délai dépassé, coupure réseau, redémarrage de votre TMS au mauvais moment. Vous ne savez alors pas si Fincargo a reçu la requête. Cette page explique comment rejouer sans risque : sans créer deux fois le même document, et sans être facturé deux fois.

Posez votre propre référence sur chaque DeCa

Chaque DeCa accepte un external_identifier : le numéro de l'ordre dans votre TMS. C'est lui qui rend une création rejouable.

POST /v1/controldocuments
{
  "external_identifier": "ORD-1001",
  "roles": [ ... ],
  "goods_lines": [ ... ]
}

• Il est unique dans votre compte, et seulement dans votre compte. Une autre entreprise peut utiliser ORD-1001 sans vous gêner, et rien de ce qu'elle fait n'apparaît jamais dans vos réponses.
• Il est distinct de la transport_reference, le numéro imprimé sur le document. Vous pouvez donner les deux, ou seulement l'un.

Rejouer une création

Si vous renvoyez une création avec un external_identifier déjà utilisé dans votre compte, la réponse est un 409 qui porte l'identifiant du document déjà créé :

{
  "errors": [
    {
      "code": "control_document.external_identifier_already_exists",
      "description": "A control document of this account already carries this external_identifier.",
      "existing_id": "3f2c9a4e-…"
    }
  ]
}

Votre TMS lit existing_id, puis GET /v1/controldocuments/{existing_id} : il retrouve le document que le premier appel a créé. Aucun second document n'existe.

La tournée suit la même règle avec sa reference (POST /v1/tours, code tour.reference_already_exists, avec existing_id). Une tournée créée sans reference n'est pas protégée : rejouée, elle serait créée deux fois. Envoyez toujours une référence.

Rejouer une assignation

Assigner un document est le geste qui l'émet et le facture. Rejouer la même assignation ne fait rien de plus : la réponse est un 200 qui rend le document (ou la tournée), sans nouvelle émission, sans nouvelle facturation et sans nouvelle notification au chauffeur.

Geste	Rejoué à l'identique	Rejoué avec une autre cible
PATCH /v1/controldocuments/{id}/roles/{role_id}/assign-subaccount	200, le document	400 : changer de chauffeur est une correction (POST .../corrections, champ DRIVER), qui apparaît barrée sur le PDF
POST /v1/tours/{id}/assignment	200, la tournée (même chauffeur, et même camion s'il est donné)	400
POST /v1/tours/{id}/send	200, la tournée (même sous-traitant, et même chauffeur pour un envoi direct)	400

Un document remplacé garde votre référence

Un DeCa émis ne se modifie pas toujours : certaines erreurs se réparent en le remplaçant par un nouveau document (POST .../supersede, ou POST .../replace pour un sous-traitant). Pour votre TMS, c'est le même ordre, corrigé : le remplaçant garde l'external_identifier de l'original. S'il n'en porte pas dans son corps, il en hérite.

Après un remplacement, l'existing_id d'un rejeu désigne la version en vigueur, c'est-à-dire le remplaçant. Un remplacement ne peut pas prendre l'external_identifier d'un autre document de votre compte.