# Conota

> Plataforma de infraestrutura fiscal para desenvolvedores. Emissão e gestão de NF-e (modelo 55),
> NFC-e (modelo 65) e NFS-e por uma API REST única, mais uma integração nativa para assistentes de
> IA via Model Context Protocol (MCP). Requisições e respostas em JSON; emissão assíncrona com
> acompanhamento por job_id ou webhook.

## Endereços

- API REST: https://api.conota.dev
- Referência da API (ReDoc): https://api.conota.dev/docs
- Especificação OpenAPI: https://api.conota.dev/docs/json
- Console de testes (Swagger UI): https://api.conota.dev/swagger
- Servidor MCP: https://mcp.conota.dev/mcp
- Catálogo de ferramentas MCP: https://mcp.conota.dev
- Documentação: https://docs.conota.dev

Os domínios api.conota.com.br, api.pluganota.com e api.qualyfiscal.com.br sao aliases do mesmo
serviço.

## Autenticação

Header `X-API-Key: <chave>` ou `Authorization: Bearer <chave>`. A chave identifica uma conta e
permite emitir documentos com efeito fiscal — nunca use em frontend.

## Conceitos que mais causam erro de integração

- A emissão responde HTTP 202 com um `job_id`. **202 não é autorização.**
- O job tem status próprio (`pending`, `processing`, `completed`, `failed`, `cancelled`) e a nota
  tem outro (`autorizada`, `rejeitada`, `denegada`, `cancelada`, `inutilizada`).
  **`completed` não significa autorizada** — verifique `nota.status`.
- Rejeição fiscal não é erro técnico: o documento chegou ao autorizador e foi recusado por uma
  regra. Repetir igual dá o mesmo resultado.
- Nota rejeitada **não consome numeração**.
- `referencia_externa` torna a emissão idempotente por conta: reenviar a mesma referência devolve o
  job existente (HTTP 200, `idempotente: true`) em vez de emitir de novo.
- Após timeout, **não reenvie**: localize com `GET /v1/jobs/localizar?ref=...`.
- Campo com nome errado é ignorado em silêncio. Use `POST /v1/nfe/verificar-campos` (não consome
  cota) antes de emitir.
- CNPJ alfanumérico (letras nas 12 primeiras posições) é aceito, com ou sem máscara.

## Começando

- Introdução: https://docs.conota.dev/docs/comecando/introducao
- Onboarding da integração: https://docs.conota.dev/docs/comecando/onboarding
- Ambientes: https://docs.conota.dev/docs/comecando/ambientes
- Autenticação: https://docs.conota.dev/docs/comecando/autenticacao
- Primeira requisição: https://docs.conota.dev/docs/comecando/primeira-requisicao
- Primeira emissão: https://docs.conota.dev/docs/comecando/primeira-emissao

## Conceitos da API

- Empresas e emitentes: https://docs.conota.dev/docs/conceitos/empresas
- Certificado digital: https://docs.conota.dev/docs/conceitos/certificado
- Processamento assíncrono: https://docs.conota.dev/docs/conceitos/assincrono
- Referência externa e idempotência: https://docs.conota.dev/docs/conceitos/referencia-externa
- Status das emissões: https://docs.conota.dev/docs/conceitos/status
- Erros e rejeições: https://docs.conota.dev/docs/conceitos/erros-rejeicoes
- Limites e cotas: https://docs.conota.dev/docs/conceitos/limites
- Paginação: https://docs.conota.dev/docs/conceitos/paginacao
- Webhooks: https://docs.conota.dev/docs/conceitos/webhooks

## Documentos fiscais

- Visão geral: https://docs.conota.dev/docs/documentos/index
- NF-e: https://docs.conota.dev/docs/documentos/nfe/visao-geral
- Emitir NF-e: https://docs.conota.dev/docs/documentos/nfe/emitir
- Consultar emissão: https://docs.conota.dev/docs/documentos/nfe/consultar
- Arquivos XML e DANFE: https://docs.conota.dev/docs/documentos/nfe/arquivos
- Cancelamento: https://docs.conota.dev/docs/documentos/nfe/cancelamento
- NFC-e: https://docs.conota.dev/docs/documentos/nfce/visao-geral
- NFS-e: https://docs.conota.dev/docs/documentos/nfse/visao-geral
- Municípios e provedores: https://docs.conota.dev/docs/documentos/nfse/provedores

## MCP (integração para agentes de IA)

- O Conota MCP: https://docs.conota.dev/docs/mcp/introducao
- Quando usar MCP ou REST: https://docs.conota.dev/docs/mcp/mcp-vs-rest
- Conectar ao MCP: https://docs.conota.dev/docs/mcp/conectar
- Segurança e confirmação humana: https://docs.conota.dev/docs/mcp/seguranca
- Exemplos de uso: https://docs.conota.dev/docs/mcp/exemplos

Emissão pelo MCP usa dois passos (preparar → confirmar) e exige confirmação humana explícita. O
token de confirmação é de uso único e há teto de valor por conta.

## Operação

- Boas práticas: https://docs.conota.dev/docs/operacao/boas-praticas
- Segurança: https://docs.conota.dev/docs/operacao/seguranca
- Observabilidade e logs: https://docs.conota.dev/docs/operacao/logs
- Suporte: https://docs.conota.dev/docs/operacao/suporte
- FAQ: https://docs.conota.dev/docs/operacao/faq

## Atualizações

- Changelog: https://docs.conota.dev/docs/atualizacoes/changelog
- Mudanças incompatíveis: https://docs.conota.dev/docs/atualizacoes/breaking-changes
- Atualizações fiscais e regulatórias: https://docs.conota.dev/docs/atualizacoes/fiscal