Feronix Клієнтський портал ATLAS

Клієнтський API

Підключіть вашу ERP-систему безпосередньо до Feronix — REST, JSON через HTTPS, прив'язка до тенанта, з ідемпотентністю та попередньою валідацією.

Дані, передані через API, оформляються Feronix під власним EORI та власними рахунками відстрочки. Ви як клієнт передаєте дані доставки та відправлень; Feronix бере на себе митну декларацію як декларант та представник. Товари доставляються безпосередньо на склад Feronix.

Коли використовувати API

Клієнтський API — це шлях для автоматизованої передачі з ERP-систем (SAP, Microsoft Dynamics, Odoo, Oracle) та для всіх сценаріїв інтеграції, у яких ви хочете автоматично передавати доставки, маніфести посилок, дані відправлень та документи. Він замінює ручне введення на порталі та забезпечує наскрізну автоматизацію від ERP до митниці. Передані доставки призначені для складу Feronix; Feronix виступає як декларант та представник у митній процедурі.

Підтримувані формати вводу

  • Структуровані REST-запити — JSON через HTTPS
  • JSON — для окремих даних та невеликих пакетів
  • CSV — для масового імпорту даних
  • Пакети доставки NOVA-POSHTA — у форматі NOVA, рядки товарів консолідуються за номером посилки у фізичні посилки та їхні базові товарні позиції

Конфліктні майстер-дані посилок, дублікати або відсутні призначення, недійсні суми, ваги, HS-коди та компоненти адреси виявляються перед створенням.

Автентифікація

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

Ключ визначає тенанта на стороні сервера. customer_id у тілі запиту ніколи не повинен розширювати цю область. Підтримувані мови: de, en, fr, es, zh, ru, uk.

Що ви можете контролювати через API

  1. Створити доставку
  2. Передати дані доставки та транспортування
  3. Імпортувати список посилок або маніфест на основі товарів
  4. Консолідувати посилки та товарні позиції
  5. Завантажити та призначити рахунки, докази вартості, T1 та інші документи
  6. Отримати валідацію
  7. Подати декларацію IMPOST явно
  8. Запитати статус, помилки, повідомлення та документи
  9. Виправити помилкові дані та повторно подати з новим номером повідомлення

Рекомендована послідовність

  1. Визначити випадок T1 — якщо існує наявна транзитна процедура, спочатку POST /warehouse/delivery-documents/t1. Якщо новий T1 повинен бути створений, встановіть t1_mode=create у доставці.
  2. Створити доставку — POST /warehouse/delivery-manifests для доставки включно з дедлайном та повним списком посилок.
  3. Завантажити докази вартості — POST /warehouse/value-evidence для рахунку/доказу вартості.
  4. Попередня валідація — POST /customer/shipments/validate для попередньої перевірки. Успішна валідація нічого ще не надсилає до митниці.
  5. Створити відправлення — POST /customer/shipments для створення/подання згідно з запитом.
  6. Відстежувати статус — GET /customer/shipments/{lrn} та митний процес через GET /customer/declarations/{lrn}.
  7. Згенерувати T1 — з t1_mode=create після повного введення згенеруйте T1 через POST /warehouse/deliveries/{delivery_number}/t1-xml.

Ідемпотентність

Ключі ідемпотентності запобігають дублюванню створення при мережевих або сканерних повторних спробах. Логічно ідентична повторна спроба повинна використовувати той самий зовнішній референс або ідемпотентний ідентифікатор. Виправлена повторна подача отримує новий номер повідомлення ATLAS. Тайм-аут не дорівнює відхиленню — перед повторною спробою перевірте, чи запит був прийнятий, а лише відповідь була втрачена.

Основні ендпоінти

МетодЕндпоінтПризначення
POST/warehouse/delivery-manifestsСтворити доставку та посилки атомарно (доставка на склад Feronix)
POST/warehouse/value-evidenceЗавантажити докази вартості
POST/customer/shipments/validateПопередня валідація (нічого не надсилає до митниці)
POST/customer/shipmentsСтворити/подати відправлення
GET/customer/shipments/{lrn}Статус відправлення
GET/customer/shipments/{lrn}/impost-xmlЕкспорт IMPOST-XML (ICOMDA)
GET/customer/shipments/{lrn}/standard-clearance/dossier.pdfPDF митної справи
GET/customer/shipments/{lrn}/standard-clearance/dossier.zipZIP митної справи
POST/customer/shipments/{lrn}/standard-clearance/atlas-xmlЗгенерувати DECDFA-XML
GET/customer/declarations/{lrn}Митний процес з повідомленнями та рішенням
POST/customer/declarations/{lrn}/resubmitВиправлена повторна подача
POST/customer/suma/xmlЕкспорт SumA-XML
POST/warehouse/transit-ordersСтворити транзитне замовлення
POST/warehouse/transit-orders/{id}/xmlЗгенерувати T1-XML (DETPDD)
POST/customer/customs-xml/validateВалідувати XML за оригінальним XSD
GET/customer/meПрофіль тенанта
GET/customer/me/identitiesМитні ідентичності (EORI/NL) — ідентичності Feronix, під якими Feronix виступає як декларант, а не ваші власні
GET/customer/me/mandatesМандати представництва — мандати, під якими Feronix виступає для вас як представник у митній процедурі
GET/customer/reference/hs-searchПошук HS-коду

Коди помилок

Помилки API містять HTTP-статус, стабільний код помилки, локалізований текст та, за можливості, шлях до відповідного поля.

СтатусЗначенняДія
400Запит технічно нечитабельнийПеревірте JSON, кодування або файл
401API-ключ відсутній або недійснийНадішліть X-Api-Key правильного тенанта
403Відсутній дозвілПеревірте роль користувача або затвердження API
404Об'єкт не знайдено у тенантіПеревірте LRN, номер доставки, штрихкод та тенанта
409Логічний конфліктВиправте статус, унікальність або залежні дані
422Порушення обов'язкового поля/залежностіОбробіть підказки для конкретних полів повністю
500/502/503Технічна помилкаНе надсилайте всліпу — повторіть з тим самим ключем ідемпотентності
→ IMPOST Відкрити рахунок