consultar_cnpj

Consulta os dados cadastrais de um CNPJ na Receita Federal (razão social, endereço, situação, CNAE). Use para validar dados de emitente ou destinatário antes de emitir.

consultar_cep

Consulta o endereço de um CEP (logradouro, bairro, município, UF).

buscar_ncm_por_descricao

Procura códigos NCM a partir da DESCRIÇÃO do produto. É a ferramenta certa quando você sabe o que o item é ("parafuso de aço", "café solúvel") mas não sabe o código de oito dígitos. Devolve os candidatos com a descrição oficial e a vigência, para escolher com segurança. Use antes de montar o payload de emissão, não depois de levar rejeição. A busca casa o termo em QUALQUER POSIÇÃO da descrição oficial, mas ela é LITERAL: não entende sinônimo nem plural. Mande UMA palavra, no singular e como o texto oficial escreveria ("parafuso", não "parafuso de aço inox"). Se vier vazio, tente outra palavra do mesmo item antes de desistir — lista vazia significa que o termo não aparece na tabela, não que o produto não tem NCM. Só vêm códigos de 8 dígitos, que são os únicos válidos numa nota.

consultar_ncm

Devolve a descrição oficial, a vigência e o ato normativo de um NCM de 8 dígitos. Use quando já tem o código e quer confirmar o que ele significa — ou se ainda vale.

validar_ncm

Responde apenas se o código existe na tabela vigente. Útil para conferir cadastro antigo antes de emitir: NCM sai de vigência por ato normativo, e o código que funcionava ano passado pode não existir mais.

listar_empresas

Lista as empresas (emitentes) cadastradas na conta, com CNPJ, razão social e município.

Sem parâmetros.

status_certificados

Relatório de validade dos certificados A1 de todas as empresas da conta. Use para saber quais estão vencidos ou perto de vencer — certificado vencido faz TODAS as emissões serem rejeitadas.

Sem parâmetros.

numeracao_das_notas

Numero da ULTIMA NOTA AUTORIZADA de cada empresa, por tipo de documento, serie e ambiente. Responde "qual foi a ultima nota que emiti?" e serve de base para montar a proxima com o numero certo. Homologacao e producao sao sequencias INDEPENDENTES e vem separadas — nao misture as duas ao sugerir um numero. Nota rejeitada NAO avanca a sequencia: so entram as autorizadas. ATENCAO: e CONSULTA, nao reserva. Entre voce ler e a nota sair, outra emissao pode ter usado o numero seguinte. Nunca diga a pessoa que o numero esta garantido; se a emissao for rejeitada por duplicidade, consulte de novo em vez de chutar o proximo.

localizar_nota

Encontra uma emissão pela referência externa do cliente OU por atributos de negócio (emitente, destinatário, valor, período). Use quando não se tem o job_id. Zero resultados é forte indício de que a emissão nunca aconteceu.

consultar_emissao

Retorna a situação de uma emissão pelo job_id: status, nota (número, chave de acesso, motivo), arquivos e erro.

itens_da_nota

Retorna os itens de uma emissão pelo job_id, com código, descrição, NCM, CFOP, valores e os grupos tributários de cada item (ICMS, PIS, COFINS e IBS/CBS). Use para descobrir QUAL produto causou uma rejeição: quando o fisco aponta um item, a resposta traz "item_rejeitado" já identificado. Funciona para qualquer status — inclusive rejeitadas e falhas, porque a fonte é o payload enviado, não o XML autorizado. Fluxo típico: notas_rejeitadas → pegue um job_id → itens_da_nota.

consultar_emissoes_em_lote

Consulta o status de até 200 job_ids numa só chamada. Ids desconhecidos voltam como "nao_encontrado".

verificar_campos

Recebe o MESMO objeto "nota" que seria enviado para emitir e devolve os campos que o emissor NAO reconhece — sem emitir, sem gastar numeracao e sem debitar cota. Use quando o cliente perguntar por que uma nota saiu errada ou for rejeitada, e antes de uma primeira integracao. Campo com nome errado nao gera erro na emissao: ele e ignorado e o campo correto sai zerado — por exemplo "vlrProd" no lugar de "vProd" gera uma nota com o produto valendo R$ 0,00. A resposta traz o caminho exato e uma sugestao de correcao. ATENCAO ao interpretar: lista vazia significa apenas que nao ha campo desconhecido, NAO que a nota sera aceita — valor malformado e regra fiscal nao sao verificados aqui. Passe cpf_cnpj do emitente para ligar a 2a camada (schema oficial), que pega valor malformado. Disponivel para nfe e nfce; nfse usa outro layout e devolve erro.

