API Reference

Cette page ne duplique pas la référence complète des endpoints — elle vous oriente vers la documentation générée automatiquement depuis le schéma OpenAPI réel de l'API, et donne le contexte nécessaire pour la lire efficacement.

Où trouver la référence complète

• Swagger UI : /docs sur l'environnement sandbox — exploration interactive, "Try it out" inclus.
• Schéma brut : /openapi.json — utile pour générer un client, ou l'importer dans votre propre outil (Postman, Insomnia...).

/docs, /redoc et /openapi.json ne sont exposés qu'en dehors de la production, pour des raisons de sécurité (surface d'attaque inutile une fois l'intégration terminée). Utilisez le sandbox pour explorer le schéma.

Groupes de ressources

Tout endpoint métier vit sous le préfixe /v1. Les endpoints d'infrastructure (/healthz, /readyz, /version) n'en font délibérément pas partie.

Groupe	Préfixe	Contenu
Accounts	/v1/accounts	Inscription, activation, connexion, clés API, clients OAuth, sous-comptes
OAuth	/v1/oauth	Émission de token via Client Credentials
Freight Documents	/v1/freightdocuments	CRUD du document, transitions de statut, rôles, délégation, access codes
Access Codes	/v1/access-codes	Échange d'un carrierAccessCode contre un token (endpoint public, sans authentification préalable)
Directory	/v1/accounts/me	Partners/Locations, Vehicles, Drivers, Packaging Methods — voir Annuaire

Particularité à noter : l'Annuaire partage son préfixe avec Accounts (/v1/accounts/me/...). Dans Swagger, vous le trouverez donc listé sous ce même chemin, mais avec son propre tag directory — ce n'est pas une erreur de rangement.

Freight Documents — endpoints principaux

Méthode	Chemin	Description
POST	/v1/freightdocuments	Création — l'appelant devient automatiquement SUBMITTER
GET	/v1/freightdocuments	Liste (voir pagination/filtrage ci-dessous)
GET	/v1/freightdocuments/{id}	Détail — nécessite la permission VIEW
GET	/v1/freightdocuments/ext/{externalIdentifier}	Recherche par votre propre identifiant externe
PUT	/v1/freightdocuments/{id}	Remplacement complet — version obligatoire (verrouillage optimiste)
PATCH	/v1/freightdocuments/{id}	Mise à jour partielle (JSON Merge Patch, RFC 7396) — version obligatoire
POST	/v1/freightdocuments/{id}/issue	Transition DRAFT → ISSUED
POST	/v1/freightdocuments/{id}/roles	Ajout d'un rôle/partie
POST	/v1/freightdocuments/{id}/roles/{roleId}/delegate	Délégation d'un rôle vers un tiers par email
GET	/v1/freightdocuments/{id}/roles/{roleId}/delegations	Chaîne de délégation d'un rôle
POST	/v1/freightdocuments/{id}/roles/{roleId}/delegations/{delegationId}/revoke	Révocation d'une délégation et de sa sous-chaîne
POST	/v1/freightdocuments/{id}/roles/{roleId}/access-codes	Émission d'un carrierAccessCode
POST	/v1/freightdocuments/{id}/roles/{roleId}/access-codes/{accessCodeId}/revoke	Révocation d'un access code

Voir le champ PUT/PATCH : le PUT remplace le document mais ne touche jamais aux rôles (roles) ni aux champs système (status, hostingType...) — utilisez les endpoints dédiés pour ceux-là. Le PATCH ne porte que sur un sous-ensemble de champs métier (marchandises structurées, références, incoterms, dates planifiées, champs spécifiques pays) et applique une vérification de permission dédiée par champ.

ownPermissions

Chaque réponse GET/PUT/PATCH sur un Freight Document inclut un champ ownPermissions — la liste des permissions que vous, l'appelant authentifié, possédez sur ce document précis. Ce champ est recalculé à chaque requête, jamais mis en cache : il reflète toujours l'état courant de vos rôles/délégations sur ce document. Si vous accédez via un carrierAccessCode plutôt qu'un compte complet, ownPermissions est automatiquement plafonné à la consultation et aux commentaires, quel que soit le rôle sous-jacent.

carrierAccessCode

Un mécanisme d'accès minimal pour un acteur sans compte du tout — un cran en dessous d'une délégation complète. Le code est réutilisable jusqu'à expiration ou révocation (ce n'est pas un token à usage unique), et n'est visible en clair qu'au moment de sa création — il est haché en base et ne peut plus être récupéré ensuite.

• POST /v1/freightdocuments/{id}/roles/{roleId}/access-codes — émission (nécessite la permission DELEGATE sur ce rôle)
• POST /v1/access-codes/redeem — échange du code contre un token de courte durée, endpoint public, plafonné aux permissions consultation + commentaire

Pagination et filtrage

L'API n'a pas une convention unique de pagination — deux schémas coexistent délibérément :

Annuaire (partners, vehicles, drivers, packaging-methods) : pagination simple.

• limit (1-200, défaut 50), offset (défaut 0)
• Réponse : { ..., limit, offset, total }

Freight Documents (GET /v1/freightdocuments) : schéma plus riche.

• filters — paramètre répétable, grammaire champ.opérateur:valeur, combinés en ET. Exemple : ?filters=status.eq:ISSUED&filters=referenceValue.like:PO-123
• sort — un champ, -champ pour un tri descendant (ex : sort=-created_at). Seuls created_at, updated_at, status sont triables.
• limit — toujours ramené dans l'intervalle [25, 50], jamais rejeté ; la réponse indique la valeur effective.
• first — décalage (équivalent d'offset, mais nommé différemment de l'Annuaire)
• Par défaut, les documents CANCELLED sont exclus des résultats, sauf filtrage explicite sur status.

Un filtre non reconnu (champ ou opérateur) renvoie une erreur explicite plutôt que d'être silencieusement ignoré.

Format d'erreur

Toute erreur suit la même forme, quel que soit l'endpoint :

{
  "errors": [
    { "code": "auth.invalid_credentials", "description": "Invalid credentials." }
  ]
}

Voir la taxonomie complète des codes d'erreur.