Emita documentos fiscais pelo seu sistema

▸Qual documento você vai emitir?

Cada documento tem cota, cadastro e homologação próprios. O que é comum a todos — credencial, empresas, tomadores, numeração, formato de erro — está nos passos 1 e 2. Depois, siga só o bloco do seu documento.

1Pegue sua credencial

No painel do Emissor, abra Empresas → API → Gerar (ou peça à contabilidade). O código nce_… aparece uma única vez — guarde com segurança.

Há dois tipos de credencial:

# Toda chamada leva o header:
Authorization: Bearer nce_SUA_CREDENCIAL

2Conheça a empresa

Confira o cadastro e descubra os códigos de serviço disponíveis — o codigo_tributacao_nacional que você vai usar na emissão sai daqui.

curl https://emite-api.notacentral.com.br/v1/empresa \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL"

curl https://emite-api.notacentral.com.br/v1/servicos \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL"

Os itens são as descrições prontas que quem emite escolhe no painel — use a descricao deles na nota (e, na equiparação hospitalar, a classificacao_medica):

curl https://emite-api.notacentral.com.br/v1/itens \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL"

Com credencial do workspace, primeiro liste as empresas e depois use o id no caminho:

curl https://emite-api.notacentral.com.br/v1/empresas \
  -H "Authorization: Bearer nce_CREDENCIAL_DO_WORKSPACE"

curl https://emite-api.notacentral.com.br/v1/empresas/{id}/servicos \
  -H "Authorization: Bearer nce_CREDENCIAL_DO_WORKSPACE"

curl https://emite-api.notacentral.com.br/v1/empresas/{id}/itens \
  -H "Authorization: Bearer nce_CREDENCIAL_DO_WORKSPACE"

Com o turbo NC Saúde ativo, a resposta de /v1/empresa (ou /v1/empresas/{id}) inclui o objeto equiparacao_hospitalar com o corpo clínico — use-o para montar a cota_medica.

2½Confira os impostos antes de emitir (dry-run)

Seu sistema não precisa conhecer a regra fiscal. Mande o mesmo JSON da emissão para POST /v1/notas/dry-run: a resposta traz ISS (alíquota, valor, se é retido e por quê), retenções federais (PIS, COFINS, CSLL, IRRF, INSS), IBS/CBS quando a calculadora está ligada, o líquido e a memória de cálculo — inclusive o que não foi retido e o motivo. Nada é gravado: sem rascunho, sem número, sem nota. Mostre para quem confere e, se estiver de acordo, envie o mesmo corpo para POST /v1/notas.

curl -X POST https://emite-api.notacentral.com.br/v1/notas/dry-run \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL" -H "Content-Type: application/json" \
  -d '{"tomador":{"cpf_cnpj":"46009718000140","nome":"HOSPITAL X"},"valor":25087.80,"competencia":"2026-09","codigo_tributacao_nacional":"040301"}'

# resposta (resumida)
{"dados":{"valor_servico":25087.8,
  "iss":{"aliquota":5,"valor":1254.39,"retido":true,"exigibilidade":"exigivel","explicacao":"…"},
  "retencoes_federais":{"pis":163.07,"cofins":752.63,"csll":250.88,"irrf":376.32,"inss":0,"total":1542.9},
  "valor_liquido":22290.51,
  "memoria_calculo":[{"grupo":"irrf","aplicada":true,"aliquota":1.5,"valor":376.32,"explicacao":"…"}, …]},
 "meta":{"simulacao":true}}

3Emita a nota

O mínimo indispensável: tomador (CPF/CNPJ + nome), valor e competência. O resto é opcional — omitido, valem os padrões cadastrados da empresa.

curl -X POST https://emite-api.notacentral.com.br/v1/notas \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "tomador":            { "cpf_cnpj": "00000000000191", "nome": "Cliente Exemplo" },
    "valor":              150.00,
    "competencia":        "2026-08",
    "descricao":          "Consultoria em tecnologia",
    "referencia_externa": "pedido-8412"
  }'

