Desarrolladores

API de comprobación aduanera

La misma comprobación que en este sitio, invocada desde su propio software. Usted envía un expediente en JSON y recibe una puntuación sobre 100, los puntos bloqueantes, las alertas y las acciones recomendadas — con códigos de anomalía estables y mensajes traducidos a las 24 lenguas oficiales de la Unión Europea.

Crear una clave Especificación OpenAPI

Es una API de servidor a servidor. Una clave de API es un secreto. Las llamadas desde un navegador no están soportadas y no se envía ninguna cabecera CORS en las rutas autenticadas: una clave que llega a un navegador es una clave filtrada.

Visión general

La API expone el motor de comprobación del validador: trece reglas transversales, cuatro reglas de completitud documental y los validadores propios de cada sistema declarativo. No transmite nada ni consulta ninguna base arancelaria — comprueba la coherencia interna y el formato de su expediente antes de que prepare la declaración.

Todas las rutas llevan el prefijo de su versión. Las rutas de descubrimiento y la especificación son públicas: un integrador, o un agente, puede leer el esquema antes de tener una clave.

Ruta	Función	Autenticación
POST/v1/checks	Comprueba un expediente y devuelve el informe completo	Clave requerida
POST/v1/checks/batch	Comprueba hasta 25 expedientes en una llamada	Clave requerida
GET/v1/me	Devuelve la clave actual y su cuota, sin consumirla	Clave requerida
GET/v1/declaration-types	Lista los tipos de declaración reconocidos	Pública
GET/v1/declaration-types/{type}	Describe los campos esperados para un tipo	Pública
GET/v1/openapi.json	La especificación OpenAPI 3.1 de esta API	Pública

Autenticación

La API se autentica mediante un token portador. El token se muestra una sola vez, al crearlo: solo se guarda su huella, así que una clave perdida se sustituye, nunca se recupera.

Puede mantener tres claves activas a la vez, lo que permite rotar una clave sin interrumpir su integración: cree la nueva, despliéguela y revoque la antigua.

1Cree una clave desde su cuenta, en «Claves de API».
2Envíela en la cabecera Authorization de cada petición.
3Revóquela si se filtra: el corte es inmediato y el contenido de los expedientes enviados con esa clave se purga acto seguido.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Primera comprobación

Un expediente se compone de un tipo, una cabecera y líneas de mercancías. Todos los valores son cadenas de texto: el motor se encarga de interpretarlos. Los nombres de los campos se descubren en tiempo de ejecución, tipo por tipo.

La respuesta llega de inmediato; después no hay nada que consultar.

Petición

curl https://www.customs-check.com/api/v1/checks \
  -H "Authorization: Bearer $CUSTOM_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "import-export",
    "reference": "PO-2026-114",
    "header": {
      "flow": "IM",
      "shipmentCountry": "CN",
      "destinationCountry": "FR",
      "incoterm": "FOB",
      "companyName": "Acme SAS",
      "companyCountry": "FR",
      "eori": "FR12345678900012",
      "transportMode": "sea",
      "currency": "USD",
      "invoiceTotal": "12500"
    },
    "items": [
      {
        "description": "Leather sport shoes",
        "hsCode": "6403990000",
        "quantity": "500",
        "value": "12500",
        "origin": "VN",
        "grossMass": "850",
        "netMass": "800"
      }
    ],
    "documents": { "commercialInvoice": "available", "packingList": "missing" }
  }'

Leer la respuesta

Cada anomalía lleva a la vez una identidad de máquina y una frase legible. Construya su lógica sobre la identidad de máquina: no cambia sin un cambio de versión.

severity · code · path · rule: Contrato estableEstables. Pueden aparecer códigos nuevos; los existentes no se renombran sin un cambio de versión.
field · message · text: Solo visualizaciónTraducidos para su visualización. Pueden reformularse en cualquier momento: no los compare nunca en su código.
engine.version: Cambia en cuanto una evolución de las reglas modifica la puntuación de un expediente sin cambios. Archívela junto con sus informes.

El campo «path» refleja la forma de su petición, de modo que puede asociar una anomalía directamente al campo correspondiente de su propia interfaz.

header.<campo> · items.<n>.<campo> · documents.<category> · global

Respuesta