preparar_emissao

PASSO 1 DE 2. NAO emite nada. Confere o payload e devolve um token de uso unico, valido por 15 minutos. A referencia COMPLETA dos campos de `nota` (nome, tipo, tamanho, valores aceitos e os apelidos de cada campo) esta em https://docs.conota.dev/docs/documentos/nfe/referencia-de-campos — consulte-a antes de montar uma nota do zero, em vez de adivinhar nome de campo. Devolve tambem um resumo em uma frase. Se a conferencia falhar, NAO ha token — o payload torto nunca vira emissao. DEPOIS DE CHAMAR ESTA TOOL: mostre o campo resumo.texto para a pessoa, com as suas proprias palavras se quiser, e PERGUNTE se pode emitir. Nao chame confirmar_emissao por conta propria: emitir e IRREVERSIVEL e a nota tem efeito fiscal e juridico. Espere a pessoa responder que sim. Existe um TETO DE VALOR nesta rota: acima dele a preparacao e recusada e a resposta diz qual e o limite. Nao tente contornar dividindo a nota em varias — avise a pessoa. Se a nota que voce quer emitir se parece com uma que ja existe, prefira emitir_como ou reemitir_corrigindo: aproveitam um payload que a SEFAZ ja aceitou, em vez de um montado do zero.

confirmar_emissao

PASSO 2 DE 2. EMITE a nota de verdade — acao IRREVERSIVEL, com efeito fiscal. So chame depois que uma PESSOA viu o resumo do preparar_emissao e respondeu que pode emitir. Nunca chame na mesma resposta em que voce chamou preparar_emissao. Se a pessoa nao respondeu, nao confirmou, ou voce esta em duvida: NAO chame — pergunte. Repetir a chamada com o mesmo token devolve o MESMO job_id, nunca uma segunda nota, entao nao ha motivo para "tentar de novo por seguranca".

reemitir_corrigindo

PASSO 1 DE 2, para uma nota que o fisco REJEITOU. NAO emite: devolve token, resumo e a lista de alteracoes, e so confirmar_emissao emite. Parte do payload original — que a realidade ja testou — e aplica so o que voce mandar mudar, em vez de remontar a nota inteira e arriscar mexer no que estava certo. Use itens_da_nota ou consultar_emissao antes, para saber QUAL campo derrubou a nota. O numero da nota e MANTIDO: numero de nota rejeitada nao foi consumido. Se a nota de origem foi AUTORIZADA a chamada e recusada — corrigir criaria uma segunda nota para o mesmo fato. Nesse caso use emitir_como (nota nova) ou cancele a autorizada. DEPOIS DE CHAMAR: mostre resumo.texto E o campo alteracoes para a pessoa e pergunte se pode emitir.

emitir_como

PASSO 1 DE 2, usando uma nota existente como MODELO para uma nota NOVA. NAO emite: devolve token, resumo e a lista de alteracoes, e so confirmar_emissao emite. Serve para "faca outra igual a de ontem, mudando o destinatario" — aproveita um payload que a SEFAZ ja aceitou (impostos, CFOP, CST) em vez de um montado do zero. O NUMERO da nota precisa mudar. Se voce nao informar um em ajustes, sugerimos o proximo com base nas notas emitidas por aqui — e a resposta traz um aviso, porque nao enxergamos o que o cliente emite por outro sistema. Confira o numero com a pessoa. Vale o mesmo TETO DE VALOR do preparar_emissao. DEPOIS DE CHAMAR: mostre resumo.texto E o campo alteracoes para a pessoa e pergunte se pode emitir.

zips_mensais_disponiveis

Lista os pacotes ZIP mensais de XMLs da conta — um por tipo de documento (NF-e/NFS-e/NFC-e) e por mês, gerados automaticamente no dia 1º com os XMLs do mês anterior e mantidos por 15 meses. Cada item traz competência, tipo, quantidade de arquivos, tamanho e "completo": quando false, o pacote foi gerado antes do fechamento do mês e ainda será refeito. Use antes de baixar_zip_mensal para saber o que existe.

Sem parâmetros.

baixar_zip_mensal

Devolve um LINK de download (válido por 1 hora) do pacote ZIP de XMLs de um mês e tipo de documento. A ferramenta entrega o endereço, não o arquivo: repasse o link para a pessoa baixar. Qualquer um com o link consegue baixar enquanto ele valer — não publique em lugar aberto. Se não existir pacote para o período, use zips_mensais_disponiveis para ver o que há.

baixar_arquivo_da_nota

