API del cliente

Cuándo usar la API

La API del cliente es la vía para la transferencia automatizada desde sistemas ERP (SAP, Microsoft Dynamics, Odoo, Oracle) y para todos los escenarios de integración en los que desea transferir entregas, manifiestos de bultos, datos de envío y documentos automáticamente. Sustituye la entrada manual en el portal y habilita la automatización de extremo a extremo desde ERP a aduanas. Las entregas transmitidas están destinadas al almacén de Feronix; Feronix actúa como declarante y representante en el procedimiento aduanero.

Formatos de entrada admitidos

• Cargas REST estructuradas — JSON sobre HTTPS
• JSON — para datos individuales y paquetes más pequeños
• CSV — para importación masiva de datos
• Paquetes de entrega NOVA-POSHTA — en el formato NOVA, las líneas de artículos se consolidan por número de bulto en paquetes físicos y sus posiciones de mercancías subyacentes

Los datos maestros de bultos conflictivos, asignaciones duplicadas o faltantes, importes, pesos, códigos HS y componentes de dirección no válidos se detectan antes de la creación.

Autenticación

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

La clave determina el inquilino en el lado del servidor. Un customer_id en el cuerpo nunca debe ampliar este ámbito. Idiomas admitidos: de, en, fr, es, zh, ru, uk.

Lo que puede controlar vía la API

1. Crear entrega
2. Transmitir datos de entrega y transporte
3. Importar lista de bultos o manifiesto basado en posiciones
4. Consolidar bultos y posiciones de mercancías
5. Cargar y asignar facturas, pruebas de valor, T1 y otros documentos
6. Recuperar validación
7. Presentar declaración IMPOST explícitamente
8. Consultar estado, errores, mensajes y documentos
9. Corregir datos erróneos y volver a presentar con un nuevo número de mensaje

Secuencia recomendada

1. Definir caso T1 — si existe un procedimiento de tránsito existente, primero POST /warehouse/delivery-documents/t1. Si se debe crear un T1 nuevo, establezca t1_mode=create en la entrega.
2. Crear entrega — POST /warehouse/delivery-manifests para entrega incluyendo plazo y lista de bultos completa.
3. Cargar prueba de valor — POST /warehouse/value-evidence para factura/prueba de valor.
4. Validación previa — POST /customer/shipments/validate para verificación previa. Una validación exitosa no envía nada a aduanas todavía.
5. Crear envío — POST /customer/shipments para crear/presentar según la carga.
6. Seguir estado — GET /customer/shipments/{lrn} y proceso aduanero vía GET /customer/declarations/{lrn}.
7. Generar T1 — con t1_mode=create tras entrada completa, genere el T1 vía POST /warehouse/deliveries/{delivery_number}/t1-xml.

Idempotencia

Las claves de idempotencia evitan la creación duplicada en reintentos de red o escáner. Un reintento lógicamente idéntico debe usar la misma referencia externa o identificador de idempotencia. Un reenvío corregido recibe un nuevo número de mensaje ATLAS. El tiempo de espera agotado no es lo mismo que rechazo — antes de reintentar, verifique si la solicitud fue aceptada y solo se perdió la respuesta.

Endpoints principales

Método	Endpoint	Propósito
POST	/warehouse/delivery-manifests	Crear entrega y bultos atómicamente (entrega al almacén de Feronix)
POST	/warehouse/value-evidence	Cargar prueba de valor
POST	/customer/shipments/validate	Validación previa (no envía nada a aduanas)
POST	/customer/shipments	Crear/presentar envío
GET	/customer/shipments/{lrn}	Estado del envío
GET	/customer/shipments/{lrn}/impost-xml	Exportar IMPOST-XML (ICOMDA)
GET	/customer/shipments/{lrn}/standard-clearance/dossier.pdf	Expediente aduanero PDF
GET	/customer/shipments/{lrn}/standard-clearance/dossier.zip	Expediente aduanero ZIP
POST	/customer/shipments/{lrn}/standard-clearance/atlas-xml	Generar DECDFA-XML
GET	/customer/declarations/{lrn}	Proceso aduanero con mensajes y decisión
POST	/customer/declarations/{lrn}/resubmit	Reenvío corregido
POST	/customer/suma/xml	Exportar SumA-XML
POST	/warehouse/transit-orders	Crear orden de tránsito
POST	/warehouse/transit-orders/{id}/xml	Generar T1-XML (DETPDD)
POST	/customer/customs-xml/validate	Validar XML contra XSD original
GET	/customer/me	Perfil del inquilino
GET	/customer/me/identities	Identidades aduaneras (EORI/NL) — identidades aduaneras de Feronix bajo las cuales Feronix actúa como declarante, no las suyas
GET	/customer/me/mandates	Mandatos de representación — Mandatos bajo los cuales Feronix actúa como representante para usted en los procedimientos aduaneros
GET	/customer/reference/hs-search	Búsqueda de código HS

Códigos de error

Los errores de API contienen estado HTTP, un código de error estable, texto localizado y, cuando es posible, la ruta del campo afectado.

Estado	Significado	Acción
400	Solicitud técnicamente ilegible	Verificar JSON, charset o archivo
401	Clave API faltante o no válida	Enviar X-Api-Key del inquilino correcto
403	Permiso faltante	Verificar rol de usuario o aprobación de API
404	Objeto no encontrado en el inquilino	Verificar LRN, número de entrega, código de barras e inquilino
409	Conflicto lógico	Corregir estado, unicidad o datos dependientes
422	Campo/dependencia obligatorio vulnerado	Procesar las indicaciones específicas de campo completamente
500/502/503	Error técnico	No reenviar a ciegas — reintentar con la misma clave de idempotencia