# Resposta: HTTP 202
{ "dados": { "id": "f2b41c…", "situacao": "na_fila" } }

4Acompanhe até autorizar

A emissão é assíncrona e leva segundos. Consulte a nota até a situação virar emitida (sugestão: a cada 2–3 s, com timeout de 1 minuto).

curl https://emite-api.notacentral.com.br/v1/notas/{id} \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL"

# Autorizada:
{ "dados": {
  "situacao":     "emitida",
  "numero_dps":   93,
  "chave_acesso": "3511508226391706100013800000000000712…",
  "links": {
    "xml":    "https://emite-api.notacentral.com.br/nfse/…/….xml",
    "danfse": "https://emite-api.notacentral.com.br/nfse/…/….pdf"
  }
} }

Nota cancelada tem três documentos, e os três vêm em links: xml (a nota existiu), danfse (o mesmo PDF, já regerado com a marca CANCELADA) e xml_cancelamento — o XML assinado do evento, que é a prova do cancelamento e o que a contabilidade pede.

Os links são permanentes e públicos (URL não-adivinhável): grave no seu sistema, mande por e-mail ao cliente — não expiram e não pedem autenticação. Se a nota for rejeitada, o objeto rejeicao vem com o motivo explicado em português; cancelada, o objeto cancelamento traz motivo e data.

5Cancelar a nota

Cancelar pede motivo — ele vai no evento assinado que mandamos ao órgão e fica registrado na nota. A chamada é síncrona: a resposta só volta depois que o órgão aceitou. O DANFSe é regerado com a marca CANCELADA e os links da nota continuam os mesmos.

curl -X POST https://emite-api.notacentral.com.br/v1/notas/{id}/cancelar \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL" -H "Content-Type: application/json" \
  -d '{"motivo":"Serviço não executado"}'

{ "dados": { "id": "f2b41c…", "situacao": "cancelada", "motivo": "Serviço não executado" } }

# Depois, GET /v1/notas/{id} traz os três documentos:
{ "links": {
  "xml":              "…/nfse/{token}/{chave}.xml",
  "danfse":           "…/nfse/{token}/{chave}.pdf",
  "xml_cancelamento": "…/nfse/{token}/{chave}-cancelamento.xml"
} }

O prazo e as regras são de cada prefeitura. Passado o prazo, o caminho costuma ser substituir a nota ou abrir processo no município.

+Tomadores: cadastro pela API

O cadastro de tomadores é o mesmo do painel e é do workspace: qualquer credencial da conta enxerga e altera o mesmo registro. A emissão enriquece a nota a partir dele pelo CPF/CNPJ — endereço (obrigatório em municípios que ancoram o ISS no domicílio do tomador), inscrição municipal (em São Paulo decide se o ISS pode ser retido) e e-mail.

# cria ou atualiza pelo documento — um único verbo; campos omitidos ficam como estão
curl -X POST https://emite-api.notacentral.com.br/v1/tomadores \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL" -H "Content-Type: application/json" \
  -d '{"cpf_cnpj":"46009718000140","nome":"HOSPITAL X LTDA","email":"fiscal@hospitalx.com.br",
       "inscricao_municipal":"12345678",
       "endereco":{"logradouro":"Av. Paulista","numero":"1000","bairro":"Bela Vista",
                   "municipio":"São Paulo","codigo_municipio":"3550308","uf":"SP","cep":"01310100"}}'
# 201 criado · 200 já existia e foi atualizado (meta.criado diz qual)

curl https://emite-api.notacentral.com.br/v1/tomadores/46009718000140 -H "Authorization: Bearer nce_…"
curl "https://emite-api.notacentral.com.br/v1/tomadores?busca=hospital" -H "Authorization: Bearer nce_…"

Na resposta, endereco_completo diz se há código IBGE + CEP — o mínimo que a emissão exige quando o município pede o domicílio do tomador. Alíquotas de retenção por tomador e o marcador de substituto tributário ficam no painel (escritório de contabilidade).

