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 control del validador: catorce reglas transversales, cinco reglas TARIC, cuatro reglas de documentación completa y los validadores propios de cada sistema declarativo. No transmite nada: comprueba el formato y la coherencia de su expediente, la existencia de los códigos en la nomenclatura y, para una importación en la UE, las medidas TARIC aplicables al origen (antidumping, controles, preferencias, tipo de derecho), 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.

01Cree una clave desde su cuenta, en «Claves de API».
02Envíela en la cabecera Authorization de cada petición.
03Revó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": 1 },
  "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": [
    {
      "severity": "info",
      "code": "taricControlsPossible",
      "path": "items.0.hsCode",
      "rule": "RULE-017",
      "params": { "measures": "Import control - CITES ; Import control on seal products" },
      "field": "Product 1 — HS / commodity code (if known)",
      "message": "Possible import controls depending on the goods (Import control - CITES ; Import control on seal products): check whether they apply.",
      "text": "Product 1 — HS / commodity code (if known): Possible import controls depending on the goods (Import control - CITES ; Import control on seal products): check whether they apply."
    }
  ],
  "engine": { "version": "1.6.0", "rules": 25, "taric": "2026-10-01" }
}

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": [] } ] }'

Agentes y herramientas

Además de las rutas REST, el mismo motor y los mismos datos son accesibles desde un asistente de IA, mediante un servidor Model Context Protocol (MCP), y desde un cliente de API, mediante una colección de Postman ya preparada. Ambos usan la clave de API y la cuota diaria descritas más arriba.

Servidor MCP

El servidor MCP permite a un asistente buscar códigos aduaneros, leer el derecho de importación de la UE de un código, comprobar un número EORI, de IVA o AEO en los registros oficiales y comprobar un borrador de declaración, sin que escriba una sola línea de código intermedio. Responde en POST /api/mcp, con respuestas JSON.

No guarda estado y habla las dos generaciones del protocolo: la revisión 2026-07-28, en la que cada solicitud lleva su versión, y las revisiones anteriores, que se abren con una llamada initialize. La conexión, el descubrimiento y el listado de herramientas no cuestan nada; cada llamada a una herramienta consume una unidad de la cuota diaria de la clave.

La autenticación es el mismo token bearer que la API REST. Un cliente que solo admite el inicio de sesión OAuth, como los conectores web de claude.ai, todavía no puede conectarse: use un cliente que permita definir una cabecera.

POST https://www.customs-check.com/api/mcp

claude mcp add --transport http customs-check https://www.customs-check.com/api/mcp \
  --header "Authorization: Bearer $CUSTOM_CHECK_KEY"

check_declaration	Comprueba un borrador de declaración: puntuación sobre 100, nivel y cada incidencia con el campo y la acción. No conserva el contenido del archivo salvo que se pida.
list_declaration_types	Los sistemas de declaración admitidos, con autoridad, región y documentos esperados.
describe_declaration_type	Los campos de cabecera y de partida de un tipo, para construir la entrada de check_declaration.
search_hs_codes	Códigos candidatos de la Nomenclatura Combinada a partir de la descripción de un producto, en cualquiera de los 24 idiomas de la UE.
describe_hs_code	Si un código de 4 a 10 dígitos existe en la nomenclatura vigente, con su ruta oficial y su texto.
lookup_import_duty	Derecho de importación de la UE de un código según los datos TARIC de la Comisión: derecho de terceros países, preferencias para un origen, contingentes, antidumping y controles.
search_chemical	Una sustancia química por número CAS, número CUS o nombre en el inventario ECICS de la Comisión: el código de la nomenclatura combinada dado para cada entrada, por verificar.
get_quota_balance	Saldo restante de un contingente arancelario de la UE en la base QUOTA de la Comisión, a partir de su número de orden o de un código y un origen: saldo, estado (abierto, crítico, bloqueado, agotado), período y hora de la lectura.
validate_eori	Formato de un número EORI y su estado en el registro oficial (Comisión Europea, HMRC).
validate_vat	Formato de un número de IVA de la UE y su validez en el VIES, con el nombre registrado cuando se publica.
check_rex	Formato de un número REX de exportador registrado y su situación en la base REX de la Comisión (válido, revocado o desconocido), con sus fechas.
screen_sanctions	Una empresa, persona o buque frente a las listas de sanciones de la UE, la ONU, el Reino Unido y Estados Unidos, actualizadas cada día: cada coincidencia con su puntuación, fuerte o parcial.
search_aeo	Búsqueda en la base de datos de la Comisión de Operadores Económicos Autorizados por nombre de empresa.

Los códigos aduaneros son propuestas extraídas del texto de la nomenclatura. Solo el declarante, o una información arancelaria vinculante de la aduana, puede confirmar una clasificación.
Los derechos son indicativos: no se evalúan las condiciones, las exclusiones por país ni los contingentes agotados. Cada respuesta lleva la fecha de referencia del extracto TARIC, actualizado cada mes.
Un registro que no responde se notifica como no disponible, nunca como un número no válido. Nunca se envía nada a la aduana.

Colección de Postman

La colección se genera a partir de la especificación OpenAPI, por lo que siempre coincide con ella: una solicitud por ruta, agrupadas por etiqueta, con un esqueleto de cuerpo para cada POST. Impórtela en Postman, rellene la variable apiKey (guardada como secreta) y las solicitudes estarán listas para enviarse.

Descargar la colección

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, su existencia en la nomenclatura y, en las importaciones en la UE, frente a las medidas TARIC de su origen, nunca en la clasificación de la mercancía: un código existente sigue siendo un código por verificar. Las medidas TARIC son indicativas (extracción mensual de la Comisión Europea): no se evalúan las exclusiones de países, los contingentes agotados ni los derechos condicionales.