Devolve um LINK de download (válido por 1 hora) de um arquivo de uma emissão específica: xml (o documento autorizado), pdf (DANFE/DANFSE), xml_cancelamento ou log. A ferramenta entrega o endereço, não o arquivo. Qualquer um com o link baixa enquanto ele valer. Use consultar_emissao ou localizar_nota para obter o job_id.

listar_notas

Lista as notas da conta, da mais recente para a mais antiga, com filtros por tipo, situação e empresa.

resumo_emissoes

Relatório consolidado do período: quantas notas foram EMITIDAS com sucesso e o valor somado, separado por tipo (NF-e/NFS-e/NFC-e), mais as que ficaram COM ERRO e os principais motivos. Use para perguntas do tipo "quanto foi emitido no dia X". Para um único dia, informe a mesma data em de e ate. Sem datas, usa do 1º dia do mês até hoje. ATENCAO: a resposta desta ferramenta e um resumo MONTADO por nos a partir de GET /v1/notas/rejeicoes — nao e o mesmo JSON da rota REST. Nao use os nomes de campo daqui para escrever integracao REST.

emissoes_com_erro

Lista (ou resume) os jobs que FALHARAM num período — emissões que nem viraram nota. Janela máxima de 90 dias; sem datas, últimos 7 dias. Use formato=resumo para agrupar por motivo.

notas_rejeitadas

Lista (ou resume) as notas que foram REJEITADAS pelo fisco — diferente de emissoes_com_erro, aqui o documento chegou a ser processado. Janela máxima de 90 dias; sem datas, últimos 7 dias.

listar_catalogos

Lista os catálogos de uma empresa emissora, com a contagem de produtos e serviços de cada um. É o primeiro passo de qualquer trabalho no catálogo: o `catalogo_id` daqui é o que as demais ferramentas pedem. Cada empresa tem um catálogo. Se a lista vier vazia, use `criar_catalogo`.

criar_catalogo

Cria o catálogo de uma empresa emissora e devolve o `catalogo_id`. Uma empresa tem um catálogo: se já existir, a resposta é um erro de conflito, e o caminho é usar o que existe. Confira antes com `listar_catalogos`.

listar_itens_do_catalogo

Lista os itens de um catálogo. Informe `codigo` para trazer um item exato — a resposta é a mesma lista, com `total` 1 ou 0, e não um erro quando não existe. Use antes de cadastrar, para não duplicar, e para **copiar a classificação de um item parecido que a pessoa já cadastrou** — copiar do que ela mesma declarou é diferente de inventar.

cadastrar_produto

Cadastra um produto (item de NF-e). O `sku` é o código do CLIENTE — o mesmo que ele usa no ERP e que vai no `cProd` da nota. ⚠️ **Os valores do bloco `fiscal` têm de vir da pessoa.** Não escolha NCM, não invente `cst` nem `classificacao` de IBS/CBS, não deduza CFOP nem CST de ICMS a partir do nome do produto. Classificação fiscal errada vira nota errada, e a nota é do cliente. Se faltar um valor, **pergunte** — ou copie de um item que ela já cadastrou, com `listar_itens_do_catalogo`. Para NCM existe `buscar_ncm_por_descricao`, que consulta a tabela OFICIAL: mostre os candidatos e deixe a pessoa escolher. Para `cst` e `classificacao` não há consulta, e isso é deliberado — esses dois só podem vir dela. O preço **não** é do catálogo: omita `valor_unitario` se a emissão informa o valor a cada nota. `0` significa preço zero, não "não definido". O formato do `fiscal` espelha o item do payload de emissão: `NCM`, `cEAN`, `icms`, `pis`, `cofins`, `ibscbs`. Um `ibscbs.cst` de tributação com todas as alíquotas em zero é recusado — é a contradição que gerou milhares de rejeições.

cadastrar_servico

Cadastra um serviço (DPS de NFS-e). O `codigo` é o código do CLIENTE para o serviço. ⚠️ **Os valores do bloco `fiscal` têm de vir da pessoa.** Não escolha `cTribNac`, não invente `cNBS`, `CST` nem `cClassTrib`, não arbitre alíquota de ISS. Se faltar, **pergunte** — ou copie de um serviço que ela já cadastrou. O formato espelha o DPS, e cada chave é um nó dele: `cServ` (de `serv.cServ`), `tribMun` (de `valores.trib.tribMun`) e `IBSCBS`. NÃO entram aqui o município de prestação nem os valores — eles mudam a cada nota. Se um município exigir códigos diferentes (o caso típico é o `cTribMun`), isso é uma **exceção**, configurada à parte, e não um segundo cadastro.

atualizar_item_do_catalogo