{
  "id": "4c749e25-3408-48f9-b3ca-b18a7ad84681",
  "createdAt": "2026-09-16T12:46:13.186Z",
  "type": "import-export",
  "locale": "en",
  "reference": "PO-2026-114",
  "score": 90,
  "level": "good",
  "counts": { "errors": 0, "warnings": 2, "infos": 0 },
  "documents": { "commercialInvoice": "available", "packingList": "missing" },
  "issues": [
    {
      "severity": "warning",
      "code": "docPackingListMissing",
      "path": "documents.packingList",
      "rule": "DOC-002",
      "params": null,
      "field": "Packing list",
      "message": "Packing list not provided",
      "text": "Packing list not provided"
    },
    {
      "severity": "warning",
      "code": "docTransportMissing",
      "path": "documents.transportDocument",
      "rule": "DOC-003",
      "params": null,
      "field": "Transport document (B/L, AWB, CMR)",
      "message": "Transport document not provided",
      "text": "Transport document not provided"
    }
  ],
  "actions": [
    { "severity": "warning", "code": "docPackingListMissing",
      "path": "documents.packingList", "text": "Add: Packing list" }
  ],
  "tips": [],
  "engine": { "version": "1.0.0", "rules": 13 }
}

Descubrir los campos

Los tipos de declaración y sus campos son públicos, no hace falta clave. Es la ruta para construir un formulario, alimentar un mapeo desde su ERP o dar a un agente el esquema que debe rellenar.

Los nombres devueltos aquí son exactamente las claves que hay que usar en la cabecera y en cada línea de mercancía. Las listas de opciones llegan resueltas y traducidas; añada el parámetro para omitirlas si la respuesta le resulta pesada.

# The 8 declaration types
curl "https://www.customs-check.com/api/v1/declaration-types?locale=en"

# The fields of one type
curl "https://www.customs-check.com/api/v1/declaration-types/h7?locale=en"

# Same, without the resolved option lists
curl "https://www.customs-check.com/api/v1/declaration-types/h7?options=false"

Procesamiento por lotes

Hasta 25 expedientes por llamada. La respuesta es siempre un éxito en cuanto el lote se acepta, y cada entrada lleva su propio estado: un expediente mal formado nunca hace fallar a los demás.

Si la cuota restante no cubre todas las entradas válidas, se rechaza el lote entero en lugar de procesarlo parcialmente: nunca tendrá que adivinar dónde se detuvo el proceso.

curl https://www.customs-check.com/api/v1/checks/batch \
  -H "Authorization: Bearer $CUSTOM_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "checks": [ { "type": "h7", "header": {}, "items": [] } ] }'

Cuota

Cada clave dispone de 500 comprobaciones por día natural UTC. El estado actual viaja con cada respuesta autenticada, así que nunca necesita una llamada adicional para conocerlo.

Las llamadas rechazadas también cuentan: un cliente que insiste con peticiones inválidas se limita a sí mismo. La cuota se fija por clave — escríbanos si necesita más.

Respuesta

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 437
X-RateLimit-Reset: 1789603200
X-RateLimit-Policy: 500;w=86400

Errores

Los mensajes de error están solo en inglés: son mensajes de protocolo, dirigidos a desarrolladores. Solo se traduce el contenido de negocio.

Cada respuesta lleva un identificador de petición, repetido en el cuerpo. Cítelo al contactarnos: nos lleva directamente a la llamada.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body failed validation.",
    "details": [
      { "path": "items.0.quantity", "message": "expected a string" }
    ],
    "requestId": "2bbb0946-6178-4b54-921c-b28f794c44bd"
  }
}

Estado	code	Significado
400	invalid_json	El cuerpo no es JSON válido.
422	invalid_request	El JSON es válido pero su contenido no. El detalle indica el campo erróneo.
401	missing_credentials	Cabecera Authorization ausente o mal formada.
401	invalid_key	Clave desconocida.
401	key_revoked	Clave revocada.
403	account_suspended	La cuenta propietaria de la clave está suspendida.
415	unsupported_media_type	El tipo de contenido no es JSON.
413	payload_too_large	Cuerpo de la petición demasiado grande.
429	rate_limit_exceeded	Cuota diaria alcanzada. Consulte la cabecera Retry-After.
500	internal_error	Error por nuestra parte. Reinténtelo y comuníquenoslo con el identificador de petición.

Datos y conservación

Los expedientes enviados por la API son datos de sus clientes: conservamos lo mínimo posible y usted dispone de un interruptor para no conservar nada.

Envíe «store» como false y no se escribirá ningún contenido del expediente: solo se conservan la puntuación y los códigos de anomalía.
En caso contrario, el contenido de los expedientes se purga al cabo de 30 días.
Revocar una clave purga de inmediato el contenido de los expedientes que ha enviado.
El tratamiento se realiza en Fráncfort y la base de datos está alojada en la Unión Europea.
La API no sube ningún archivo: usted solo declara qué documentos posee.

200 items · 256 KB · 25 / batch · reference ≤ 64

Lo que esta API no es

La comprobación es una ayuda a la preparación. No constituye una validación por parte de la administración aduanera, no presenta nada y no sustituye las obligaciones reglamentarias aplicables a su operación.

Los códigos aduaneros se comprueban en su formato y su coherencia con la operación, nunca frente a una base arancelaria: un código bien formado sigue siendo un código por verificar.