#Numeração: empresa que veio de outro emissor

A numeração de DPS/RPS é por empresa e por série, e começa em 1. Se a empresa já emitia por outro sistema, a prefeitura já tem números usados nessa série. O emissor tolera isso até 5 números seguidos na mesma emissão (salta e tenta o próximo) e depois para: a nota fica rejeitada com rejeicao.codigo = "dps_number_collision". É de propósito — continuar tentando queimaria numeração na prefeitura sem limite. Nada é emitido nesse caso.

O jeito certo é posicionar a série antes da primeira nota. A API mostra onde ela está e de onde deveria continuar, com base nas notas que a captura do Nota Central já viu para o CNPJ:

curl https://emite-api.notacentral.com.br/v1/numeracao -H "Authorization: Bearer nce_SUA_CREDENCIAL"

{"dados":{"serie_padrao":"1",
  "series":[{"serie":"1","proximo_numero":95}],
  "sugestao":{"disponivel":true,"serie":"1","proximo_numero":101,"maior_numero_capturado":100,
              "notas_capturadas":100,"ultima_nota_em":"2026-09-14T16:40:00Z","estimativa":false,
              "explicacao":"Baseado na nota mais recente capturada: a próxima livre é esta."},
  "teto_de_saltos":5}}

# ajusta: a próxima nota da série sai com este número
curl -X PUT https://emite-api.notacentral.com.br/v1/numeracao \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL" -H "Content-Type: application/json" \
  -d '{"serie":"1","proximo_numero":101}'

Cada documento tem a própria numeração. Sem documento a chamada é da NFS-e; para CT-e e MDF-e envie ?documento=cte no GET e "documento": "cte" no PUT (a série padrão vem do bloco Transporte da empresa). A sugestão da captura existe só para NFS-e.

Credencial do workspace: /v1/empresas/{id}/numeracao ou empresa_id no corpo/query. Todo ajuste fica na trilha de auditoria com a credencial como autora.

+Conta Azul: cada nota vira conta a receber

Com a integração ligada, toda NFS-e emitida pela empresa vira uma conta a receber no Conta Azul da própria empresa, pelo valor líquido, com o tomador como cliente e os links permanentes do PDF e do XML na observação. Tudo pela API, sem abrir o painel. São três passos:

# 1. gere o link e mande o CLIENTE abrir (o login no Conta Azul é dele)
curl -X POST https://emite-api.notacentral.com.br/v1/conta-azul/conectar \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL" -H "Content-Type: application/json" \
  -d '{"url_retorno":"https://seu-sistema.com/conta-azul/retorno"}'

{"dados":{"url_autorizacao":"https://login.contaazul.com/#/oauth/authorize?…","expira_em":"2026-10-01T18:10:00Z"}}

# 2. depois que ele autorizar: escolha a conta financeira e ligue
curl https://emite-api.notacentral.com.br/v1/conta-azul/contas-financeiras -H "Authorization: Bearer nce_…"
curl -X PUT https://emite-api.notacentral.com.br/v1/conta-azul \
  -H "Authorization: Bearer nce_…" -H "Content-Type: application/json" \
  -d '{"conta_financeira_id":"c1d2…","vencimento_dias":15,"ligado":true}'

# 3. acompanhe
curl "https://emite-api.notacentral.com.br/v1/conta-azul/lancamentos?situacao=falhou" -H "Authorization: Bearer nce_…"
curl https://emite-api.notacentral.com.br/v1/notas/{id}/conta-azul -H "Authorization: Bearer nce_…"

Credencial do workspace: os mesmos caminhos sob /v1/empresas/{id}/conta-azul. O Conta Azul não aceita anexos pela API dele, por isso o PDF e o XML vão como links permanentes na observação do lançamento.

+Equiparação hospitalar (NC Saúde)

