Perguntas frequentes

O Swagger foi removido?

Não. Ele está em api.conota.dev/swagger e continua sendo o console de testes. A referência da API usa ReDoc, em api.conota.dev/docs.

O que devo usar para integrar: este portal ou o ReDoc?

Os dois. Aqui você entende o fluxo; no ReDoc confere endpoints, parâmetros e schemas.

Preciso usar MCP para integrar?

Não. O MCP é uma forma adicional, voltada a assistentes e agentes de IA. Integrações tradicionais continuam usando a API REST.

MCP substitui a API REST?

Não. O MCP expõe capacidades controladas para agentes; a REST continua sendo a interface determinística para integrações transacionais. Ver quando usar cada um.

Uma IA pode emitir uma nota sozinha pelo MCP?

Não. A emissão exige preparação e confirmação humana explícita. O token de confirmação é de uso único e há teto de valor por conta. Ver Segurança no MCP.

Recebi timeout. Posso reenviar?

Não automaticamente. Primeiro localize a operação:

GET /v1/jobs/localizar?ref=sua_referencia

Reenvio cego pode causar duplicidade. Se você enviou referencia_externa, o reenvio da mesma referência é seguro: devolve o job existente.

Uma rejeição significa que a API está fora do ar?

Não — significa o contrário. O documento chegou ao autorizador e foi recusado por uma regra fiscal ou cadastral. Ver Erros e rejeições.

O status voltou completed. A nota foi autorizada?

Não necessariamente. completed é o processamento; o desfecho fiscal está em nota.status. Ver Status das emissões.

Minha nota foi rejeitada. Perdi o número?

Não. Nota rejeitada não consome numeração. Corrija e emita de novo — com uma referencia_externa nova.

Posso usar a API Key no frontend?

Não. Ela permite emitir documentos com efeito fiscal. Use apenas em ambiente que você controla.

Quanto tempo os arquivos ficam disponíveis?

Depende do plano. Armazene os XMLs no seu ambiente — a obrigação de guarda é sua, e a API não é arquivo definitivo.

O CNPJ alfanumérico já é aceito?

Sim, em todos os pontos da API que tratam documento.

Sobre máscara: em query string e no corpo, envie como quiser. Em parâmetro de caminho (/v1/cnpj/{cnpj}, /v1/empresas/{cpf_cnpj}), envie sem a barra — ela é separador de caminho e a rota não seria encontrada.