⚠️ **SUBSTITUI O ITEM INTEIRO.** Todo campo que você não mandar fica vazio, e `fiscal` é trocado por completo — não é mesclado com o que estava lá. Então o caminho é sempre este, e não pule o primeiro passo: 1. `listar_itens_do_catalogo` com o `codigo`, para pegar o item como ele está hoje; 2. altere só o que a pessoa pediu; 3. mande o objeto **completo** aqui. Mandar só o campo que mudou apaga o resto sem avisar — inclusive a classificação fiscal, que vira nota errada depois. Vale a mesma regra do cadastro: os valores fiscais vêm da pessoa. Se ela pediu para mudar o nome, não aproveite para "corrigir" o NCM.

remover_item_do_catalogo

Remove o item do catálogo. A remoção é **lógica**: nada é apagado, o item sai das listagens e o código fica livre para ser cadastrado de novo. Diga à pessoa qual item você vai remover **antes** de chamar, com código e nome — "remove o serviço" numa conversa pode apontar para mais de um. > Se ela quiser o item de volta, use `reativar_item_do_catalogo`, e **não** um cadastro novo. Cadastrar o mesmo código de novo cria outro item, do zero, **sem nenhuma das exceções por município** que o antigo tinha. Reativar traz tudo junto.

reativar_item_do_catalogo

Traz de volta um item removido, **com as exceções por município que ele tinha**. É isso que diferencia reativar de cadastrar de novo: o cadastro novo nasce sem exceção nenhuma, e para um serviço com uma dezena de municípios isso significa refazer todos. Sempre prefira reativar quando a pessoa quer de volta algo que ela removeu. Para encontrar o que foi removido, use `listar_itens_do_catalogo` com `incluir_removidos`. Só funciona se não houver outro item ativo com o mesmo código — nesse caso, remova o outro antes.

resolver_item_do_catalogo

Diz qual bloco `fiscal` se aplica a um item num município, e **por quê**: `aplicado` vem `excecao` quando há uma configurada para aquele município, e `padrao` quando não há. Não é recomendação fiscal — é o cadastro da própria pessoa, resolvido. Use para conferir o que ela configurou antes de ela emitir, e para explicar por que uma nota vai sair com determinado código.

estado_da_captura

Diz, para uma empresa, se a captura de notas recebidas (NF-e e NFS-e emitidas CONTRA ela, por fornecedores) está incluída no plano, ligada, em dia ou com erro, e quando foi a última consulta. Mostra também se há webhook configurado. Situações: `nao_incluida_no_plano`, `desligada`, `sincronizando` (baixando o histórico), `em_dia`, `aguardando_limite_de_consumo` (espera imposta pela fonte, não é defeito) e `com_erro` (o campo `erro` diz o motivo — ex.: certificado vencido).

listar_notas_recebidas

Lista as notas que fornecedores emitiram CONTRA a empresa (ela é tomadora, destinatária ou intermediária), capturadas das fontes oficiais. As notas que a própria empresa emitiu não aparecem aqui. Datas em AAAA-MM-DD, no fuso de Brasília. `situacao` vem como a fonte informou; um valor como `cstat-107` é um código que ainda não interpretamos — diga isso à pessoa em vez de supor. Para ler o conteúdo de uma nota (itens, valores, impostos), use `xml_da_nota_recebida`.

xml_da_nota_recebida

Devolve o XML de uma nota recebida, para ler itens, valores e impostos. Pegue a `chave` em `listar_notas_recebidas`. Numa NF-e, pode vir só o RESUMO, se a nota integral ainda não chegou — a resposta avisa. Informe `cpf_cnpj` se a mesma nota aparecer em mais de uma empresa da conta.

ligar_ou_desligar_captura

Liga ou desliga, por tipo, a captura de notas recebidas de uma empresa. Exige chave de PRODUÇÃO: a captura lê as notas reais, não existe captura de homologação. Desligar para de capturar e mantém o que já foi capturado. ⚠️ **Ligar a NF-e é um aceite em nome da empresa.** Ligada, a captura registra na SEFAZ a Ciência da Operação de cada NF-e recebida — é o que libera o XML completo. Antes de enviar `aceite_ciencia_da_operacao: true`, explique isso à pessoa com essas palavras e só envie depois de um "sim" EXPLÍCITO dela a esse aceite. Pedido genérico ("liga tudo") não é aceite. Sem o aceite, a API recusa e devolve o texto a mostrar. Ligar a NFS-e não tem aceite. Diga à pessoa, antes de chamar, qual empresa e quais tipos vão mudar. O webhook de aviso é configurado no painel, não por aqui.