Annuaire (Partners, Vehicles, Packaging Methods)

L'annuaire est un carnet d'adresses privé, propre à votre compte : il évite de retaper l'identité complète d'un tiers à chaque Freight Document. Il est entièrement push et entièrement optionnel — rien ici ne synchronise automatiquement avec votre propre TMS ; chaque entrée n'existe que parce que vous avez explicitement appelé l'endpoint de création correspondant. Vous pouvez tout aussi bien ignorer complètement l'annuaire et continuer à envoyer une identité complète en ligne (party_snapshot) à chaque création de document.

Toutes les ressources de l'annuaire vivent sous /v1/accounts/me/... (et non /v1/directory/...) — c'est une particularité de l'arborescence de l'API : dans Swagger, vous les trouverez donc regroupées visuellement sous "Accounts", bien qu'elles portent leur propre tag directory.

Partners (et Locations)

Un Location n'est pas une ressource séparée : c'est un Partner dont le champ kind vaut LOCATION plutôt que GENERIC — mêmes endpoints, même CRUD, même import en masse.

Méthode	Chemin	Description
POST	/v1/accounts/me/partners	Création (201)
POST	/v1/accounts/me/partners/bulk	Import en masse — jusqu'à 500 entrées, un résultat par entrée (une entrée en échec ne bloque pas les autres)
GET	/v1/accounts/me/partners	Liste paginée
GET	/v1/accounts/me/partners/{id}	Détail
PATCH	/v1/accounts/me/partners/{id}	Mise à jour partielle
DELETE	/v1/accounts/me/partners/{id}	Suppression logique (deleted_at)

Champs principaux : kind (GENERIC ou LOCATION, défaut GENERIC), name, address, external_identifier (votre propre identifiant, optionnel), et les champs de contact contact_name, phone, mobile_phone, contact_email, notes (tous optionnels).

linked_account_id est en lecture seule : il apparaît dans les réponses quand la fiche est reliée à un compte Fincargo, et seule l'acceptation d'une mise en relation le pose. Envoyé à la création ou à la modification d'une fiche, il est ignoré.

gln (optionnel) est le GLN GS1 (Global Location Number) de ce tiers — exactement 13 chiffres, vérifié uniquement sur la forme (pas de clé de contrôle), rejeté avec partner.invalid_gln sinon. Comme name/address, il est figé dans frozen_party_snapshot au moment où un rôle est créé à partir de ce Partner (partner_id) — jamais une référence vivante. Un rôle créé sans passer par l'annuaire peut aussi porter un gln directement dans son party_snapshot (même validation, code freight_document.invalid_gln).

address est structuré, pas un texte libre — même règle qu'un rôle de Freight Document (voir Identité figée d'une partie) : {street, postal_code, city, country}, les 4 champs requis si une adresse est fournie (country : code à 2 lettres, ex. "ES" — vérifié uniquement sur la forme, pas sur une liste blanche de codes réels). Une adresse vide ({}, la valeur par défaut) reste valide — un Partner peut ne pas encore avoir d'adresse. Un objet incomplet est rejeté avec partner.invalid_address.

{
  "name": "Acme Consignor SL",
  "address": { "street": "Calle Mayor 1", "postal_code": "28013", "city": "Madrid", "country": "ES" }
}

Un Partner supprimé n'est jamais retiré physiquement de la base : un Freight Document peut avoir figé une référence vers lui (frozen_party_snapshot) au moment de sa création, et cette référence doit rester résoluble indéfiniment pour des raisons de conservation légale.

external_identifier est unique par compte, jamais globalement — deux comptes différents peuvent réutiliser la même valeur sans collision, puisque chaque annuaire est strictement privé à son propriétaire.

Numéros de confiance d'un Partner

Vous pouvez enregistrer, pour chaque Partner, les numéros de téléphone que vous savez déjà légitimes chez ce tiers (le quai de réception, un responsable de site). Si une signature est ensuite réalisée depuis un numéro qui ne figure dans aucun d'eux, une indication apparaît sur le document.

Ce n'est jamais bloquant. Le signataire n'est pas empêché de signer, la signature est valide, le document avance normalement. C'est un signal de vigilance pour la personne qui relit le document ensuite, jamais un contrôle d'accès ni une preuve.

Méthode	Chemin	Description
GET	/v1/accounts/me/partners/{id}/trusted-phone-numbers	Liste
POST	/v1/accounts/me/partners/{id}/trusted-phone-numbers	Ajout (201)
DELETE	/v1/accounts/me/partners/{id}/trusted-phone-numbers/{number_id}	Retrait (204, suppression physique)

