Pular para o conteúdo

Contta para desenvolvedores

API de NFS-e Nacional

Referência gerada do contrato da API. Servidor base: https://app.contta.com.br. Versão do contrato 1.0.0, no padrão OpenAPI 3.0.3.

Como funciona

API de NFS-e Nacional do Contta: emite, consulta, cancela e devolve o PDF de notas de serviço pelo emissor nacional (Sefin Nacional), em nome das empresas do seu escritório.

Como funciona. Você manda o FATO (o que foi feito, para quem e quanto). O Contta decide código de serviço, alíquota, retenção e regime pelo cadastro fiscal da empresa e devolve uma PRÉVIA. A nota só sai quando você confirma a prévia com o previa_hash. Faltou algo: a resposta traz pendencias com a pergunta pronta; pedido recusado traz proximo_passo.

Autenticação. Authorization: Bearer ctk_.... A chave é criada por um responsável do escritório (owner/admin) em Contta > Emissão > Chaves de API e age em nome dessa pessoa. Escopos: nfse:emitir (emitir, confirmar, cancelar) e nfse:consultar (consultar, listar, PDF, XML).

Teste e produção. Chave nova emite só na homologação nacional (nota de teste, sem valor fiscal). Nota real exige chave liberada pelo dono do escritório e a empresa liberada para produção.

Idempotência. Mande request_id no corpo ou o header Idempotency-Key: o mesmo pedido repetido devolve o mesmo resultado, sem nota em dobro. Resposta 202 no confirmar = o fisco ainda não respondeu: consulte, nunca confirme de novo.

Limite. 120 pedidos por minuto por chave (HTTP 429 acima disso).

Autenticação, ambientes e limites

  • Chave. Mande Authorization: Bearer ctk_... em todo pedido. A chave é criada no app, menu Emissão > Chaves de API, por quem é administrador ou dono do escritório. Escopos: nfse:emitir e nfse:consultar.
  • Homologação e produção. Chave nova só emite na homologação nacional: a nota é de teste e não tem valor fiscal. Produção exige chave liberada pelo dono do escritório e empresa liberada para produção.
  • Idempotência. Mande o header Idempotency-Key (ou request_id no corpo): o mesmo pedido repetido devolve o mesmo resultado, sem nota em dobro. No confirmar, a resposta 202 quer dizer que o fisco ainda não respondeu: consulte o pedido e nunca confirme de novo.
  • Limite. 120 pedidos por minuto por chave. Acima disso a resposta é 429.

Exemplos com curl

Chave, empresa e pedido são fictícios. Troque ctk_SUA_CHAVE_AQUI pela sua chave e os identificadores pelos que a API devolver. O CNPJ do tomador é um exemplo, não é de ninguém.

Emitir (montar a prévia)

Você manda o fato; o Contta devolve a prévia com o previa_hash e o ambiente. Nada é emitido ainda.

curl
curl -X POST https://app.contta.com.br/api/v1/nfse-nacional/ \
  -H "Authorization: Bearer ctk_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: venda-2026-11-08-0001" \
  -d '{"empresa_id":"3f0c6c2e-0000-4000-8000-000000000001","fato":{"descricao":"Consultoria contábil de novembro","valor":"1500.00","tomador":{"documento":"11222333000181"}}}'

Confirmar (emitir de fato)

Envia ao fisco a prévia conferida. Se voltar 202, o fisco ainda não respondeu: consulte, nunca confirme de novo.

curl
curl -X POST https://app.contta.com.br/api/v1/nfse-nacional/7a1d9e52-0000-4000-8000-000000000002/confirmar/ \
  -H "Authorization: Bearer ctk_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"previa_hash":"HASH_DA_PREVIA"}'

Consultar um pedido

Mostra o estado atual: prévia, pendências, emitida ou recusada.

curl
curl https://app.contta.com.br/api/v1/nfse-nacional/7a1d9e52-0000-4000-8000-000000000002/ \
  -H "Authorization: Bearer ctk_SUA_CHAVE_AQUI"

Listar os pedidos de uma empresa

curl
curl "https://app.contta.com.br/api/v1/nfse-nacional/?empresa_id=3f0c6c2e-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer ctk_SUA_CHAVE_AQUI"

Baixar o PDF (só nota de produção)

curl
curl -o nota.pdf https://app.contta.com.br/api/v1/nfse-nacional/7a1d9e52-0000-4000-8000-000000000002/pdf/ \
  -H "Authorization: Bearer ctk_SUA_CHAVE_AQUI"

Baixar o XML autorizado

Funciona também para nota de teste (homologação).

curl
curl -o nota.xml https://app.contta.com.br/api/v1/nfse-nacional/7a1d9e52-0000-4000-8000-000000000002/xml/ \
  -H "Authorization: Bearer ctk_SUA_CHAVE_AQUI"

Operações

As 10 operações do contrato, com parâmetros, corpo e respostas.

GET/api/v1/nfse-nacional/

Listar pedidos

Parâmetros

NomeOndeObrigatórioO que é
empresa_idquerynãoEmpresa; sem ela, use all_empresas=true.

Respostas

  • 200 · application/json · ListaNfse
    Campos de ListaNfse
    CampoTipoObrigatórioO que é
    itenslista de objetosim

POST/api/v1/nfse-nacional/

Emitir (montar a prévia)

Monta a prévia da nota a partir do FATO (o que, para quem, quanto). Imposto, código e alíquota o sistema decide; não se mandam. Faltou algo: estado REJECTED com pendencias. Chave sem liberação de produção: a nota vai para a homologação nacional (teste).

Corpo (JSON) · EmitirNfseRequest