Clínica no lucro presumido com equiparação hospitalar apura IRPJ/CSLL com base reduzida (8% / 12% em vez de 32%) sobre os serviços hospitalares. Para isso a nota precisa dizer quanto de cada valor é de qual médico — a cota médica. O Nota Central grava a cota na nota e monta os relatórios de segregação e apuração a partir dela.

Pré-requisitos (uma vez por empresa)

Cadastro de médicos pela API

É o mesmo cadastro do painel e do app: o que você cria aqui aparece lá. O id devolvido é o doctor_id da cota. O percentual_padrao só pré-preenche o rateio — a cota de cada nota é quem emite que decide.

# cadastrar
curl -X POST https://emite-api.notacentral.com.br/v1/medicos \
  -H "Authorization: Bearer nce_SUA_CREDENCIAL" -H "Content-Type: application/json" \
  -d '{"nome":"Dra. Ana Souza","cpf":"52998224725","crm":"123456-SP","percentual_padrao":60}'
# → 201 {"dados":{"id":"0d2f…","nome":"Dra. Ana Souza","cpf":"52998224725","crm":"123456-SP","percentual_padrao":60,"ativo":true}}

# listar (meta diz se a equiparação está ligada e quanto somam os % padrão)
curl https://emite-api.notacentral.com.br/v1/medicos -H "Authorization: Bearer nce_SUA_CREDENCIAL"

# alterar (campos omitidos ficam como estão) · remover (some das próximas notas)
curl -X PATCH  …/v1/medicos/{id} -d '{"percentual_padrao":40}'
curl -X DELETE …/v1/medicos/{id}

Credencial do workspace: use /v1/empresas/{id}/medicos ou mande empresa_id no corpo.

Emitindo com cota médica

No POST /v1/notas (e no dry-run), mande cota_medica: uma lista com uma linha por médico, em reais. Informe o doctor_id e o sistema completa nome, CPF e CRM do cadastro. A soma das linhas deve ser o valor da nota (ou a parte dela que é serviço médico).

{
  "tomador": {"cpf_cnpj": "46009718000140", "nome": "HOSPITAL X"},
  "valor": 10000.00,
  "competencia": "2026-09",
  "codigo_tributacao_nacional": "040301",
  "descricao": "Procedimentos cirúrgicos — setembro/2026",
  "cota_medica": [
    {"doctor_id": "0d2f1a3c-…", "amount": 6000.00},
    {"doctor_id": "1e3a2b4d-…", "amount": 4000.00}
  ],
  "referencia_externa": "fat-2026-09-0412"
}

Depois de emitida, a nota entra na Segregação (consulta × procedimento, pela classificação do item) e na Apuração (IRPJ/CSLL com e sem equiparação) da competência — os relatórios ficam no painel, em Equiparação.

Conferindo o rateio de uma nota

O que você mandou em cota_medica volta em GET /v1/notas/{id}, já com o valor e o percentual de cada médico e a economia da equiparação:

curl https://emite-api.notacentral.com.br/v1/notas/{id} -H "Authorization: Bearer nce_…"

{ "dados": { "situacao": "emitida", "valor": 10000.00,
  "cota_medica": [
    {"medico": "Dra. Ana Souza", "cpf": "52998224725", "crm": "123456-SP",
     "valor": 6000.00, "percentual": 60, "equiparacao": true, "economia": 240.00},
    {"medico": "Dr. Bruno Lima", "valor": 4000.00, "percentual": 40, "equiparacao": false}
  ] } }

Vem só na consulta de uma nota, não na listagem: são linhas de outra tabela, e anexá-las a cada item de uma página de 50 notas seriam 50 consultas extras. Para indicador, use o agregado abaixo.

Produção por médico (para indicadores)

Quanto cada médico fez no período, já somado — o mesmo número da tela de Apuração:

curl "https://emite-api.notacentral.com.br/v1/medicos/cotas?de=2026-07&ate=2026-09" \
  -H "Authorization: Bearer nce_…"

