Kunden-API

Binden Sie Ihr ERP-System direkt an Feronix an — REST, JSON über HTTPS, mandantengebunden, mit Idempotenz und Vorabprüfung.

Die über die API übermittelten Daten werden von Feronix unter eigener EORI und eigenen Aufschubkonten verzollt. Sie als Kunde übermitteln Lieferungs- und Sendungsdaten; Feronix übernimmt die Zollanmeldung als Anmelder und Vertreter. Bei Full Service wird die Ware direkt ins Feronix-Lager geliefert; bei reiner LVS-Nutzung verwalten Sie Ihre Bestände im eigenen Lager.

Wann Sie die API nutzen

Die Kunden-API ist der Weg für automatisierte Übergabe aus ERP-Systemen (SAP, Microsoft Dynamics, Odoo, Oracle) und für alle Integrationsszenarien, in denen Sie Lieferungen, Paketmanifeste, Sendungsdaten und Dokumente maschinell übergeben wollen. Sie ersetzt manuelle Erfassung im Portal und ermöglicht End-to-End-Automatisierung vom ERP bis zum Zoll. Je nach gebuchtem Paket steuern Sie reine Zollvorgänge, die scanbasierte Lagerverwaltung im eigenen Haus oder das physische Full-Service-Fulfillment im Feronix-Lager.

Unterstützte Eingangsformate

Strukturierte REST-Nutzdaten — JSON über HTTPS
JSON — für Einzeldaten und kleinere Bündel
CSV — für Massendatenübernahme
NOVA-POSHTA-Lieferungsbündel — beim NOVA-Format werden Positionszeilen anhand der Paketnummer zu physischen Paketen und darunterliegenden Warenpositionen konsolidiert

Widersprüchliche Paketstammdaten, doppelte oder fehlende Zuordnungen, ungültige Beträge, Gewichte, HS-Codes und Adressbestandteile werden vor Anlage erkannt.

Authentifizierung

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

Der Schlüssel bestimmt den Mandanten serverseitig. Eine customer_id im Inhalt darf diesen Geltungsbereich niemals erweitern. Unterstützte Sprachen: de, en, fr, es, zh, ru, uk.

Was Sie über die API steuern können

Lieferung anlegen
Lieferungs- und Transportdaten übermitteln
Paketliste beziehungsweise positionsbezogenes Manifest importieren
Pakete und Warenpositionen konsolidieren
Rechnungen, Wertnachweise, T1 und weitere Dokumente hochladen und zuordnen
Validierung abrufen
IMPOST-Anmeldung ausdrücklich einreichen
Status, Fehler, Nachrichten und Dokumente abfragen
fehlerhafte Daten berichtigen und mit neuer Nachrichtennummer erneut übermitteln

Empfohlene Reihenfolge

T1-Fall festlegen — bei vorhandenem Versandverfahren zuerst POST /warehouse/delivery-documents/t1. Soll ein neues T1 erzeugt werden, in der Lieferung t1_mode=create setzen.
Lieferung anlegen — POST /warehouse/delivery-manifests für Lieferung samt Deadline und kompletter Paketliste.
Wertnachweis hochladen — POST /warehouse/value-evidence für Rechnung/Wertnachweis.
Vorabprüfung — POST /customer/shipments/validate zur Vorprüfung. Eine erfolgreiche Validierung sendet noch nichts an den Zoll.
Sendung anlegen — POST /customer/shipments zum Anlegen/Übermitteln gemäss Payload.
Status verfolgen — GET /customer/shipments/{lrn} und Zollvorgang über GET /customer/declarations/{lrn}.
T1 erzeugen — bei t1_mode=create nach vollständiger Erfassung das T1 über POST /warehouse/deliveries/{delivery_number}/t1-xml.

Idempotenz

Idempotenzschlüssel verhindern Doppelanlagen bei Netzwerk- oder Scannerwiederholungen. Eine fachlich identische Wiederholung muss dieselbe externe Referenz bzw. Idempotenzkennung verwenden. Eine korrigierte Neuübermittlung erhält eine neue ATLAS-Nachrichtennummer. Timeout ist nicht gleich Ablehnung — vor Wiederholung prüfen, ob die Anfrage angenommen und nur die Antwort verloren ging.

Kern-Endpunkte

Methode	Endpunkt	Zweck
POST	`/warehouse/delivery-manifests`	Lieferung und Pakete atomar anlegen (Lieferung ins Feronix-Lager)
POST	`/warehouse/value-evidence`	Wertnachweis hochladen
POST	`/customer/shipments/validate`	Vorabprüfung (sendet nichts an den Zoll)
POST	`/customer/shipments`	Sendung anlegen/übermitteln
GET	`/customer/shipments/{lrn}`	Sendungsstatus
GET	`/customer/shipments/{lrn}/impost-xml`	IMPOST-XML (ICOMDA) exportieren
GET	`/customer/shipments/{lrn}/standard-clearance/dossier.pdf`	Zollmappe PDF
GET	`/customer/shipments/{lrn}/standard-clearance/dossier.zip`	Zollmappe ZIP
POST	`/customer/shipments/{lrn}/standard-clearance/atlas-xml`	DECDFA-XML erzeugen
GET	`/customer/declarations/{lrn}`	Zollvorgang mit Nachrichten und Bescheid
POST	`/customer/declarations/{lrn}/resubmit`	Korrigierte Neuübermittlung
POST	`/customer/suma/xml`	SumA-XML exportieren
POST	`/warehouse/transit-orders`	Transitauftrag anlegen
POST	`/warehouse/transit-orders/{id}/xml`	T1-XML (DETPDD) erzeugen
POST	`/customer/customs-xml/validate`	XML gegen Original-XSD prüfen
GET	`/customer/me`	Mandantenprofil
GET	`/customer/me/identities`	Zollidentitäten (EORI/NL) — Feronix-Zollidentitäten, unter denen Feronix als Anmelder auftritt, nicht Ihre eigenen
GET	`/customer/me/mandates`	Vertretungsmandate — Mandate, unter denen Feronix für Sie als Vertreter im Zollverfahren auftritt
GET	`/customer/reference/hs-search`	HS-Code-Suche

Fehlercodes

API-Fehler enthalten HTTP-Status, stabilen Fehlercode, lokalisierten Text und soweit möglich den betroffenen Feldpfad.

Status	Bedeutung	Massnahme
400	Anfrage technisch unlesbar	JSON, Zeichensatz oder Datei prüfen
401	API-Schlüssel fehlt oder ungültig	X-Api-Key des richtigen Mandanten senden
403	Berechtigung fehlt	Benutzerrolle oder API-Freigabe prüfen
404	Objekt im Mandanten nicht gefunden	LRN, Lieferungsnummer, Barcode und Mandant prüfen
409	Fachlicher Konflikt	Status, Eindeutigkeit oder abhängige Daten korrigieren
422	Pflichtfeld/Abhängigkeit verletzt	Feldbezogene Hinweise vollständig abarbeiten
500/502/503	Technischer Fehler	Nicht blind doppelt senden — mit gleichem Idempotenzschlüssel wiederholen

→ IMPOST Konto eröffnen