API de verificação aduaneira

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.

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

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.

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

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.

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.

O servidor MCP permite a um assistente pesquisar códigos aduaneiros, ler o direito de importação da UE de um código, verificar um número EORI, de IVA ou AEO nos registos oficiais e verificar um rascunho de declaração, sem que escreva uma única linha de código de ligação. Responde em POST /api/mcp, com respostas JSON.

É sem estado e fala as duas gerações do protocolo: a revisão 2026-07-28, em que cada pedido transporta a sua versão, e as revisões anteriores, que se abrem com uma chamada initialize. A ligação, a descoberta e a listagem das ferramentas não custam nada; cada chamada de uma ferramenta consome uma unidade da quota diária da chave.

A autenticação é o mesmo token bearer da API REST. Um cliente que só suporta o início de sessão OAuth, como os conectores web do claude.ai, ainda não consegue ligar-se: use um cliente que permita definir um cabeçalho.

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

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.

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.