EDI

NEXUS EDI — API des partenaires

Conseil du Coton, de l'Anacarde et du Karité (CCAK) · NEXUS SYSTEM^BM · DSIPE · version 1.0

L'API EDI permet aux partenaires du guichet unique des exportations d'échanger directement leurs données avec NEXUS EXPORT, sans ressaisie : CCI-CI (pesées et certificats de poids), ACE (bulletins qualité ou d'empotage, rapports d'empotage), inspection phytosanitaire, et logiciels des exportateurs agréés (contrats et demandes d'exportation). Chaque donnée reçue passe par les mêmes contrôles que la saisie à l'écran.

1. Authentification

Chaque partenaire reçoit du CCAK une clé d'API rattachée à son compte. Elle est transmise par un canal sûr et n'est jamais réaffichée ; le CCAK n'en conserve que l'empreinte. Toute requête porte l'en-tête :

X-Nexus-Cle: nxk_1a2b3c4d.0f9e8d7c6b5a49382716051f2e3d4c5b6a798867

La clé n'ouvre que les chemins /api/v1/edi/v1/…. Ses portées limitent les actions :

Portée	Autorise
`LECTURE`	Consulter les dossiers qui vous concernent, vérifier un contrat
`PIECES`	Déposer les pièces dont vous êtes l'émetteur (bulletins, rapports, certificats)
`PESAGES`	Transmettre les pesées et le certificat de poids (CCI)
`DECISIONS`	Valider ou rejeter les pièces dont vous êtes le valideur (ACE : rapport d'empotage)
`CONTRATS`	Enregistrer des contrats et des demandes d'exportation (logiciel d'un exportateur)

Une clé révoquée ou expirée est refusée (401). Une clé utilisée hors de l'API EDI est refusée (403). Tous les échanges sont journalisés.

2. Idempotence

Pour les envois (POST), ajoutez l'en-tête Idempotency-Key (identifiant unique de votre message, 100 caractères au plus). En cas de coupure réseau, renvoyez le même message avec la même clé : NEXUS renvoie la réponse initiale (en-tête Idempotent-Replay: true) sans l'enregistrer deux fois. Réutiliser la clé pour un contenu différent renvoie 422.

Idempotency-Key: CCI-ABJ-2026-0042-v1

3. Points d'accès

Base : https://<serveur NEXUS>/api/v1/edi/v1 — corps et réponses en JSON (UTF-8), dates AAAA-MM-JJ, poids en kg.

Méthode et chemin	Portée	Objet
GET`/moi`	—	Identité de la clé : compte, acteur, spécialité, portées
GET`/dossiers?booking=&conteneur=&numero=&statut=`	LECTURE	Dossiers qui vous concernent (50 au plus) : conteneurs, plombs, poids, pièces attendues
GET`/dossiers/{numéro}`	LECTURE	Un dossier
GET`/contrats/{numéro}`	LECTURE	Vérification d'un contrat : statut, validité, quantité restante
POST`/pieces`	PIECES	Dépôt d'une pièce sur un dossier
POST`/pieces/{id}/decision`	DECISIONS	Validation ou rejet motivé d'une pièce
POST`/pesages`	PESAGES	Pesées par conteneur et certificat de poids
POST`/terminal/evenements`	TERMINAL	Événements conteneur du terminal (un événement ou `{"evenements":[…]}`, 500 au plus)
GET`/terminal/feu-vert?conteneur=`	TERMINAL	Feu vert d'embarquement d'un conteneur : VERT ou ROUGE, motifs, référence de la décision
GET`/terminal/feux-verts?navire=`	TERMINAL	Feux de tous les conteneurs annoncés pour un navire (liste de chargement)
POST`/contrats`	CONTRATS	Enregistrement d'un contrat d'exportation (brouillon)
POST`/contrats/{id}/soumettre`	CONTRATS	Soumission du contrat à la vérification du SCE
POST`/dossiers`	CONTRATS	Demande d'autorisation d'empotage (DAE) sur des contrats validés
GET`/dossiers/{n°}/stock`	LECTURE	Stock tracé de la DAE (noix de cajou) : lots désignés, réservés et sortis du stock, origine, lots exportables
PUT`/dossiers/{n°}/stock`	CONTRATS	Désignation des lots de la DAE en brouillon : `{"lots":[{"lot":"LOT-ANA-…","kg":25000}]}` ; réservation à la soumission

3.1 CCI — transmettre les pesées

POST /api/v1/edi/v1/pesages
X-Nexus-Cle: nxk_…
Idempotency-Key: CCI-ABJ-2026-0042
Content-Type: application/json

{
  "dossier": "EX-FC26-00001-6",
  "numero_certificat": "CCI/ABJ/FIBCOT/2026-0042",
  "date": "2026-10-11",
  "pesees": [
    { "conteneur": "MSCU3000011", "ticket": "TK-0456", "poids_reel_kg": 24810 },
    { "conteneur": "CMAU3000013", "ticket": "TK-0457", "poids_reel_kg": 24795 }
  ],
  "fichier": { "nom": "certificat.pdf", "contenu_base64": "JVBERi0x…" }
}

Contrôles appliqués : dossier en exportation, conteneurs sur la packing-list définitive, un ticket de pesée ne sert qu'une fois.

3.1 bis Terminal à conteneurs — événements et feu vert

« Pas de feu vert NEXUS, pas d'embarquement. » Le terminal transmet chaque événement dès qu'il survient ; le champ id (identifiant de l'événement dans le système du terminal) rend tout renvoi sans effet. Types : PREANNONCE, GATE_IN, VGM (avec vgm_kg), PLOMB (avec plomb), CHARGE (avec navire, bl), DEPART_NAVIRE (avec navire, voyage), GATE_OUT (sortie d'un conteneur plein).

POST /api/v1/edi/v1/terminal/evenements
X-Nexus-Cle: nxk_…
Content-Type: application/json

{ "evenements": [
  { "id": "ABJT-2026-118204", "type": "GATE_IN", "conteneur": "MSCU1000017", "booking": "BK-2026-1104",
    "navire": "CMA CGM LOME", "plomb": "PL-000123", "code_sh": "0801.31", "survenu_le": "2026-10-11T14:05:00Z" },
  { "id": "ABJT-2026-118230", "type": "VGM", "conteneur": "MSCU1000017", "vgm_kg": 30180, "survenu_le": "2026-10-11T14:40:00Z" }
] }

GET /api/v1/edi/v1/terminal/feu-vert?conteneur=MSCU1000017
→ { "couleur": "VERT", "motifs": [], "avertissements": [], "dossier": "EX-NC26-00012-4", "ape": "APE-NC26-00012.1-7",
    "plomb": "PL-000123", "reference": "FV-261011-MSCU1000017-V…", "le": "2026-10-11T15:02:11Z" }

Feu vert : conteneur déclaré à l'empotage, dossier en exportation et non suspendu, APE délivrée et en validité, redevances couvertes, exportateur actif, plomb constaté conforme, délai d'embarquement respecté (15 jours après le rapport d'empotage), aucune anomalie critique en cours. Anomalies levées par NEXUS : conteneur de produit agricole inconnu, conteneur substitué sous un booking, plomb différent, VGM incohérente, chargé à bord sans feu vert, resté à quai après le départ du navire, ressorti plein du terminal.

3.2 ACE — déposer un bulletin, valider un rapport d'empotage

POST /api/v1/edi/v1/pieces
{
  "dossier": "EX-FC26-00001-6",
  "type_piece": "BULLETIN_QUALITE_P",
  "numero": "ACE/ABJ/QLTE/CAJ/2026-1464",
  "date_piece": "2026-10-09",
  "donnees": { "humidite": 9.2, "grainage": 187, "kor": 41.8, "sacs": 6500 },
  "fichier": { "nom": "bulletin.pdf", "contenu_base64": "JVBERi0x…" }
}

POST /api/v1/edi/v1/pieces/{id}/decision
{ "valider": true }                      ← ou { "valider": false, "motif": "plombs non conformes" }

Les identifiants des pièces à valider figurent dans pieces_attendues[].piece_id de GET /dossiers. Types de pièces courants : BULLETIN_QUALITE_P, BULLETIN_QUALITE_D, BULLETIN_EMPOTAGE_P, BULLETIN_EMPOTAGE_D, CERTIFICAT_POIDS, AMQ, CERTIFICAT_PHYTO, ATTESTATION_DESINFECTION. Seul l'émetteur prévu par la liasse du produit peut déposer une pièce.

3.3 Retrouver un dossier

GET /api/v1/edi/v1/dossiers?booking=BK-2026-0815
GET /api/v1/edi/v1/dossiers?conteneur=MSCU3000011

→ { "version": "1.0", "nombre": 1, "dossiers": [ { "numero": "EX-FC26-00001-6", "statut": "EN_EXPORTATION",
      "exportateur": "…", "booking": "BK-2026-0815", "navire": "MSC AURORA",
      "conteneurs": [ { "numero": "MSCU3000011", "plomb": "PL-0001", "poids_theorique_kg": 24800, "statut": "EMPOTE" } ],
      "pieces_attendues": [ { "type_piece": "CERTIFICAT_POIDS", "ouverte": true, "peut_deposer": true, "statut": null } ] } ] }

3.4 Logiciel d'un exportateur — contrat puis demande

POST /api/v1/edi/v1/contrats            ← mêmes champs que l'écran « Nouveau contrat »
POST /api/v1/edi/v1/contrats/{id}/soumettre
POST /api/v1/edi/v1/dossiers            ← { "contrats": [{ "contrat": "CT C A 1632-0005 0001", "quantite_kg": 48000 }], "nb_tc40": 2, … }

Toute demande d'exportation est adossée à un contrat validé par la DCOM, dans la limite de sa quantité restante.

4. Codes de réponse

Code	Signification
200 / 201	Succès (201 : créé)
400	Donnée invalide ou manquante (message explicite dans `error`)
401	Clé absente, inconnue, invalide, révoquée ou expirée
403	Portée absente, pièce d'un autre émetteur, dossier qui ne vous concerne pas, clé hors API EDI
404	Dossier, contrat ou pièce introuvable
409	Règle de gestion : étape du dossier, pièce déjà traitée, ticket déjà utilisé, quantité dépassée…
422	Clé d'idempotence réutilisée pour un autre contenu

{ "error": "Portée PESAGES absente de la clé d'API 1a2b3c4d" }

5. Sécurité et exploitation

HTTPS obligatoire ; la clé ne doit jamais figurer dans une URL, un journal applicatif ou un courriel.
Une clé par système partenaire ; en cas de fuite, le CCAK la révoque et en émet une nouvelle.
Le CCAK consulte le journal des échanges (date, clé, requête, statut, durée) dans NEXUS EXPORT › Interconnexions EDI.
Contact technique : DSIPE / Service Informatique du CCAK.