Feronix Portale Clienti ATLAS

API cliente

Collega direttamente il tuo sistema ERP a Feronix — REST, JSON su HTTPS, legato al tenant, con idempotenza e pre-validazione.

I dati trasmessi tramite API vengono sdoganati da Feronix sotto la propria EORI e i propri conti di dilazione. Tu come cliente trasmetti i dati di consegna e di spedizione; Feronix effettua la dichiarazione doganale come dichiarante e rappresentante. Le merci vengono consegnate direttamente al magazzino Feronix.

Quando usare l'API

L'API cliente è la via per il trasferimento automatizzato dai sistemi ERP (SAP, Microsoft Dynamics, Odoo, Oracle) e per tutti gli scenari di integrazione in cui vuoi trasferire consegne, manifesti di colli, dati di spedizione e documenti automaticamente. Sostituisce l'immissione manuale nel portale e consente l'automazione end-to-end dall'ERP alla dogana. Le consegne trasmesse sono destinate al magazzino Feronix; Feronix agisce come dichiarante e rappresentante nel procedimento doganale.

Formati di input supportati

  • Payload REST strutturati — JSON su HTTPS
  • JSON — per dati singoli e bundle più piccoli
  • CSV — per l'importazione di dati massivi
  • Bundle di consegna NOVA-POSHTA — nel formato NOVA, le righe articolo vengono consolidate per numero di pacco in pacchi fisici e nelle relative posizioni merce sottostanti

I dati master dei pacchi in conflitto, le assegnazioni duplicate o mancanti, importi, pesi, codici HS e componenti di indirizzo non validi vengono rilevati prima della creazione.

Autenticazione

curl -H 'X-Api-Key: ' \
     -H 'Accept-Language: de' \
     https://atlas.feronix.tech/customer/me

La chiave determina il tenant lato server. Un customer_id nel body non deve mai estendere questo ambito. Lingue supportate: de, en, fr, es, zh, ru, uk.

Cosa puoi controllare tramite l'API

  1. Creare consegna
  2. Trasmettere dati di consegna e trasporto
  3. Importare lista colli o manifesto basato su articoli
  4. Consolidare pacchi e posizioni merce
  5. Caricare e assegnare fatture, prove del valore, T1 e altri documenti
  6. Recuperare la validazione
  7. Inviare la dichiarazione IMPOST esplicitamente
  8. Interrogare stato, errori, messaggi e documenti
  9. Correggere dati errati e reinviare con un nuovo numero di messaggio

Sequenza consigliata

  1. Definire il caso T1 — se esiste una procedura di transito esistente, prima POST /warehouse/delivery-documents/t1. Se deve essere creato un nuovo T1, impostare t1_mode=create nella consegna.
  2. Creare consegna — POST /warehouse/delivery-manifests per la consegna inclusa scadenza e lista colli completa.
  3. Caricare prova del valore — POST /warehouse/value-evidence per fattura/prova del valore.
  4. Pre-validazione — POST /customer/shipments/validate per il pre-check. Una validazione riuscita non invia nulla alla dogana.
  5. Creare spedizione — POST /customer/shipments per creare/inviare secondo il payload.
  6. Monitorare lo stato — GET /customer/shipments/{lrn} e processo doganale tramite GET /customer/declarations/{lrn}.
  7. Generare T1 — con t1_mode=create dopo l'inserimento completo, generare il T1 tramite POST /warehouse/deliveries/{delivery_number}/t1-xml.

Idempotenza

Le chiavi di idempotenza impediscono la creazione duplicata in caso di ripetizioni di rete o scanner. Un tentativo logicamente identico deve usare la stessa riferimento esterno o identificatore di idempotenza. Un reinvio corretto riceve un nuovo numero di messaggio ATLAS. Il timeout non è uguale al rifiuto — prima di riprovare, verifica se la richiesta è stata accettata e solo la risposta è andata persa.

Endpoint principali

MetodoEndpointScopo
POST/warehouse/delivery-manifestsCreare consegna e pacchi atomicamente (consegna al magazzino Feronix)
POST/warehouse/value-evidenceCaricare prova del valore
POST/customer/shipments/validatePre-validazione (non invia nulla alla dogana)
POST/customer/shipmentsCreare/inviare spedizione
GET/customer/shipments/{lrn}Stato della spedizione
GET/customer/shipments/{lrn}/impost-xmlEsportare IMPOST-XML (ICOMDA)
GET/customer/shipments/{lrn}/standard-clearance/dossier.pdfFascicolo doganale PDF
GET/customer/shipments/{lrn}/standard-clearance/dossier.zipFascicolo doganale ZIP
POST/customer/shipments/{lrn}/standard-clearance/atlas-xmlGenerare DECDFA-XML
GET/customer/declarations/{lrn}Processo doganale con messaggi e decisione
POST/customer/declarations/{lrn}/resubmitReinvio corretto
POST/customer/suma/xmlEsportare SumA-XML
POST/warehouse/transit-ordersCreare ordine di transito
POST/warehouse/transit-orders/{id}/xmlGenerare T1-XML (DETPDD)
POST/customer/customs-xml/validateConvalidare XML rispetto all'XSD originale
GET/customer/meProfilo tenant
GET/customer/me/identitiesIdentità doganali (EORI/NL) — identità doganali di Feronix, sotto le quali Feronix agisce come dichiarante, non le tue
GET/customer/me/mandatesMandati di rappresentanza — mandati sotto i quali Feronix agisce per te come rappresentante nel procedimento doganale
GET/customer/reference/hs-searchRicerca codice HS

Codici di errore

Gli errori API contengono stato HTTP, un codice di errore stabile, testo localizzato e, ove possibile, il percorso del campo interessato.

StatoSignificatoAzione
400Richiesta tecnicamente illeggibileVerificare JSON, charset o file
401Chiave API mancante o non validaInviare l'X-Api-Key del tenant corretto
403Permesso mancanteVerificare il ruolo utente o l'approvazione API
404Oggetto non trovato nel tenantVerificare LRN, numero di consegna, codice a barre e tenant
409Conflitto logicoCorreggere stato, unicità o dati dipendenti
422Campo/dipendenza obbligatorio violatoElaborare completamente gli indizi specifici per campo
500/502/503Errore tecnicoNon reinviare alla cieca — riprovare con la stessa chiave di idempotenza
→ IMPOST Apri un conto