Ext. Contabilidade
Entrar
API de NFS-e

NFS-e emitida pelo seu código.

API REST para empresas Ext. Você manda valor e descrição — a Ext resolve competência, tributação, certificado, XML assinado e o PDF da nota.

Ler a referência Gerar uma chave
  • Emissor Nacional
  • Certificado custodiado
  • PDF e XML
POST /v1/nfse
# valor em CENTAVOS: R$ 1.250,50 = 125050
# reference: o id da fatura no seu sistema — reencontra a nota e recusa a segunda
# cnae: opcional — sem ele a nota sai na atividade principal da empresa
curl -X POST https://api.extcontabilidade.com.br/v1/nfse \
  -H "Authorization: Bearer $EXT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount_in_cents": 125050,
    "description": "Licenciamento de uso da plataforma — plano mensal",
    "customer": { "document": "12345678000190" },
    "reference": "INV-2026-0042",
    "cnae": "6202300"
  }'

Da liberação à primeira nota.

Só o primeiro passo depende de nós.

01Peça a liberaçãoA API entra em parte dos planos. O suporte confirma o seu e libera a empresa.Pedir acesso no WhatsApp
02Gere a chaveEm Minha conta → API, de produção ou de teste. Ela aparece uma única vez.
03EmitaAuthorization: Bearer ext_sk_… e um POST em /v1/nfse. Comece pela chave de teste — o código é o mesmo.
Superfície

A superfície inteira, e o contrato.

Campo a campo na referência
O contrato em formato de máquina

Gerados do código a cada montagem, sem chave para ler. Aponte o seu agente ou o gerador de cliente para eles, não para esta página.

/v1/openapi.json/llms.txt/llms-full.txt
Do POST à nota

Você manda o essencial. A Ext faz o resto.

amount_in_cents e description. Competência, tributação, certificado, XML assinado e PDF da nota ficam fora do seu backend — é o mesmo pipeline que já emite as suas notas.

01
Antes de emitirA Ext resolve o que a nota declara
  • Tributação pelo CNAEO código de tributação da nota sai do CNAE — o principal da empresa, ou o que você mandar em cnae.
  • Alíquota calculadaA efetiva do Simples Nacional, pelo faturamento dos últimos 12 meses. Optante não destaca ISS na nota: ele é apurado no imposto mensal.
  • Município pelo cadastroCidade e UF viram código IBGE contra a tabela oficial dos 5.571 municípios.
  • Tomador pelo CNPJMande só o documento — o nome sai do cadastro. Ou omita customer: sai nota sem destinatário.
02
Na emissãoA DPS é montada, assinada e transmitida
  • Certificado no cofreO e-CNPJ assina o XML e faz o TLS mútuo com o SEFIN. Sem upload, sem senha no seu código.
  • XML assinadoDPS 1.01 na ordem do XSD, assinada com XMLDSig/RSA-SHA256 e transmitida ao Emissor Nacional.
  • Sequencial sem colisãoO número da DPS é reservado atomicamente por empresa.
03
Depois de autorizadaO que a nota disponibiliza
  • PDF da nota (DANFSe)Gerado do XML autorizado, com o QR code oficial. Vem como bytes na resposta, não como link.
  • XML autorizado e access_keyOs dois saem pela API assim que a nota chega a issued.
  • A mesma nota do painelA mesma entidade da tela: aparece na sua lista e aceita cancelar, substituir e baixar. A de teste também, marcada e com prazo, em coleção separada — fora de faturamento e imposto.
MCP

A mesma API, no seu agente.

/v1/mcp é um servidor MCP: as operações desta página publicadas como ferramentas. A chave é a que você já tem, e o catálogo sai do mesmo contrato — rota nova na API vira ferramenta sem release do seu lado.

  • issue_nfseEmite a nota. Devolve o mesmo 202 do POST — o agente consulta antes de anunciar que saiu.
  • get_nfseConsulta a nota inteira pelo id, incluindo o erro quando houver.
  • find_nfse_by_referenceReencontra a nota pela sua referência, sem guardar o id da Ext.
  • cancel_nfseCancela a nota, dentro do mês da emissão. É irreversível.
  • list_activitiesLista as atividades em que a empresa pode emitir.
