API e agentes de IA
Autenticação e endereço base
Gere sua chave no app, no menu “Agentes de IA”. Envie a chave no cabeçalho x-api-key ou em Authorization: Bearer <chave>. O endereço base da API é https://api.acainfe.com.
Principais rotas
POST /v1/sales — registrar uma venda e emitir as notas.
GET /v1/invoices e GET /v1/invoices/{id} — consultar notas.
POST /v1/invoices/{id}/cancel — cancelar uma nota.
GET /v1/products e POST /v1/products — produtos e tributação.
GET /v1/public/pricing e GET /v1/public/coverage — preço e cidades atendidas; públicas, sem chave.
Exemplo de emissão
O exemplo registra uma venda de R$ 97,00. Substitua <chave> pela sua chave e productExternalId pelo identificador do produto. A emissão é assíncrona: acompanhe a nota por GET /v1/invoices/{id}.
curl -X POST https://api.acainfe.com/v1/sales -H "x-api-key: <chave>" -H "Content-Type: application/json" -d '{"externalId":"pedido-123","customer":{"name":"Ana Souza","taxId":"52998224725","email":"ana@exemplo.com"},"items":[{"productExternalId":"prod_abc","totalCents":9700}]}'Valores inteiros
Envie sempre valores inteiros: dinheiro em centavos (R$ 82,20 = 8220) e percentuais em pontos-base (2,01% = 201).
Versionamento e descontinuação
A versão da API está no caminho (/v1). Dentro de uma versão, só entram mudanças compatíveis: novos campos, novas rotas e novos valores opcionais. Uma mudança incompatível só sai numa nova versão (/v2). Uma rota ou versão descontinuada continua funcionando por pelo menos 90 dias, responde com os cabeçalhos Deprecation (RFC 9745) e Sunset (RFC 8594) e é anunciada nesta página e no llms.txt.
Erros
Toda resposta de erro tem o formato { "error": "<CÓDIGO>", "message": "...", "details": {...} }: error identifica o código, message explica o problema e details traz os detalhes.
VALIDATION (422): os dados enviados não passaram na validação.
NOT_FOUND (404): o recurso não foi encontrado.
CONFLICT e INVALID_STATE (409): há um conflito ou o estado atual não permite a ação.
UNAUTHORIZED (401): a autenticação está ausente ou não foi aceita.
CERTIFICATE_INVALID e CERTIFICATE_MISSING (422): o certificado é inválido ou está ausente.
UNAVAILABLE (503): o serviço está temporariamente indisponível; pode tentar de novo.
INTERNAL (500): ocorreu um erro interno.
Agentes de IA e MCP
O servidor MCP é https://api.acainfe.com/mcp, com transporte HTTP streamable e a mesma chave, no cabeçalho Authorization: Bearer <chave>. O guia para agentes está em /llms.txt.
Referência completa
Consulte a referência Swagger para os detalhes da API pública, seus parâmetros e respostas.