Programadores

API de verificação aduaneira

A mesma verificação deste site, invocada a partir do seu software. Envia um processo em JSON e recebe uma pontuação sobre 100, os pontos bloqueantes, os alertas e as ações recomendadas — com códigos de anomalia estáveis e mensagens traduzidas nas 24 línguas oficiais da União Europeia.

Criar uma chave Especificação OpenAPI

Esta é uma API servidor-a-servidor. Uma chave de API é um segredo. As chamadas a partir de um navegador não são suportadas e não é enviado qualquer cabeçalho CORS nas rotas autenticadas: uma chave que chega a um navegador é uma chave divulgada.

Panorâmica

A API expõe o motor de verificação do validador: treze regras transversais, quatro regras de completude documental e os validadores próprios de cada sistema declarativo. Não transmite nada nem consulta qualquer base pautal — verifica a coerência interna e o formato do seu processo antes de preparar a declaração.

Todas as rotas têm o prefixo da sua versão. As rotas de descoberta e a especificação são públicas: um integrador, ou um agente, pode ler o esquema antes sequer de ter uma chave.

Rota	Função	Autenticação
POST/v1/checks	Verifica um processo e devolve o relatório completo	Chave necessária
POST/v1/checks/batch	Verifica até 25 processos numa chamada	Chave necessária
GET/v1/me	Devolve a chave atual e a sua quota, sem a consumir	Chave necessária
GET/v1/declaration-types	Lista os tipos de declaração reconhecidos	Pública
GET/v1/declaration-types/{type}	Descreve os campos esperados para um tipo	Pública
GET/v1/openapi.json	A especificação OpenAPI 3.1 desta API	Pública

Autenticação

A API autentica-se com um token portador. O token é mostrado uma única vez, na criação: apenas a sua impressão é guardada, pelo que uma chave perdida substitui-se, nunca se recupera.

Pode manter três chaves ativas em simultâneo, o que permite rodar uma chave sem interromper a sua integração: crie a nova, coloque-a em produção e revogue a antiga.

1Crie uma chave a partir da sua conta, em «Chaves de API».
2Envie-a no cabeçalho Authorization de cada pedido.
3Revogue-a se houver fuga: o corte é imediato e o conteúdo dos processos submetidos com essa chave é purgado de imediato.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Primeira verificação

Um processo é composto por um tipo, um cabeçalho e linhas de mercadorias. Todos os valores são cadeias de texto: o motor encarrega-se de as interpretar. Os nomes dos campos descobrem-se em tempo de execução, tipo a tipo.

A resposta chega de imediato; depois não há nada a consultar.

Pedido

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" }
  }'

Ler a resposta

Cada anomalia traz ao mesmo tempo uma identidade de máquina e uma frase legível. Construa a sua lógica sobre a identidade de máquina: não muda sem uma mudança de versão.

severity · code · path · rule: Contrato estávelEstáveis. Podem surgir novos códigos; os existentes não são renomeados sem uma mudança de versão.
field · message · text: Apenas visualizaçãoTraduzidos para exibição. Podem ser reformulados a qualquer momento: nunca os compare no seu código.
engine.version: Muda assim que uma evolução das regras altera a pontuação de um processo inalterado. Arquive-a com os seus relatórios.

O campo «path» reflete a forma do seu pedido, pelo que pode ligar uma anomalia diretamente ao campo correspondente na sua própria interface.

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

Resposta

{
  "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 }
}

Descobrir os campos

Os tipos de declaração e os seus campos são públicos, não é necessária chave. É a rota a usar para construir um formulário, alimentar um mapeamento a partir do seu ERP, ou dar a um agente o esquema que tem de preencher.

Os nomes devolvidos aqui são exatamente as chaves a usar no cabeçalho e em cada linha de mercadoria. As listas de opções chegam resolvidas e traduzidas; acrescente o parâmetro para as omitir se a resposta lhe parecer 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"

Processamento em lote

Até 25 processos por chamada. A resposta é sempre um sucesso assim que o lote é aceite, e cada entrada traz o seu próprio estado: um processo mal formado nunca faz falhar os restantes.

Se a quota restante não cobrir todas as entradas válidas, o lote inteiro é recusado em vez de processado parcialmente — nunca terá de adivinhar onde o processamento parou.

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

Quota

Cada chave dispõe de 500 verificações por dia de calendário UTC. O estado atual viaja com cada resposta autenticada, pelo que nunca precisa de uma chamada adicional para o conhecer.

As chamadas recusadas também contam: um cliente que insiste com pedidos inválidos limita-se a si próprio. A quota é definida por chave — escreva-nos se precisar de mais.

Resposta

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

Erros

As mensagens de erro estão apenas em inglês: são mensagens de protocolo, destinadas a programadores. Só o conteúdo de negócio é traduzido.

Cada resposta traz um identificador de pedido, repetido no corpo. Cite-o quando nos contactar — leva-nos diretamente à chamada.

{
  "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	O corpo não é JSON válido.
422	invalid_request	O JSON é válido mas o seu conteúdo não. O detalhe indica o campo em falta.
401	missing_credentials	Cabeçalho Authorization ausente ou mal formado.
401	invalid_key	Chave desconhecida.
401	key_revoked	Chave revogada.
403	account_suspended	A conta proprietária da chave está suspensa.
415	unsupported_media_type	O tipo de conteúdo não é JSON.
413	payload_too_large	Corpo do pedido demasiado grande.
429	rate_limit_exceeded	Quota diária atingida. Consulte o cabeçalho Retry-After.
500	internal_error	Erro do nosso lado. Tente de novo e comunique-nos com o identificador de pedido.

Dados e conservação

Os processos enviados pela API são dados dos seus clientes: guardamos o mínimo possível e tem um interruptor para não guardar nada.

Envie «store» como false e nenhum conteúdo do processo será escrito: apenas a pontuação e os códigos de anomalia são conservados.
Caso contrário, o conteúdo dos processos é purgado ao fim de 30 dias.
Revogar uma chave purga de imediato o conteúdo dos processos que submeteu.
O tratamento decorre em Frankfurt e a base de dados está alojada na União Europeia.
Nenhum ficheiro é carregado pela API: apenas declara que documentos possui.

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

O que esta API não é

A verificação é uma ajuda à preparação. Não constitui uma validação pela administração aduaneira, não submete nada e não substitui as obrigações regulamentares aplicáveis à sua operação.

Os códigos aduaneiros são verificados quanto ao formato e à coerência com a operação, nunca confrontados com uma base pautal: um código bem formado continua a ser um código a verificar.