Champs : phone_number (requis), note (optionnel — un texte libre pour vous y retrouver, ex. "Réception marchandises", jamais comparé à quoi que ce soit).

phone_number est normalisé au format E.164 quelle que soit la forme envoyée (0041 22 345 67 89, +41 22 345 67 89 et +41223456789 donnent tous +41223456789), et un numéro qui ne peut pas être résolu est rejeté avec partner.invalid_trusted_phone_number. C'est volontairement plus strict que le champ phone du Partner juste à côté, qui reste du texte libre : un numéro de confiance n'existe que pour être comparé à un numéro signataire, et un numéro non normalisé ne pourrait jamais correspondre — il produirait donc une indication fausse en permanence. Il n'y a pour autant aucune liste blanche de pays ; mais un numéro sans indicatif n'est accepté que s'il s'agit d'un vrai numéro national de la région par défaut du déploiement, donc envoyez l'indicatif.

Un doublon est rejeté avec partner.trusted_phone_number_already_exists, comparé sur la forme normalisée.

La liste est figée à la création du rôle, exactement comme name/address/gln : un rôle créé à partir de ce Partner (partner_id) emporte une copie des numéros tels qu'ils sont à cet instant. Ajouter ou retirer un numéro ensuite ne change jamais ce contre quoi un document déjà créé est vérifié. Un rôle créé sans partner_id n'a aucune liste, donc jamais d'indication — l'absence de signal ne veut pas dire « numéro reconnu ».

Côté document, le signal se lit sur signer_phone_unrecognized dans GET /v1/freightdocuments/{id}/signatures : true = le numéro ne correspondait à aucun numéro connu, false = il correspondait, null = rien à comparer ou vous n'êtes pas destinataire de ce signal. Seuls le compte détenteur du rôle signé (ou un délégataire actif de ce rôle) et le déposant du document reçoivent une valeur non nulle ; les deux sens de null sont volontairement indistinguables.

Enfin, l'API renvoie toujours les numéros en clair. L'interface web les affiche réduits aux derniers chiffres avec un bouton « Révéler », mais c'est un simple confort visuel (écran partagé, capture d'écran) — pas un contrôle d'accès, et rien ne doit être construit en supposant le contraire.

Sous-traitants : leurs chauffeurs et leurs véhicules

Un Partner de nature entreprise (kind=GENERIC) porte un champ relation : SUBCONTRACTOR pour une entreprise à qui vous confiez des transports, OTHER pour toute autre relation (un client, un fournisseur). Toute fiche vaut OTHER par défaut, y compris celles créées avant l'apparition de ce champ. Un lieu (kind=LOCATION) n'est jamais un sous-traitant : partner.invalid_relation (400).

