Feronix ATLAS 客户门户

客户 API

将您的 ERP 系统直接连接到 Feronix——REST、基于 HTTPS 的 JSON、 租户绑定，具备幂等性和预校验。

通过 API 传输的数据由 Feronix 在自有 EORI 和自有递延账户下清关。您作为客户传输交运 和货件数据；Feronix 作为申报人和 代表承担海关申报。货物直接送达 Feronix 仓库。

何时使用 API

客户 API 是从 ERP 系统 （SAP、Microsoft Dynamics、Odoo、Oracle）自动传输的路径，适用于所有 您希望自动传输交运、包裹清单、货件数据和文档的 集成场景。它替代门户中的手动录入，并 实现从 ERP 到海关的端到端自动化。传输的 交运指定送达 Feronix 仓库；Feronix 作为申报人 和代表参与海关程序。

支持的输入格式

  • 结构化 REST 负载——基于 HTTPS 的 JSON
  • 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，通过 POST /warehouse/deliveries/{delivery_number}/t1-xml 生成 T1。

幂等性

幂等键防止在网络或 扫码器重试时重复创建。逻辑相同的重试必须使用相同的 外部参考或幂等标识符。更正的 重新提交获得新的 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.pdf海关档案 PDF
GET/customer/shipments/{lrn}/standard-clearance/dossier.zip海关档案 ZIP
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依据原始 XSD 校验 XML
GET/customer/me租户档案
GET/customer/me/identities海关身份（EORI/NL）——Feronix 的海关身份，Feronix 以申报人身份出现，而非您自己的
GET/customer/me/mandates代理授权——Feronix 在海关程序中作为您的代表出现的授权
GET/customer/reference/hs-searchHS 编码搜索

错误代码

API 错误包含 HTTP 状态、稳定的错误代码、本地化文本 以及（如可能）受影响的字段路径。

状态含义操作
400请求技术上不可读检查 JSON、字符集或文件
401API 密钥缺失或无效发送正确租户的 X-Api-Key
403缺少权限检查用户角色或 API 审批
404在租户中未找到对象检查 LRN、交运编号、条码和租户
409逻辑冲突更正状态、唯一性或依赖数据
422必填字段/依赖违反完整处理字段特定提示
500/502/503技术错误不要盲目重发——使用相同幂等键重试
→ IMPOST 开立账户