Annuaire (Partners, Vehicles, Drivers, 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), linked_account_id (informatif uniquement), et les champs de contact contact_name, phone, mobile_phone, contact_email, notes (tous optionnels).

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.

Vehicles

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

!!! warning "linked_subaccount_id est abandonné — ne l'utilisez pas"

Ce champ reliait la fiche à un **sous-compte** de type `VEHICLE` (un boîtier embarqué qui s'authentifie). Ce concept a été retiré de la console : plus aucun écran ne permet de créer un tel sous-compte, rien n'écrit ce lien, et aucun mécanisme ne l'a jamais lu. Le champ reste accepté par l'API pour ne rien casser, mais il n'a aucun effet. N'en dépendez pas.

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_certified (booléen), external_identifier, default_trailer_id (voir ci-dessous), linked_subaccount_id (abandonné, voir l'encadré ci-dessus). Suppression logique, comme Partners.

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 — déprécié

!!! warning "Ressource dépréciée — ne l'utilisez pas pour une nouvelle intégration"

Les endpoints ci-dessous fonctionnent toujours à l'identique et ne sont pas retirés : si votre intégration les appelle aujourd'hui, rien ne casse. Mais cette fiche n'a **jamais eu de consommateur** — aucun champ d'un Freight Document n'accepte de `driver_id`, et rien ne lit `linked_subaccount_id`. Créer une fiche ici n'a donc aucun effet observable ailleurs dans le système.

Les deux seuls champs qui portaient une information utile, `driving_license_number` et `adr_certified`, existent désormais **directement sur le sous-compte** du chauffeur (`POST`/`PATCH /v1/accounts/me/subaccounts`), c'est-à-dire sur l'identité qui signe réellement. C'est là qu'il faut les renseigner.

La console ne propose plus cette ressource : l'onglet correspondant a été retiré de l'Annuaire.

Même forme CRUD que Vehicles, y compris la suppression logique. Champs : full_name, phone (optionnel), driving_license_number (optionnel — jamais requis, par principe de minimisation des données personnelles), adr_certified, external_identifier, linked_subaccount_id (doit référencer un sous-compte DRIVER).

À ne pas confondre avec l'assignation d'un chauffeur à un transport. Cette fiche est de la donnée de flotte : la créer ne donne accès à rien, et rien ici n'est lu au moment de créer un Freight Document. Pour désigner le chauffeur qui roule, un rôle CARRIER accepte driver_phone_number à la création du document — voir Mono-transporteur. Ce mécanisme résout un sous-compte de type DRIVER par son numéro et ne touche jamais à cet annuaire : il ne crée pas de fiche Driver et ne renseigne pas linked_subaccount_id.

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 trois 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 quatre listes de l'annuaire (partners, vehicles, drivers, 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.