Comme toute entreprise, un sous-traitant peut être créé incomplet, à partir de son seul nom. Son identité fiscale (une adresse, un vat_number, et un NIF si l'adresse est en Espagne) est exigée au moment de le mettre sur un document : un rôle créé depuis une fiche incomplète est refusé avec freight_document.missing_tax_identification (ou freight_document.address_required), et le message nomme la fiche à compléter.

La liste accepte un filtre relation=SUBCONTRACTOR (ou OTHER), appliqué par le serveur avant la pagination.

Vous pouvez enregistrer ce que vous savez des chauffeurs et des véhicules d'un sous-traitant, pour pré-remplir un document que vous lui confiez. Ce ne sont pas des accès : ces chauffeurs ne se connectent à rien et ne voient rien. Et ces véhicules n'entrent jamais dans votre propre flotte (/v1/accounts/me/vehicles) : ce sont deux listes distinctes, et une même plaque peut figurer dans les deux.

Méthode	Chemin	Description
GET	/v1/accounts/me/partners/{id}/drivers	Liste
POST	/v1/accounts/me/partners/{id}/drivers	Ajout (201)
PATCH	/v1/accounts/me/partners/{id}/drivers/{driver_id}	Modification
DELETE	/v1/accounts/me/partners/{id}/drivers/{driver_id}	Retrait (204)
GET	/v1/accounts/me/partners/{id}/vehicles	Liste
POST	/v1/accounts/me/partners/{id}/vehicles	Ajout (201)
PATCH	/v1/accounts/me/partners/{id}/vehicles/{vehicle_id}	Modification
DELETE	/v1/accounts/me/partners/{id}/vehicles/{vehicle_id}	Retrait (204)

Chauffeur : full_name et email requis (c'est à cette adresse que le chauffeur recevra un lien d'accès au document), phone facultatif. Véhicule : license_plate requise, vehicle_type (TRUCK par défaut, VAN, TRAILER), et default_trailer_id, la remorque attelée par défaut : une remorque (TRAILER) de ce même sous-traitant, non retirée, jamais le véhicule lui-même, et jamais sur une remorque (partner.invalid_default_trailer, 400). Retirer une remorque la détache des véhicules qui la portaient.

Un doublon (même email ou même license_plate chez ce sous-traitant) est rejeté avec partner.fleet_entry_already_exists (409).

Lecture libre, écriture réservée au sous-traitant. Sur une fiche qui n'est pas (ou plus) un sous-traitant, les listes restent lisibles, mais toute écriture est refusée avec partner.not_a_subcontractor (409). Repasser une fiche en OTHER conserve ses chauffeurs et véhicules ; ils redeviennent modifiables si elle redevient SUBCONTRACTOR.

Vehicles

Fiche technique d'un véhicule de votre flotte.

!!! note "linked_subaccount_id est retiré"

Ce champ reliait la fiche à un sous-compte de type `vehicle` (un boîtier embarqué qui s'authentifie), un concept qu'aucun mécanisme n'a jamais lu. Depuis le 04/11/2026, il n'est plus rendu et il est ignoré s'il est envoyé.

Méthode	Chemin
POST / GET (liste)	/v1/accounts/me/vehicles
GET / PATCH / DELETE	/v1/accounts/me/vehicles/{id}

Champs : license_plate, vehicle_type (TRUCK par défaut, ou TRAILER/VAN), capacity_kg, capacity_volume_m3, adr_declared (booléen) et adr_vehicle_types (voir ci-dessous), external_identifier, default_trailer_id (voir ci-dessous). Suppression logique, comme Partners.

!!! warning "Une déclaration du transporteur, jamais une vérification" adr_declared dit que le transporteur déclare le véhicule apte au transport de marchandises dangereuses. Fincargo ne vérifie rien, ne bloque rien et ne croise rien sur cette donnée : ni avec un chauffeur, ni avec la marchandise transportée.

- `adr_vehicle_types` : facultatif, même quand `adr_declared` vaut `true` (un type
  inconnu est une réponse valide). Liste fermée, plusieurs valeurs possibles :
  `EX/II`, `EX/III`, `FL`, `AT`, `MEMU`. Une autre valeur est refusée
  (`vehicle.invalid_adr_vehicle_type`).
- Chaque déclaration est datée (`adr_declared_at`), attribuée et conservée : une
  nouvelle déclaration s'ajoute à l'historique, elle n'efface jamais la précédente.
- Sur le véhicule d'un sous-traitant, `adr_declaration_reported` vaut `true` : la
  déclaration est rapportée par votre compte.
- **Ancien nom** : `adr_certified` est encore accepté en entrée et renvoyé en
  lecture, avec la même valeur que `adr_declared`, le temps d'une transition. Il est
  déprécié et sera retiré : lisez et écrivez `adr_declared`. Le même renommage vaut
  pour les chauffeurs et les sous-comptes.

La plateforme n'assure aucune obligation documentaire liée aux marchandises
dangereuses : le document de transport qu'elles exigent reste à la charge du
transporteur.

!!! warning "Le numéro d'autorisation de transport appartient à l'entreprise, plus au véhicule" Il se gère sur votre compte : GET / POST /v1/accounts/me/transport-authorizations ({"number": "..."}) et DELETE /v1/accounts/me/transport-authorizations/{id}. Un même numéro n'est gardé qu'une fois (account.transport_authorization_already_exists, 409).

- Sur un document de contrôle (DeCA), le numéro est **facultatif** :
  `transport_authorization_no` sur le rôle `CARRIER`. Absent, et si le transporteur est
  votre propre entreprise, son numéro est pris d'office **quand elle n'en a qu'un** ;
  sinon le document part sans numéro.
- **Ancien champ** : `transport_authorization_no` est encore accepté en entrée sur un
  véhicule, le temps d'une transition. Il n'y est plus enregistré : il rejoint la liste
  de votre entreprise. Il n'est plus renvoyé sur le véhicule, et
  `authorization_valid_until` n'existe plus.

Remorque par défaut — default_trailer_id désigne la remorque qu'un véhicule tracte habituellement. Il doit référencer un autre véhicule de votre propre compte, de type TRAILER et non supprimé ; sinon la requête est rejetée avec vehicle.invalid_default_trailer. Aucune contrainte sur le type du véhicule porteur : un VAN tracte aussi.

C'est uniquement un pré-remplissage, jamais une règle. La console propose la remorque par défaut quand on choisit le tracteur à la création d'un document, et l'opérateur reste libre de la changer — un tracteur ne tire pas toujours la même remorque. L'API, elle, ne substitue rien et ne rejette aucune combinaison : trailer_vehicle_id/trailer_plate sont pris exactement tels que vous les envoyez. Une intégration TMS n'a donc rien à changer.

Lien avec un Freight Document (case 16 du CMR) — un rôle CARRIER (à la création du document ou via l'ajout de rôle post-création) accepte deux champs supplémentaires, chacun avec le même choix que Partners/party_snapshot : vehicle_plate/trailer_plate (saisie libre, immédiatement figée sur le rôle) ou, en alternative, vehicle_id/trailer_vehicle_id référençant une entrée de cet annuaire — sa license_plate est copiée au moment de la création, jamais une référence vivante ensuite (modifier le véhicule plus tard ne change pas les rôles déjà créés). Fournir les deux pour le même emplacement (plaque et id) est rejeté. vehicle_id doit référencer un véhicule qui n'est pas TRAILER ; trailer_vehicle_id doit référencer un TRAILER — un mauvais type renvoie freight_document.vehicle_type_mismatch, distinct de vehicle.not_found. trailer_plate/trailer_vehicle_id restent toujours optionnels : un transport n'a pas systématiquement de remorque. Ces champs ne sont pertinents que pour CARRIER ; les fournir sur un autre type de rôle est rejeté explicitement, pas ignoré silencieusement.

Drivers — retiré

Les endpoints /v1/accounts/me/drivers ont été retirés le 04/11/2026 : ils répondent 404. Cette fiche n'a jamais eu de consommateur. Un chauffeur est un sous-compte de type driver (/v1/accounts/me/subaccounts), qui porte driving_license_number et adr_declared, et que driver_phone_number désigne sur un rôle CARRIER — voir Mono-transporteur.

Packaging Methods

Méthode	Chemin
POST / GET (liste)	/v1/accounts/me/packaging-methods
GET / PATCH / DELETE	/v1/accounts/me/packaging-methods/{id}

Cette ressource ne se gère plus depuis l'interface. L'onglet « Emballages » de l'annuaire d'ecmr-platform a été retiré : créer, renommer ou supprimer un type d'emballage passe désormais uniquement par les endpoints ci-dessus. Les endpoints eux-mêmes n'ont pas changé, et les emballages déjà enregistrés restent proposés à la création d'un document. Un compte qui n'en a aucun ne verra tout simplement pas le mode « Depuis l'annuaire » sur une ligne de marchandise, et saisira l'emballage en texte libre — ce que packaging_method a toujours permis. Le retrait est assumé et réversible : rien n'a été supprimé côté API.

Champs : label, external_identifier. À la différence des deux autres ressources de l'annuaire, la suppression ici est définitive (pas de deleted_at) : packaging_method_id n'est jamais stocké de façon durable ailleurs dans le système, seul son label l'est (voir ci-dessous) — donc rien ne dépend de la persistance de l'identifiant lui-même après suppression.

Lien avec les lignes de marchandise (cases 6-12 du CMR) — chaque ligne de marchandise (goods_lines, à la création du document, sur un PUT, ou sur un PATCH qui touche ce champ) accepte packaging_method (saisie libre, immédiatement figée sur la ligne) ou, en alternative, packaging_method_id référençant une entrée de cet annuaire — son label est copié au moment de la requête, jamais une référence vivante ensuite : ni l'id ni aucune colonne ne le relie à la ligne après coup, exactement comme vehicle_id/vehicle_plate ci-dessus. Fournir les deux, ou aucun des deux, est rejeté (freight_document.invalid_role_assignment).

Pagination

Les trois listes de l'annuaire (partners, vehicles, packaging-methods) partagent la même pagination simple :

• limit (1 à 200, défaut 50)
• offset (défaut 0)

La réponse inclut toujours limit, offset et total. C'est un schéma différent de celui utilisé par la liste des Freight Documents — voir API Reference pour le détail des deux conventions.