{ "dados": [
    {"medico": "Dra. Ana Souza", "crm": "123456-SP", "notas": 12, "valor": 36000.00, "economia": 1440.00},
    {"medico": "Dr. Bruno Lima", "notas": 5, "valor": 12500.00, "economia": 0}
  ],
  "meta": {"de": "2026-07", "ate": "2026-09", "medicos": 2, "notas": 17,
           "valor_total": 48500.00, "economia_total": 1440.00} }

CTCT-e: conhecimento de transporte pela API

Fluxo: PUT /v1/tomadores para remetente e destinatário (com endereço completo) → POST /v1/cte → GET /v1/cte/{id} até emitida. Cancelamento pelo mesmo POST /v1/notas/{id}/cancelar; carta de correção em POST /v1/cte/{id}/carta-correcao. O emitente (CNPJ, IE, CRT, endereço, RNTRC, série e ambiente) vem do cadastro da empresa: não vai no corpo.

Pré-requisitos (uma vez por empresa)

Nos links da resposta, o PDF do CT-e vem como dacte (e também pdf); o XML autorizado em xml.

Pedido mínimo

POST /v1/cte
{
  "referencia_externa": "FRETE-2026-000123",
  "inicio": {"codigo": "3550308", "nome": "Sao Paulo", "uf": "SP"},
  "fim":    {"codigo": "3304557", "nome": "Rio de Janeiro", "uf": "RJ"},
  "tomador": 0, "indicador_ie_tomador": 1,
  "remetente":    {"cpf_cnpj": "98765432000100", "inscricao_estadual": "987654321098", "nome": "EMBARCADOR SA",
                   "endereco": {"logradouro": "Rua A", "numero": "10", "bairro": "Centro", "codigo_municipio": "3550308", "municipio": "Sao Paulo", "uf": "SP", "cep": "01001000"}},
  "destinatario": {"cpf_cnpj": "11222333000181", "inscricao_estadual": "ISENTO", "nome": "LOJA DO RIO LTDA",
                   "endereco": {"logradouro": "Av. B", "numero": "200", "bairro": "Centro", "codigo_municipio": "3304557", "municipio": "Rio de Janeiro", "uf": "RJ"}},
  "valores":  {"total": 1500.00, "componentes": [{"nome": "FRETE PESO", "valor": 1400.00}, {"nome": "PEDAGIO", "valor": 100.00}]},
  "impostos": {"icms": {"cst": "00", "base": 1500.00, "aliquota": 12, "valor": 180.00}},
  "carga":    {"valor": 150000.00, "produto": "Equipamentos eletronicos", "medidas": [{"unidade": "01", "medida": "PESO BRUTO", "quantidade": 1250.5}]},
  "documentos": {"chaves_nfe": ["35260998765432000100550010000001231000001236"]}
}

Resposta 202 com situacao: na_fila; ao autorizar, chave_acesso e links (XML e DACTE). O que faltar volta em 422 dados_incompletos com a lista campos em português, antes de gastar número.

ICMS: cst 00, 20, 40/41/51, 60 ou 90; simples_nacional: true para empresa do Simples (automático quando o CRT da empresa é 1); outra_uf: true quando o imposto é devido à UF de término. Autorizador: escolhido pela UF da empresa (SEFAZ própria em MT, MS, MG, PR e SP; SVRS e SVSP para as demais).

MDMDF-e: manifesto da viagem pela API

Fluxo: cadastre a frota uma vez (PUT /v1/veiculos, PUT /v1/condutores) → POST /v1/mdfe com a viagem, o veículo, os condutores e as chaves dos CT-e/NF-e por município de descarga → GET /v1/mdfe/{id} até emitida → no destino, POST /v1/mdfe/{id}/encerrar. Condutor a mais no caminho: POST /v1/mdfe/{id}/condutores. Cancelamento: POST /v1/notas/{id}/cancelar (só até o encerramento, dentro do prazo da SEFAZ).

Pré-requisitos (uma vez por empresa)