claude mcp add --transport http --scope user ext \
  https://api.extcontabilidade.com.br/v1/mcp \
  --header "Authorization: Bearer SUA_CHAVE"

Roda no terminal. Com --scope user o conector vale em qualquer diretório, não só no atual.

Onde isso conecta hoje

Em clientes que aceitam header de autenticação — os cinco das abas acima. Claude na web, no celular e o ChatGPT só instalam conector por OAuth, que ainda não publicamos: até lá, a conexão é local.

As regras fiscais antes de integrar.

Nenhuma delas se desfaz com um retry.

ext_sk_live_ emite na primeira chamada

Documento fiscal já no primeiro POST, sem confirmação e sem desfazer. Integre com ext_sk_test_ (mesmo código, livemode: false) e vá a produção trocando a variável de ambiente.

A competência é sempre o mês corrente

Competência é o mês fiscal da nota, e você não a envia: é a data da chamada. Não há emissão retroativa — mês fechado obrigaria a retificar a declaração daquele mês, e o SEFIN rebaixa em silêncio competência posterior à emissão.

Cancelamento é pela API, só no mês da emissão

A janela é o mês-calendário da emissão: nota de 31/07 percebida em 01/08 já está fora. Dentro dela, POST /v1/nfse/{id}/cancel; fora dela, é o suporte. Substituir continua fora do v1 — só pelo painel ou pelo suporte.

Sem ISS retido e sem MEI

O ISS sai sempre como não retido, e o regime vem do cadastro da empresa. Operação com retenção na fonte, ou empresa MEI, não sai representada corretamente.

Exportação de serviço pede o payload dela

Serviço prestado ao exterior sai por aqui, mas só quando declarado: customer.type "foreign", com o endereço completo do tomador, a identificação fiscal dele (ou o motivo da ausência) e o valor na moeda do faturamento. Sem isso a nota é tratada como doméstica — e a divergência só aparece na apuração.

failed e indeterminate pedem ações opostas

Em failed nada foi emitido: corrigir e reemitir é seguro. Em indeterminate pode existir NFS-e autorizada na prefeitura sem registro aqui — nunca reemita automaticamente, porque nota em duplicidade só se desfaz com cancelamento formal, e cancelamento tem prazo.

O suporte é pelos canais que você já usa com a Ext.

Perguntas de quem vai integrar.

O que costuma aparecer antes da primeira chamada — e depois dela.

Preciso ser cliente da Ext para usar a API?

Sim. A emissão usa o certificado e-CNPJ que a Ext custodia e a habilitação da empresa no Emissor Nacional — os dois só existem para quem já é cliente. Não é um gateway aberto de notas.

Como consigo uma chave?

A API entra em parte dos planos, e quem confirma e libera a empresa é o suporte. Liberada, você cria e revoga as chaves em Minha conta → API, escolhendo produção (ext_sk_live_) ou teste (ext_sk_test_).

São até cinco chaves ativas por modo, não cinco no total. A chave aparece uma única vez, na criação.

Dá para entregar o contrato ao meu agente de IA?

Dá, e é o caminho recomendado: os três arquivos são gerados do próprio código a cada montagem, então não envelhecem como um trecho copiado desta página.

llms.txt traz o resumo na convenção llmstxt.org; llms-full.txt traz campo a campo, operação a operação; openapi.json é o documento OpenAPI 3.1 completo, que também abre em Postman, Insomnia ou num gerador de cliente.

Os três são públicos e não exigem chave para ler.

Tem cobrança por nota emitida pela API?

Não. A emissão pela API é benefício do plano: contabilizada, não cobrada. Nenhuma quota bloqueia emissão — barrar a nota de um serviço prestado atrapalharia uma obrigação sua.

A nota emitida pela API entra na minha apuração?

Entra, pelo mesmo caminho de qualquer NFS-e sua — é a mesma nota que a Ext emitiria pela tela. Ela é capturada do ambiente nacional e alimenta a sua apuração de impostos junto com as demais, sem nada a fazer do seu lado.

Qual é o suporte?

Pelos canais que você já usa com a Ext. Ao abrir chamado, cite o request_id: ele vem no corpo de toda falha e no header Request-Id das rotas de /v1/nfse, e é o que localiza a requisição exata nos nossos logs.

Pronto para a primeira chamada?

Ler a referência Gerar uma chave