a API do Dualisia
em uma página.

a primeira chamada não precisa de chave.

A apuração pública aceita um XML de NF-e direto, sem cadastro. É o caminho mais curto para ver o formato da resposta.

API key por escritório, com scope.

Os endpoints sob /api/v1 exigem a chave da organização. O owner do escritório gera em Configurações → API keys, e ela aparece uma única vez. Cada chave tem scopes (read:clients, read:documents) e só enxerga dados da própria organização.

quatro chamadas, todas implementadas.

Esta lista é a superfície pública inteira. Nada de endpoint "em breve": o que está aqui responde hoje, e o que responde hoje está aqui.

rate limit explícito no header.

Toda resposta — sucesso ou erro — traz os campos estruturados do IETF, para o agente se auto-limitar antes de bater no teto:

q é a cota, w a janela em segundos, r o que resta e t os segundos até a janela reabrir. Os headers históricos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset continuam saindo. O 429 traz também Retry-After e o campo retryAfter no corpo.

o contrato não muda embaixo de você.

A versão maior vive no caminho: /api/v1. Mudança que quebra contrato não é publicada na mesma versão — ela ganha um caminho novo, /api/v2, e o anterior continua respondendo. Os endpoints públicos de cálculo (/api/calculadora e /api/simulador) seguem o mesmo compromisso.

O que conta como mudança que quebra: remover endpoint, campo ou valor de enum; tornar obrigatório um parâmetro que era opcional; mudar o tipo de um campo; mudar o significado de um code de erro. O que não conta, e pode entrar sem versão nova: campo novo na resposta, endpoint novo, valor novo em enum de saída, e correção de cálculo por mudança na legislação — esta última sempre acompanhada da base legal na própria resposta.

Quando uma versão entrar em depreciação, o aviso vem no próprio tráfego, antes de qualquer desligamento:

Deprecation marca quando a versão passou a ser desaconselhada; Sunset, a data em que ela deixa de responder. O intervalo entre as duas é de no mínimo 90 dias. Hoje nenhuma versão está depreciada, e por isso esses dois headers não aparecem — o Link com rel="deprecation" sai em toda resposta da API e aponta para esta seção.

um formato só, com código estável e dica.

Todo erro da API responde JSON com code — estável, para ramificar em código — e hint, dizendo o que fazer para corrigir. error repete message por compatibilidade com clientes antigos.

Caminho inexistente sob /api responde 404 em JSON com code: not_found — nunca HTML.

tudo que importa está em formato de máquina.

Qualquer página pública também responde em Markdown: mande Accept: text/markdown na mesma URL. As respostas carregam Vary: Accept, então a variante certa nunca sai do cache trocada.

CLI no npm, SDK ainda não.

O pacote dualisia-cli (licença MIT) está publicado no npm e envolve os quatro endpoints acima. Rode sem instalar com npx dualisia-cli --help, ou instale global com npm i -g dualisia-cli. O código-fonte é aberto em github.com/munhoz-iago/dualisia-cli.

Não há SDK oficial em nenhuma linguagem — a API é REST puro e qualquer cliente HTTP serve. Diga em /contato de qual linguagem você precisa primeiro.