API client

Quand utiliser l'API

L'API client est la voie pour le transfert automatisé depuis les systèmes ERP (SAP, Microsoft Dynamics, Odoo, Oracle) et pour tous les scénarios d'intégration dans lesquels vous souhaitez transférer des livraisons, des manifestes de colis, des données d'expédition et des documents automatiquement. Elle remplace la saisie manuelle dans le portail et permet une automatisation de bout en bout de l'ERP à la douane. Les livraisons transmises sont destinées à l'entrepôt Feronix ; Feronix agit en tant que déclarant et représentant dans la procédure douanière.

Formats d'entrée pris en charge

• Charges utiles REST structurées — JSON sur HTTPS
• JSON — pour les données individuelles et les petits lots
• CSV — pour l'import de données en masse
• Lots de livraison NOVA-POSHTA — au format NOVA, les lignes d'articles sont consolidées par numéro de colis en colis physiques et leurs articles de marchandises sous-jacents

Les données maîtresses de colis conflictuelles, les affectations en double ou manquantes, les montants, poids, codes HS et composants d'adresse invalides sont détectés avant la création.

Authentification

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

La clé détermine le locataire côté serveur. Un customer_id dans le corps ne doit jamais étendre ce périmètre. Langues prises en charge : de, en, fr, es, zh, ru, uk.

Ce que vous pouvez contrôler via l'API

1. Créer une livraison
2. Transmettre les données de livraison et de transport
3. Importer la liste de colis ou le manifeste basé sur les articles
4. Consolider les colis et articles de marchandises
5. Télécharger et affecter des factures, des preuves de valeur, des T1 et d'autres documents
6. Récupérer la validation
7. Soumettre la déclaration IMPOST explicitement
8. Consulter le statut, les erreurs, les messages et les documents
9. Corriger les données erronées et soumettre à nouveau avec un nouveau numéro de message

Séquence recommandée

1. Définir le cas T1 — si une procédure de transit existante existe, d'abord POST /warehouse/delivery-documents/t1. Si un nouveau T1 doit être créé, définir t1_mode=create dans la livraison.
2. Créer la livraison — POST /warehouse/delivery-manifests pour la livraison incluant l'échéance et la liste de colis complète.
3. Télécharger la preuve de valeur — POST /warehouse/value-evidence pour la facture/preuve de valeur.
4. Pré-validation — POST /customer/shipments/validate pour la pré-vérification. Une validation réussie n'envoie rien à la douane pour le moment.
5. Créer l'expédition — POST /customer/shipments pour créer/soumettre selon la charge utile.
6. Suivre le statut — GET /customer/shipments/{lrn} et le processus douanier via GET /customer/declarations/{lrn}.
7. Générer le T1 — avec t1_mode=create après une saisie complète, générer le T1 via POST /warehouse/deliveries/{delivery_number}/t1-xml.

Idempotence

Les clés d'idempotence empêchent la création en double lors des nouvelles tentatives réseau ou scanner. Une nouvelle tentative logiquement identique doit utiliser la même référence externe ou le même identifiant d'idempotence. Une resoumission corrigée reçoit un nouveau numéro de message ATLAS. Un délai d'attente n'est pas identique à un rejet — avant de réessayer, vérifiez si la demande a été acceptée et seule la réponse a été perdue.

Endpoints principaux

Méthode	Endpoint	Objet
POST	/warehouse/delivery-manifests	Créer livraison et colis atomiquement (livraison à l'entrepôt Feronix)
POST	/warehouse/value-evidence	Télécharger la preuve de valeur
POST	/customer/shipments/validate	Pré-validation (n'envoie rien à la douane)
POST	/customer/shipments	Créer/soumettre l'expédition
GET	/customer/shipments/{lrn}	Statut de l'expédition
GET	/customer/shipments/{lrn}/impost-xml	Exporter l'XML IMPOST (ICOMDA)
GET	/customer/shipments/{lrn}/standard-clearance/dossier.pdf	Dossier douanier PDF
GET	/customer/shipments/{lrn}/standard-clearance/dossier.zip	Dossier douanier ZIP
POST	/customer/shipments/{lrn}/standard-clearance/atlas-xml	Générer le DECDFA-XML
GET	/customer/declarations/{lrn}	Processus douanier avec messages et décision
POST	/customer/declarations/{lrn}/resubmit	Resoumission corrigée
POST	/customer/suma/xml	Exporter l'XML SumA
POST	/warehouse/transit-orders	Créer un ordre de transit
POST	/warehouse/transit-orders/{id}/xml	Générer l'XML T1 (DETPDD)
POST	/customer/customs-xml/validate	Valider le XML par rapport au XSD original
GET	/customer/me	Profil du locataire
GET	/customer/me/identities	Identités douanières (EORI/NL) — identités douanières de Feronix sous lesquelles Feronix agit en tant que déclarant, non les vôtres
GET	/customer/me/mandates	Mandats de représentation — Mandats sous lesquels Feronix agit en tant que représentant pour vous dans les procédures douanières
GET	/customer/reference/hs-search	Recherche de code HS

Codes d'erreur

Les erreurs API contiennent le statut HTTP, un code d'erreur stable, du texte localisé et, si possible, le chemin du champ concerné.

Statut	Signification	Action
400	Demande techniquement illisible	Vérifier le JSON, le charset ou le fichier
401	Clé API manquante ou invalide	Envoyer le X-Api-Key du bon locataire
403	Permission manquante	Vérifier le rôle utilisateur ou l'approbation API
404	Objet introuvable dans le locataire	Vérifier le LRN, le numéro de livraison, le code-barres et le locataire
409	Conflit logique	Corriger le statut, l'unicité ou les données dépendantes
422	Champ/dépendance obligatoire violé	Traiter complètement les indications spécifiques aux champs
500/502/503	Erreur technique	Ne pas renvoyer aveuglément — réessayer avec la même clé d'idempotence