API eCMR: checklist per il team di integrazione
Non partire dalla sola chiamata di creazione del documento. L’integrazione deve gestire tutto il ciclo di vita e rendere comprensibile che cosa accade quando un partner o una versione cambia.
Prima di applicare la checklist.
Pubblicato e verificato il . Informazioni generali, non consulenza legale.
Chiedi la specifica della release effettiva.
Ottieni OpenAPI o un contratto equivalente, changelog, limiti, ambiente di prova e modalità di autenticazione del provider scelto. Registra la versione e quali operazioni sono disponibili. Il progetto eCMR della Open Logistics Foundation è un riferimento pubblico utile, non un’API universale né la prova che tutti i provider condividano lo stesso contratto.
Non copiare un endpoint da un vecchio esempio senza controllare repository e release: nell’ecosistema esistono anche componenti legacy archiviati. Le prove devono riferirsi al software che userà il cliente.
Sette controlli oltre al POST iniziale.
- Identità della spedizione, delle consegne e del documento: evita collisioni tra aziende.
- Bozza e revisione: chi può correggere quale dato prima della firma?
- Autorizzazioni: accesso del partner e revoca senza visibilità su altre consegne.
- Firme: identità, ruolo e versione esatta del contenuto sottoscritto.
- Modifiche: cronologia recuperabile e gestione di aggiornamenti concorrenti.
- Eventi: ordine, duplicati, acknowledgement e recupero dei messaggi persi.
- Export: contenuto, riferimenti ed evidenze leggibili fuori dal portale.
Un timeout non prova che la creazione sia fallita.
Nella tua progettazione usa una chiave di idempotenza se il contratto la supporta; altrimenti definisci come ricercare l’operazione precedente prima di ripeterla. Distingui dati rifiutati, accesso negato, conflitto di versione e risposta ancora in attesa. Non inventare un retry automatico dove il provider non documenta il comportamento.
Prova un evento duplicato, una risposta tardiva e una modifica rifiutata dopo firma. Registra ID di correlazione, esito e versione senza inserire token, URL firmati o dati personali nei log condivisi. Sono test proposti, non risultati già ottenuti con un provider.
Una prova ripetibile per ogni scenario.
Definisci input, risposta attesa, effetti osservabili e criterio di fallimento. Un HTTP 200 non basta se il documento è associato alla consegna sbagliata. Il passaggio eFTI richiede un profilo e un’interfaccia separati: non dedurlo dal successo dell’API eCMR.
Fonti e percorso successivo.
Open Logistics Foundation · progetto eCMR ↗
Le indicazioni operative sono una traccia di progettazione, non una verifica già eseguita sul tuo flusso. Il check gratuito usa selezioni generiche nel browser e non riceve documenti. Connettori e accesso a pagamento restano in preparazione.
Tutte le guide italiane