Nos links da resposta, o PDF do MDF-e vem como damdfe (e também pdf).

Pedido mínimo

POST /v1/mdfe
{
  "referencia_externa": "VIAGEM-2026-000045",
  "viagem": {"uf_inicio": "SP", "uf_fim": "RJ", "municipios_carregamento": [{"codigo": "3550308", "nome": "Sao Paulo"}]},
  "rodoviario": {
    "ciots": [{"codigo": "123456789012", "cpf_cnpj": "12345678000195"}],
    "tracao": {"placa": "ABC1D23", "tara_kg": 8000, "capacidade_kg": 20000, "tipo_rodado": "03", "tipo_carroceria": "02", "uf": "SP",
               "condutores": [{"nome": "JOAO MOTORISTA", "cpf": "52998224725"}]}
  },
  "descargas": [{"municipio_descarga": {"codigo": "3304557", "nome": "Rio de Janeiro"},
                 "chaves_cte": ["35260912345678000195570010000000771000007719"]}],
  "produto": {"tipo_carga": "05", "descricao": "Equipamentos eletronicos"},
  "totais": {"valor_carga": 150000.00, "unidade": "01", "peso_carga": 12500.5}
}

Emitente: transportadora (tipo_emitente 1, exige RNTRC) ou carga própria (2). Padrão no cadastro da empresa. Pagamento do frete (rodoviario.pagamentos) é obrigatório quando você contrata autônomo (TAC). CIOT vai em rodoviario.ciots. São duas exigências que se somam. ANTT: obrigatório desde 24/05/2026 em toda contratação de TAC (Resolução 6.078/2026) e, desde 18/09/2026, em toda operação remunerada de transporte rodoviário de cargas (Resolução 6.090/2026); multa de R$ 10.500. SEFAZ: a NT 2026.001 do MDF-e rejeita com 684 o transporte remunerado de carga de terceiros sem o grupo — em homologação desde 21/09/2026 e em produção a partir de 23/11/2026. Com tipo_emitente 1 ou 3, o pré-voo já barra o pedido sem CIOT quando a regra vale para o ambiente. Autorizador: SVRS para o país inteiro.

Encerrar

POST /v1/mdfe/{id}/encerrar
{"data": "2026-09-25", "uf": "RJ", "codigo_municipio": "3304557"}   # tudo opcional: padrão = fim da viagem

CICIOT: em breve nesta API

O Código Identificador da Operação de Transporte é gerado por instituição de pagamento credenciada pela ANTT, não pela SEFAZ. A rota POST /v1/operacoes está reservada e responde 501 até a integração com a PSP entrar. Até lá, obtenha o CIOT na sua PSP e informe o número em rodoviario.ciots do MDF-e.

✓Campos da emissão

Situações da nota

!Erros: um formato, um catálogo

Todo erro da API vem no mesmo envelope. O erro é um código estável — é por ele que o seu sistema decide o que fazer; a mensagem é para gente ler e pode mudar de redação. campos aponta o que corrigir no corpo; detalhes traz contexto (o id de um rascunho, o código do órgão…).

{
  "erro":     "campos_invalidos",
  "mensagem": "Campos obrigatórios ausentes ou inválidos.",
  "campos":   ["tomador.cpf_cnpj", "valor"],
  "detalhes": {"nota_id": "f2b4…"}          // opcional
}

Status HTTP por família: 400 requisição mal formada · 401 credencial · 403 licença · 404 não existe ou não é seu (indistinguíveis de propósito) · 422 a requisição é válida, mas o cadastro ou a regra fiscal não deixa · 429 limite · 500 falha nossa (tente de novo) · 501 ainda não existe. Um código tem sempre o mesmo status.

Casos que não são erro: HTTP 200 com meta.repetida (mesma referencia_externa, devolve a nota original); nota rejeitada pelo órgão vem como situação da nota, com o objeto rejeicao explicado em português — corrija e emita de novo. O catálogo em JSON: /docs/erros.json.