Campos do corpo
CampoTipoObrigatórioO que é
fatoobjetosim
fato.descricaostringsimO que foi feito, como deve sair na nota.
fato.valorstringsimValor total do serviço, em reais (ex.: "1500.00").
fato.data_fatostring (date)nãoData do serviço; sem ela, hoje.
fato.tomadorobjetonão
fato.tomador.documentostringsimCPF ou CNPJ de quem contratou.
fato.tomador.nomestringnão
fato.servico_slugstringnãoServiço cadastrado da empresa (a resposta oferece as opções quando há mais de um).
empresa_idstring (uuid)sim
request_idstringnãoChave de idempotência do pedido. Sem ela vale o header Idempotency-Key.

Respostas

  • 201 · application/json · PedidoNfse
    Campos de PedidoNfse
    CampoTipoObrigatórioO que é
    comando_idstring (uuid)sim
    estadostringsim
    ambientestringsimHOMOLOGATION (teste) ou PRODUCTION (real).
    previaobjetosimPrévia; `hash` vai no confirmar.
    pendenciaslista de objetosimO que falta, com a pergunta pronta.
    proximo_passoobjetonãoPedido recusado: o que fazer.
    numerostring ou nulosim
    chavestring ou nulosim
    mensagem_leigastringsim

GET/api/v1/nfse-nacional/{comando_id}/

Consultar um pedido

Parâmetros

NomeOndeObrigatórioO que é
comando_idcaminhosim

Respostas

  • 200 · application/json · PedidoNfse

    Mesmo formato de PedidoNfse.

POST/api/v1/nfse-nacional/{comando_id}/cancelar/

Cancelar (montar o pedido)

Devolve o pedido de cancelamento com prévia; confirme em /{id}/confirmar/ do NOVO pedido.

Parâmetros

NomeOndeObrigatórioO que é
comando_idcaminhosim

Corpo (JSON) · CancelarNfseRequest

Campos do corpo
CampoTipoObrigatórioO que é
justificativastringsimDe 15 a 255 letras.
codigo_motivostringnão1 = erro na emissão (padrão).

Respostas

  • 201 · application/json · PedidoNfse

    Mesmo formato de PedidoNfse.

POST/api/v1/nfse-nacional/{comando_id}/confirmar/

Confirmar (emitir de fato)

Envia ao fisco a prévia conferida. 202 = o fisco ainda não respondeu: consulte de novo, nunca confirme outra vez.

Parâmetros

NomeOndeObrigatórioO que é
comando_idcaminhosim

Corpo (JSON) · ConfirmarNfseRequest

Campos do corpo
CampoTipoObrigatórioO que é
previa_hashstringsim
ambiente_esperado"HOMOLOGATION" | "PRODUCTION"nãoAmbiente que você viu na prévia. Sem ele, vale o da própria prévia.

Respostas

  • 200 · application/json · PedidoNfse

    Mesmo formato de PedidoNfse.

  • 202 · application/json · PedidoNfse

    Mesmo formato de PedidoNfse.

GET/api/v1/nfse-nacional/{comando_id}/pdf/

PDF da nota (DANFSe)

Parâmetros

NomeOndeObrigatórioO que é
comando_idcaminhosim

Respostas

  • 200 · application/pdf

GET/api/v1/nfse-nacional/{comando_id}/xml/

XML autorizado

Parâmetros

NomeOndeObrigatórioO que é
comando_idcaminhosim

Respostas

  • 200 · application/xml

GET/api/v1/nfse-nacional/chaves/

Listar chaves

Só pela tela, com login.

Respostas

  • 200 · sem corpo · No response body

POST/api/v1/nfse-nacional/chaves/

Criar chave

O texto da chave volta UMA vez, na criação. Guarde-o: depois só aparece o prefixo.

Só pela tela, com login.

Corpo (JSON) · CriarChaveRequest

Campos do corpo
CampoTipoObrigatórioO que é
nomestringsim
escoposlista de "nfse:emitir" | "nfse:consultar"sim
producaobooleannãoSó o dono do escritório libera nota real.

Respostas

  • 200 · sem corpo · No response body

POST/api/v1/nfse-nacional/chaves/{chave_id}/revogar/

Revogar chave

Só pela tela, com login.

Parâmetros

NomeOndeObrigatórioO que é
chave_idcaminhosim

Respostas

  • 200 · sem corpo · No response body

Códigos de erro

O corpo do erro é sempre {"error": codigo, "mensagem_leiga": "...", "detalhe": "..."}; o campo detalhe só vem quando ajuda.

Respostas de erro da API
HTTPerrorQuando acontece
401chave_invalidaChave inválida ou revogada.
401chave_sem_donoQuem criou a chave saiu do escritório: crie outra.
401identidade_insuficienteA chave não identifica quem pede com a segurança que a operação exige.
403escopo_ausenteA chave não tem o escopo da operação (nfse:emitir ou nfse:consultar).
403producao_nao_liberadaA chave só emite teste; a liberação para nota real é do dono do escritório.
404not_foundPedido ou empresa não encontrados para essa chave.
404nota_de_testeO PDF só existe para nota de produção; use /xml/.
409ambiente_mudouO ambiente da prévia mudou desde que você a viu: monte a prévia de novo.
422fato_invalidoO fato não passou na validação (ex.: faltou request_id ou Idempotency-Key).
429limiteMais de 120 pedidos por minuto com a mesma chave: espere e tente de novo.
202(sem erro)No confirmar: o fisco ainda não respondeu. Consulte o pedido; nunca confirme outra vez.

Resposta fora desta lista: guarde o pedido (Idempotency-Key) e escreva para empresarial@contta.com.br.

Precisa de uma chave?

Fale com a equipe do Contta.

A chave de produção é liberada pelo dono do escritório. Escreva e a gente combina os próximos passos.

WhatsApp