Ligar e consultar

A captura é ligada por empresa e por tipo. Todas as rotas usam a mesma autenticação do resto da API (X-API-Key). Os campos completos estão na referência da API da captura.

Ligar e desligar

curl -X PUT https://api.conota.dev/v1/captura \
  -H "X-API-Key: $CONOTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cpf_cnpj": "11222333000181", "nfse": true }'

• Envie nfe e/ou nfse, com true para ligar e false para desligar. Um pedido com os dois muda os dois ou nenhum.
• Exige chave de produção — a resposta é 403 com chave de homologação.
• Ligar exige o tipo no plano (403) e certificado A1 ativo e válido (422).
• Desligar para de buscar notas novas. O que já foi capturado continua disponível. Religar continua de onde parou.

Ligar a NF-e é um aceite em nome da empresa

Para ligar a NF-e, envie também "aceite_ciencia_da_operacao": true. Sem ele, a resposta é 422.

Com o aceite, a captura fica autorizada a registrar na SEFAZ, em nome da empresa, a Ciência da Operação (evento 210210) de cada NF-e recebida — é o que libera o XML completo. A Ciência só informa que a empresa tomou conhecimento da nota: não confirma a operação. Confirmar, desconhecer ou recusar continua sendo decisão da empresa.

Acompanhar

GET /v1/captura?cpf_cnpj=11222333000181 devolve, por tipo, se está incluída no plano, ligada e em que situacao:

situacao	O que fazer
sincronizando	Nada: o histórico está sendo baixado, logo depois de ligar.
em_dia	Nada: a captura consulta a fonte periodicamente.
aguardando_limite_de_consumo	Nada: a fonte impôs uma espera (ex.: rejeição 656 da SEFAZ). A captura retoma sozinha.
com_erro	Ler o campo erro — por exemplo, certificado vencido — e corrigir.
desligada / nao_incluida_no_plano	Ligar, ou incluir no plano.

A mesma resposta mostra o webhook configurado para a empresa.

Notas novas não aparecem na hora

Quando não há nada novo, a captura espera cerca de uma hora antes da próxima consulta — é a regra das fontes, e consultar antes gera bloqueio temporário. Uma nota emitida agora contra a sua empresa aparece na próxima consulta, não imediatamente.

Listar as notas recebidas

curl "https://api.conota.dev/v1/captura/notas?cpf_cnpj=11222333000181&tipo=nfse&desde=2026-09-01" \
  -H "X-API-Key: $CONOTA_API_KEY"

• Filtros: tipo (nfe | nfse), desde e ate (data de emissão, AAAA-MM-DD, no fuso de Brasília), situacao, pagina e limite (até 200).
• Cada nota traz papel (tomador, destinatario, intermediario), o emissor, o valor e a situação.
• situacao vem como a fonte informou. Um código que ainda não interpretamos aparece cru — por exemplo cstat-107 — e nunca como autorizada. Não trate código desconhecido como nota válida.

Baixar o XML

curl "https://api.conota.dev/v1/captura/notas/xml?chave=<chave>&cpf_cnpj=11222333000181" \
  -H "X-API-Key: $CONOTA_API_KEY" -o nota.xml

• A chave de acesso tem 44 dígitos na NF-e e 50 na NFS-e.
• O header X-Conota-Documento diz se veio a nota integral ou só o resumo.
• Informe cpf_cnpj: se a mesma nota aparecer em duas empresas da conta (uma nota entre elas, por exemplo), sem ele a resposta é 409.
• O XML só sai pela rota autenticada — não há link público.