Documentação NotaAPI v2

API REST para emissão de documentos fiscais eletrônicos (NFe, NFCe, NFSe, NFCom). Este guia vai te ajudar a integrar do zero - mesmo que seja sua primeira vez com nota fiscal.

🚀

Primeiros Passos

Emita sua primeira nota em 10 minutos

📖

Glossário

Entenda os termos fiscais essenciais

🏢

Cadastrar Empresa

Primeiro passo: cadastre o emissor

URLs Base

🧪 Homologação (testes)

https://homologacao.notaapi.com.br/v2

🚀 Produção

https://api.notaapi.com.br/v2

Documentos Suportados

Tipo	Modelo	Descrição	Uso
`nfe`	55	Nota Fiscal Eletrônica	Venda de produtos (mercadorias)
`nfce`	65	Nota Fiscal de Consumidor	Varejo - vendas para consumidor final
`nfse`	-	Nota Fiscal de Serviço	Prestação de serviços
`nfcom`	62	Nota Fiscal de Comunicação	Telecomunicações (telefonia, internet, TV)

⏱️ Tempo de Resposta

Performance esperada

Emissão NFe/NFCe: 2-5 segundos (SEFAZ) · Emissão NFSe: 3-15 segundos (depende da prefeitura) · Consultas: < 1 segundo

🔄 Ciclo de Vida da Nota Fiscal

Entenda o fluxo completo de uma nota fiscal eletrônica:

Criação

POST /nfe

→

Envio SEFAZ

Automático

→

Autorizada

status = 2

→

Eventos

CC-e / Cancelamento

Estados Possíveis

Status	Código	Descrição	Ações Permitidas
Novo	0	Nota criada, aguardando envio	Aguardar processamento
Enviado	1	Enviada para SEFAZ, aguardando resposta	Aguardar processamento
Autorizado	2	Nota aprovada pela SEFAZ	Cancelar, CC-e, Download PDF/XML
Cancelado	3	Nota cancelada	Apenas consulta
Inutilizado	4	Numeração inutilizada	Apenas consulta
Erro	5	Rejeitada pela SEFAZ	Corrigir e reenviar (nova referência)

Eventos Após Autorização

Evento	Quando Usar	Prazo
Cancelamento	Desistência da operação, erro grave	Varia por UF (24h a 168h)
Carta de Correção (CC-e)	Corrigir dados secundários (não altera valores)	Até 30 dias
Manifestação	Confirmar/desconhecer recebimento de NFe de terceiros	Sem prazo definido

⚠️ Importante

Após o prazo de cancelamento, a única forma de "anular" uma nota é emitindo uma nota de devolução ou nota de ajuste.

✅ Pré-requisitos

Antes de começar a integração, verifique se você tem tudo pronto:

Para NFe e NFCe (Produtos)

☐

CNPJ Ativo

Empresa com situação cadastral regular na Receita Federal

☐

Inscrição Estadual (IE)

Obrigatória para emitir NFe/NFCe. Obtida na SEFAZ do estado

☐

Certificado Digital A1 (e-CNPJ)

Arquivo .pfx válido (não pode ser A3). Validade de 1 ano. Compre em certificadoras como Serasa, Certisign, etc.

☐

Credenciamento na SEFAZ

Solicitar habilitação para emissão de NFe/NFCe no site da SEFAZ do seu estado

☐

CSC Token (apenas NFCe)

Código de Segurança do Contribuinte - obtido no portal da SEFAZ

Para NFSe (Serviços)

☐

CNPJ Ativo

Empresa com situação cadastral regular

☐

Inscrição Municipal

Cadastro na prefeitura do município onde a empresa está estabelecida

☐

Credenciais da Prefeitura (se aplicável)

Algumas prefeituras exigem usuário/senha ou token específico para integração

☐

Código de Serviço Municipal

Consulte na prefeitura qual código corresponde ao seu tipo de serviço

Dados Fiscais Necessários

Dado	Onde Conseguir	Exemplo
NCM dos produtos	Tabela TIPI / Contador	61091000 (camisetas)
CFOP das operações	Tabela CFOP / Contador	5102 (venda interna)
CST/CSOSN	Contador	102 (SN sem crédito)
Código IBGE da cidade	ibge.gov.br	3550308 (São Paulo)
Alíquota de ISS	Prefeitura	2% a 5%

📊 Fluxo de Integração

Visão geral do processo de emissão de documentos fiscais:

Cadastrar Empresa

POST /empresa

Dados cadastrais, endereço, regime tributário

→

Upload Certificado

PUT .../certificado

Arquivo .pfx em base64 + senha

→

Emitir Nota

POST /nfe

Envia dados da venda/serviço

→

Consultar Status

GET /nfe/{ref}

Verifica autorização

→

✓

Download

XML + PDF prontos

Diagrama de Estados da Nota

0 Novo

→

1 Enviado

→

2 ✅ Autorizado

5 ❌ Erro

→

3 Cancelado

💡 Dica: Use Webhooks

Configure webhooks para ser notificado automaticamente quando o status mudar, ao invés de fazer polling.

Autenticação

A API usa HTTP Basic Authentication com sua API Key:

Campo	Valor
Usuário (username)	Sua `api_key`
Senha (password)	vazio

              Header
            
              Authorization: Basic {base64(api_key:)}

Exemplo cURL:

              curl -X GET https://api.notaapi.com.br/v2/empresa/{id} \
  -u "sua_api_key:" \
  -H "Content-Type: application/json"
            

💡 Nota sobre o formato

O : após a api_key é obrigatório (indica senha vazia). No cURL, -u "api_key:" já faz a codificação Base64 automaticamente.

⚠️ Mantenha sua API Key segura

Nunca exponha sua api_key no frontend ou em repositórios públicos. Use variáveis de ambiente no backend.

Header companyId

Para endpoints de documentos fiscais (NFe, NFCe, NFSe, NFCom), você precisa enviar o ID da empresa emissora no header:

companyId: uuid-da-empresa-cadastrada

Ambientes

Use o parâmetro ambiente no corpo das requisições:

Valor	URL Base	Validade Fiscal	Uso
`"Homologacao"`	homologacao.notaapi.com.br/v2	❌ Não	Testes e desenvolvimento
`"Producao"`	api.notaapi.com.br/v2	✅ Sim	Operação real

🚨 Cuidado com Produção

Notas emitidas em produção são reais e geram obrigações fiscais. Teste exaustivamente em homologação primeiro!

🔐 Certificado Digital

O certificado digital é a identidade eletrônica da empresa e é obrigatório para emitir NFe, NFCe e NFCom.

Tipo Suportado: A1

Característica	Certificado A1
Formato	Arquivo .pfx ou .p12
Armazenamento	Em arquivo (software)
Validade	1 ano
Uso na API	Enviado em base64
Vantagem	Pode ser usado em servidores/nuvem

ℹ️ Certificado A3 não suportado

A NotaAPI trabalha apenas com certificados A1 (arquivo). Certificados A3 (token/cartão) não são compatíveis com APIs REST.

Como Obter

Escolha uma Autoridade Certificadora (AC): Serasa, Certisign, Valid, Safeweb, etc.
Selecione o tipo e-CNPJ A1 (para empresas) ou e-CPF A1 (para MEI/pessoa física)
Faça a validação presencial ou por videoconferência
Baixe o arquivo .pfx e guarde a senha em local seguro

Enviar para a API

Use o endpoint PUT /empresa/{id}/certificado:

{
  "pfxCertificado": "MIIKYQIBAzCCCicGCSqGSIb3DQE... (base64 do arquivo .pfx)",
  "pfxSenha": "sua_senha_do_certificado"
}
            

Converter .pfx para base64:

# Linux/Mac
base64 -i certificado.pfx -o certificado_base64.txt

Validade e Renovação

⚠️ Fique atento à validade

O certificado A1 vence em 1 ano. Configure um alerta para renovar com antecedência. Após o vencimento, não será possível emitir notas!

Para verificar a validade, consulte a empresa:

// Na resposta de GET /empresa/{id}, verifique:
{
  "certVencimento": "2025-12-15T23:59:59Z",
  "certRazaoSocial": "EMPRESA EXEMPLO LTDA",
  "certCnpj": "12345678000199"
}
            

Primeiros Passos

Siga estes passos para emitir sua primeira nota fiscal:

Cadastre a empresa emissora

POST /empresa - Cadastre os dados da empresa (CNPJ, endereço, regime tributário)

Faça upload do certificado digital

PUT /empresa/{id}/certificado - Envie o arquivo .pfx (A1) em base64 e a senha

Emita a nota fiscal

POST /nfe, POST /nfce ou POST /nfse - Envie os dados da venda/serviço

Consulte o resultado

GET /{tipo}/{referencia} - Obtenha status, XML e PDF da nota autorizada

Glossário de Termos Fiscais

Termos essenciais que você vai encontrar durante a integração:

SEFAZ

Secretaria da Fazenda estadual. Autoriza NFe e NFCe. Cada estado tem sua SEFAZ.

XML

Arquivo oficial da nota fiscal com validade jurídica. Deve ser guardado por 5 anos.

DANFE

Documento Auxiliar - versão impressa/PDF. Não tem validade fiscal sozinho.

Chave de Acesso

Código de 44 dígitos que identifica unicamente cada nota fiscal.

NCM

Nomenclatura Comum do Mercosul - código de 8 dígitos que classifica o produto.

CFOP

Código Fiscal de Operações - indica o tipo de operação (venda, devolução, etc).

CST

Código de Situação Tributária - define como o imposto é calculado.

Certificado A1

Arquivo .pfx que funciona como "assinatura digital" da empresa. Obrigatório para NFe/NFCe.

referencia

Seu identificador único para a nota (ex: número do pedido). Usado para consultar depois.

📋 Exemplos por Caso de Uso

Payloads prontos para as situações mais comuns:

1. Venda Simples para Consumidor Final (NFe)

Venda de produto para pessoa física, sem frete.

{
  "referencia": "PEDIDO-001",
  "ambiente": "Homologacao",
  "tipoOperacao": "Saida",
  "naturezaOperacao": "Venda de mercadoria",
  "finalidade": "Normal",
  "consumidorFinal": true,
  "enviarPorEmail": true,
  "pedido": {
    "presencaConsumidor": "OperacaoPelaInternet",
    "pagamento": {
      "tipo": "PagamentoAVista",
      "formas": [{ "tipo": "PagamentoInstantaneoPix", "valor": 150.00 }]
    }
  },
  "cliente": {
    "tipoPessoa": "F",
    "cpfCnpj": "12345678900",
    "nome": "João da Silva",
    "email": "[email protected]",
    "indicadorContribuinteICMS": "ContribuinteNaoContribuinte",
    "endereco": {
      "logradouro": "Rua das Flores", "numero": "100",
      "bairro": "Centro", "cidade": "São Paulo",
      "uf": "SP", "cep": "01001000"
    }
  },
  "itens": [{
    "cfop": "5102",
    "codigo": "PROD001",
    "descricao": "Camiseta 100% Algodão Tamanho M",
    "ncm": "61091000",
    "ean": "SEM GTIN",
    "quantidade": 2,
    "unidadeMedida": "UN",
    "valorUnitario": 75.00,
    "impostos": {
      "icms": { "origem": 0, "situacaoTributaria": "102" },
      "pis": { "situacaoTributaria": "07" },
      "cofins": { "situacaoTributaria": "07" }
    }
  }]
}

curl -X POST https://homologacao.notaapi.com.br/v2/nfe \
  -u "sua_api_key:" \
  -H "Content-Type: application/json" \
  -H "companyId: seu-company-id-uuid" \
  -d '{ ... payload acima ... }'

const response = await fetch('https://homologacao.notaapi.com.br/v2/nfe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('sua_api_key:'),
    'companyId': 'seu-company-id-uuid'
  },
  body: JSON.stringify(payload)
});
const data = await response.json();
console.log(data.id); // ID da nota criada

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    'https://homologacao.notaapi.com.br/v2/nfe',
    auth=HTTPBasicAuth('sua_api_key', ''),
    headers={'companyId': 'seu-company-id-uuid'},
    json=payload
)
print(response.json())

<?php
$ch = curl_init('https://homologacao.notaapi.com.br/v2/nfe');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => 'sua_api_key:',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'companyId: seu-company-id-uuid'
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);
$response = curl_exec($ch);
echo $response;

2. Venda para Revenda (PJ Contribuinte)

Venda para pessoa jurídica que vai revender o produto. CFOP diferente!

{
  // ... dados básicos iguais ...
  "consumidorFinal": false,  // PJ vai revender
  "cliente": {
    "tipoPessoa": "J",
    "cpfCnpj": "12345678000199",
    "inscricaoEstadual": "123456789",  // Obrigatório para contribuinte
    "indicadorContribuinteICMS": "ContribuinteICMS",
    // ...
  },
  "itens": [{
    "cfop": "5102",  // Mesmo estado
    // ou "6102" se for interestadual
    // ...
  }]
}
            

3. Venda com Frete

Venda com transporte por conta do remetente.

{
  // ... dados básicos ...
  "transporte": {
    "frete": {
      "modalidade": "PorContaDoRemetente"  // CIF
    },
    "transportadora": {
      "usarDadosEmitente": false,
      "cpfCnpj": "98765432000199",
      "tipoPessoa": "J",
      "nome": "Transportadora XYZ",
      "inscricaoEstadual": "987654321",
      "enderecoCompleto": "Rua do Frete, 500",
      "cidade": "São Paulo",
      "uf": "SP"
    },
    "volume": {
      "quantidade": 1,
      "especie": "CAIXA",
      "pesoLiquido": 0.5,
      "pesoBruto": 0.6
    }
  },
  "itens": [{
    // ... dados do item ...
    "frete": 25.00  // Valor do frete rateado no item
  }]
}
            

4. Devolução de Mercadoria

Cliente devolvendo produto. Precisa referenciar a NFe original.

{
  "referencia": "DEV-001",
  "tipoOperacao": "Entrada",  // Entrada na sua empresa
  "finalidade": "DevolucaoMercadoria",
  "naturezaOperacao": "Devolução de mercadoria",
  "nfeReferenciada": [{
    "chaveAcesso": "35231112345678000199550010000012341123456789"  // NFe original
  }],
  "itens": [{
    "cfop": "1202",  // Devolução de venda
    // ... mesmo item da nota original ...
    "impostosDevolucao": {
      "percentualMercadoriaDevolvida": 100,
      "ipi": { "valorIpiDevolvido": 0 }
    }
  }]
}
            

5. Prestação de Serviço (NFSe)

Emissão de nota de serviço para empresa de software.

{
  "referencia": "SERV-001",
  "ambiente": "Homologacao",
  "dataCompetencia": "2025-12-01",
  "naturezaOperacao": "1",
  "valorTotal": 5000.00,
  "enviarPorEmail": true,
  "cliente": {
    "tipoPessoa": "J",
    "cpfCnpj": "12345678000199",
    "nome": "Empresa Cliente LTDA",
    "email": "[email protected]",
    "endereco": {
      "logradouro": "Av Paulista", "numero": "1000",
      "bairro": "Bela Vista", "cidade": "São Paulo",
      "uf": "SP", "cep": "01310100"
    }
  },
  "servico": {
    "codigoServicoMunicipio": "01.02",
    "itemListaServicoLC116": "1.02",
    "descricao": "Desenvolvimento de software sob encomenda - Projeto XYZ - Competência Dezembro/2025",
    "aliquotaIss": 2.00,
    "valorIss": 100.00,
    "issRetidoFonte": false
  }
}
            

📑 Tabela de CFOPs Comuns

CFOPs mais utilizados por tipo de operação:

Vendas (Saídas)

CFOP	Operação	Quando Usar
`5102`	Venda mercadoria (interna)	Venda dentro do mesmo estado
`6102`	Venda mercadoria (interestadual)	Venda para outro estado
`5405`	Venda merc. ST (interna)	Produto com substituição tributária, mesmo estado
`6404`	Venda merc. ST (interestadual)	Produto com ST para outro estado
`5949`	Outra saída não especificada	Outras saídas internas
`6949`	Outra saída não especificada	Outras saídas interestaduais

Devoluções (Entradas)

CFOP	Operação	Quando Usar
`1202`	Devolução de venda (interna)	Cliente do mesmo estado devolvendo
`2202`	Devolução de venda (interestadual)	Cliente de outro estado devolvendo
`1411`	Devolução merc. ST (interna)	Devolução de produto com ST

Compras (Entradas)

CFOP	Operação	Quando Usar
`1102`	Compra p/ comercialização (interna)	Comprando para revender, mesmo estado
`2102`	Compra p/ comercialização (interestadual)	Comprando de outro estado
`1556`	Compra p/ ativo imobilizado	Comprando equipamentos/máquinas

💡 Regra geral

5xxx = operação interna (mesmo estado) · 6xxx = interestadual · 1xxx/2xxx = entradas · 5xxx/6xxx = saídas

📊 Tabela de CSTs por Regime

Simples Nacional (CSOSN)

Use estes códigos se a empresa é optante pelo Simples Nacional:

CSOSN	Descrição	Quando Usar
`101`	Tributada com permissão de crédito	Venda para PJ contribuinte que pode aproveitar crédito
`102`	Tributada sem permissão de crédito	Venda para consumidor final (mais comum)
`103`	Isenção de ICMS no SN	Produtos isentos
`202`	Tributada com ST sem crédito	Produtos com substituição tributária
`300`	Imune	Livros, jornais, papel
`400`	Não tributada	Operação não tributada
`500`	ICMS cobrado por ST	Produto já teve ICMS pago por ST
`900`	Outros	Situações não enquadradas acima

Regime Normal (CST)

Use estes códigos se a empresa é Lucro Presumido ou Real:

CST	Descrição	Quando Usar
`00`	Tributada integralmente	Produto tributado normalmente
`10`	Tributada com ST	Produto com substituição tributária
`20`	Com redução de base	Produtos com benefício de redução
`40`	Isenta	Operação isenta
`41`	Não tributada	Não incidência
`60`	ICMS cobrado por ST	Produto já teve ICMS pago por ST
`90`	Outras	Situações especiais

PIS/COFINS (CST)

CST	Descrição	Regime
`01`	Operação tributável - alíquota básica	Lucro Real/Presumido
`04`	Operação tributável - monofásica	Combustíveis, bebidas, etc.
`06`	Operação tributável - alíquota zero	Produtos com alíquota zero
`07`	Operação isenta	Simples Nacional
`08`	Operação sem incidência	Exportação
`49`	Outras operações de saída	Regime cumulativo
`99`	Outras operações	Situações especiais

✅ Validação de Campos

Formatos esperados para evitar erros de validação:

Campo	Formato	Exemplo	Dica
`cpfCnpj`	Somente números	12345678000199	Sem pontos, barras ou traços
`cep`	8 dígitos	01310100	Sem hífen
`ncm`	8 dígitos	61091000	Consulte tabela TIPI
`cfop`	4 dígitos	5102	Primeiro dígito indica tipo
`codigoIBGE`	7 dígitos	3550308	Código do município no IBGE
`uf`	2 letras maiúsculas	SP	Sigla do estado
`telefone`	10-11 dígitos	11999999999	DDD + número, sem formatação
`email`	Email válido	[email protected]	Será usado para enviar XML/PDF
`referencia`	String única	PEDIDO-001	Seu ID interno - não pode repetir
`ean`	8, 12, 13 ou 14 dígitos	7891234567890	Use "SEM GTIN" se não tiver
`valorUnitario`	Decimal (até 10 casas)	75.50	Ponto como separador decimal
`quantidade`	Decimal (até 4 casas)	2.5	Pode ser fracionado
`aliquota`	Decimal (percentual)	18.00	Em percentual, não decimal
`dataCompetencia`	YYYY-MM-DD	2025-12-01	Formato ISO
`chaveAcesso`	44 dígitos	35231112345...	Retornada após autorização

⚠️ Erros mais comuns de validação

1. CNPJ com formatação (pontos/barras) · 2. NCM com menos de 8 dígitos · 3. Código IBGE errado · 4. EAN inválido (use "SEM GTIN" se não tiver)

Cadastrar Empresa

POST /empresa

Cadastra uma nova empresa emissora de documentos fiscais. Este é o primeiro passo para começar a emitir notas.

Campos principais:

Campo	Tipo	Descrição
`razaoSocial`	string obrigatório	Razão social da empresa
`cpfCnpj`	string obrigatório	CNPJ ou CPF (somente números)
`inscricaoEstadual`	string	Inscrição Estadual (para NFe/NFCe)
`inscricaoMunicipal`	string	Inscrição Municipal (para NFSe)
`endereco`	string obrigatório	Logradouro
`numero`	string obrigatório	Número do endereço
`bairro`	string obrigatório	Bairro
`cidade`	string obrigatório	Nome da cidade
`codigoIBGE`	string obrigatório	Código IBGE da cidade (7 dígitos)
`uf`	string obrigatório	UF (ex: SP, RJ, PR)
`cep`	string obrigatório	CEP (somente números)
`telefone`	string obrigatório	Telefone
`email`	string obrigatório	E-mail
`tipoContribuinte`	enum obrigatório	Regime tributário (veja enum abaixo)
`nfeHabilitada`	boolean	Habilitar emissão de NFe
`nfeHomHabilitada`	boolean	Habilitar NFe em homologação
`nfceHabilitada`	boolean	Habilitar emissão de NFCe
`nfceHomHabilitada`	boolean	Habilitar NFCe em homologação
`nfceIdToken`	string	ID do token CSC (produção)
`nfceToken`	string	Token CSC (produção)
`nfceHomIdToken`	string	ID do token CSC (homologação)
`nfceHomToken`	string	Token CSC (homologação)
`nfseHabilitada`	boolean	Habilitar emissão de NFSe
`nfseHomHabilitada`	boolean	Habilitar NFSe em homologação
`nfseRegimeEspecialTributacao`	integer	Regime especial de tributação NFSe (0-14)
`nfseWsUser`	string	Usuário WebService prefeitura
`nfseWssenha`	string	Senha WebService prefeitura
`nfcomHabilitada`	boolean	Habilitar emissão de NFCom
`nfcomHomHabilitada`	boolean	Habilitar NFCom em homologação
`nfcomSerie`	string	Série para NFCom
`pfxCertificado`	string (base64)	Certificado A1 em base64
`pfxSenha`	string	Senha do certificado

tipoContribuinte (enum):

simples_nacional simples_excesso_receita regime_normal mei

Exemplo:

curl -X POST https://api.notaapi.com.br/v2/empresa \
  -u "sua_api_key:" \
  -H "Content-Type: application/json" \
  -d '{
    "razaoSocial": "Minha Empresa LTDA",
    "cpfCnpj": "12345678000199",
    "inscricaoEstadual": "123456789",
    "endereco": "Rua Exemplo",
    "numero": "100",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "codigoIBGE": "3550308",
    "uf": "SP",
    "cep": "01001000",
    "telefone": "11999999999",
    "email": "[email protected]",
    "tipoContribuinte": "simples_nacional",
    "nfeHabilitada": true,
    "nfeHomHabilitada": true
  }'

const empresa = {
  razaoSocial: 'Minha Empresa LTDA',
  cpfCnpj: '12345678000199',
  inscricaoEstadual: '123456789',
  endereco: 'Rua Exemplo',
  numero: '100',
  bairro: 'Centro',
  cidade: 'São Paulo',
  codigoIBGE: '3550308',
  uf: 'SP',
  cep: '01001000',
  telefone: '11999999999',
  email: '[email protected]',
  tipoContribuinte: 'simples_nacional',
  nfeHabilitada: true,
  nfeHomHabilitada: true
};

const response = await fetch('https://api.notaapi.com.br/v2/empresa', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from('sua_api_key:').toString('base64')
  },
  body: JSON.stringify(empresa)
});

const data = await response.json();
console.log('Company ID:', data.id); // Guarde esse ID!

import requests
from requests.auth import HTTPBasicAuth

empresa = {
    "razaoSocial": "Minha Empresa LTDA",
    "cpfCnpj": "12345678000199",
    "inscricaoEstadual": "123456789",
    "endereco": "Rua Exemplo",
    "numero": "100",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "codigoIBGE": "3550308",
    "uf": "SP",
    "cep": "01001000",
    "telefone": "11999999999",
    "email": "[email protected]",
    "tipoContribuinte": "simples_nacional",
    "nfeHabilitada": True,
    "nfeHomHabilitada": True
}

response = requests.post(
    'https://api.notaapi.com.br/v2/empresa',
    auth=HTTPBasicAuth('sua_api_key', ''),
    json=empresa
)

company_id = response.json()['id']
print(f'Company ID: {company_id}')  # Guarde esse ID!

<?php
$empresa = [
    'razaoSocial' => 'Minha Empresa LTDA',
    'cpfCnpj' => '12345678000199',
    'inscricaoEstadual' => '123456789',
    'endereco' => 'Rua Exemplo',
    'numero' => '100',
    'bairro' => 'Centro',
    'cidade' => 'São Paulo',
    'codigoIBGE' => '3550308',
    'uf' => 'SP',
    'cep' => '01001000',
    'telefone' => '11999999999',
    'email' => '[email protected]',
    'tipoContribuinte' => 'simples_nacional',
    'nfeHabilitada' => true,
    'nfeHomHabilitada' => true
];

$ch = curl_init('https://api.notaapi.com.br/v2/empresa');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => 'sua_api_key:',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($empresa)
]);

$response = json_decode(curl_exec($ch), true);
echo 'Company ID: ' . $response['id']; // Guarde esse ID!

Resposta (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
            

ℹ️ Guarde o ID

O id retornado é o companyId que você usará em todas as requisições de documentos fiscais.

Consultar Empresa

GET /empresa/{id}

Consulta os dados de uma empresa cadastrada pelo ID.

GET /empresa/doc/{cpfCnpj}

Consulta empresa pelo CPF ou CNPJ.

Atualizar Empresa

PUT /empresa/{id}

Atualiza os dados cadastrais de uma empresa.

Atualizar Certificado

PUT /empresa/{id}/certificado

Envia ou atualiza o certificado digital A1 da empresa.

Campo	Tipo	Descrição
`pfxCertificado`	string (base64) obrigatório	Arquivo .pfx convertido para base64
`pfxSenha`	string obrigatório	Senha do certificado

curl -X PUT https://api.notaapi.com.br/v2/empresa/{id}/certificado \
  -u "sua_api_key:" \
  -H "Content-Type: application/json" \
  -d '{
    "pfxCertificado": "MIIKYQIBAzCCCicGC...",
    "pfxSenha": "senha_do_certificado"
  }'
            

⚠️ Apenas certificado A1

Certificados A3 (cartão/token físico) não são suportados por APIs em nuvem. Use somente e-CNPJ modelo A1.

Atualizar Logo

PUT /empresa/{id}/logo

Atualiza o logo da empresa (aparece no DANFE/PDF).

Campo	Tipo	Descrição
`logo`	string (base64) obrigatório	Imagem em base64

Emitir NFe

POST /nfe

Emite uma Nota Fiscal Eletrônica (modelo 55) para venda de produtos.

Headers obrigatórios:

Header	Descrição
`companyId`	UUID da empresa emissora
`Content-Type`	application/json

Campos principais do corpo:

Campo	Tipo	Descrição
`referencia`	string obrigatório	Seu ID único (ex: número do pedido)
`ambiente`	enum obrigatório	`Homologacao` ou `Producao`
`numero`	integer obrigatório	Número da nota fiscal
`serie`	string obrigatório	Série da nota fiscal (ex: "1")
`tipoOperacao`	enum obrigatório	`Entrada` ou `Saida`
`naturezaOperacao`	string obrigatório	Ex: "Venda de mercadoria"
`finalidade`	enum obrigatório	`Normal`, `Complementar`, `Ajuste`, `DevolucaoMercadoria`
`consumidorFinal`	boolean obrigatório	Se é venda para consumidor final
`cliente`	object obrigatório	Dados do destinatário
`itens`	array obrigatório	Lista de produtos
`pedido`	object	Dados de pagamento
`indicadorPresencaConsumidor`	enum	Indicador de presença do consumidor (ver enum abaixo)
`cobranca`	object	Fatura e parcelas (vendas a prazo)
`transporte`	object	Dados de frete/transporte
`informacoesAdicionais`	string	Informações complementares (aparece no DANFE)
`informacoesAdicionaisFisco`	string	Informações para o fisco
`nfeReferenciada`	array	Notas referenciadas (para devolução)
`enviarPorEmail`	boolean	Enviar XML/PDF por email ao cliente
`dadosAdicionaisEmail`	object	Emails adicionais

Objeto pedido:

Campo	Tipo	Descrição
`presencaConsumidor`	enum	Indicador de presença (ver enum abaixo)
`pagamento`	object	Dados de pagamento

Objeto pedido.pagamento:

Campo	Tipo	Descrição
`tipo`	enum	`PagamentoAVista`, `PagamentoAPrazo`, `PagamentoOutros`
`formas`	array	Lista de formas de pagamento

Objeto pedido.pagamento.formas[]:

Campo	Tipo	Descrição
`tipo`	enum	Forma de pagamento (ver enum abaixo)
`valor`	number	Valor pago nesta forma
`descricao`	string	Descrição adicional

Enum tipo_forma_pagamento:

Valor	Descrição
`Dinheiro`	Dinheiro
`CartaoDeCredito`	Cartão de crédito
`CartaoDeDebito`	Cartão de débito
`PagamentoInstantaneoPix`	PIX
`BoletoBancario`	Boleto bancário
`DepositoBancario`	Depósito/Transferência
`Cheque`	Cheque
`CreditoLoja`	Crédito da loja
`ValeAlimentacao`	Vale alimentação
`ValeRefeicao`	Vale refeição
`ValePresente`	Vale presente
`ValeCombustivel`	Vale combustível
`SemPagamento`	Sem pagamento
`Outros`	Outros

Objeto dadosAdicionaisEmail:

Campo	Tipo	Descrição
`outrosDestinatarios`	array[string]	Lista de emails adicionais para envio

Objeto cliente:

Campo	Tipo	Descrição
`tipoPessoa`	enum obrigatório	`F` (física) ou `J` (jurídica)
`cpfCnpj`	string obrigatório	CPF ou CNPJ (somente números)
`nome`	string obrigatório	Nome/Razão social
`indicadorContribuinteICMS`	enum obrigatório	`ContribuinteICMS`, `ContribuinteIsento`, `ContribuinteNaoContribuinte`
`endereco`	object obrigatório	Endereço completo
`email`	string	E-mail do cliente
`telefone`	string	Telefone
`inscricaoEstadual`	string	IE (obrigatório se ContribuinteICMS)
`inscricaoMunicipal`	string	Inscrição municipal

Objeto endereco:

Campo	Tipo	Descrição
`logradouro`	string obrigatório	Rua/Avenida
`numero`	string obrigatório	Número
`bairro`	string obrigatório	Bairro
`cidade`	string obrigatório	Nome da cidade
`uf`	string obrigatório	Sigla do estado (2 letras)
`cep`	string obrigatório	CEP (8 dígitos, sem traço)
`complemento`	string	Complemento
`codIbge`	string	Código IBGE da cidade (7 dígitos)
`pais`	string	Código do país (default: "BR")

Objeto item (itens[]):

Campo	Tipo	Descrição
`cfop`	string obrigatório	Código CFOP (ex: "5102")
`codigo`	string obrigatório	Código interno do produto
`descricao`	string obrigatório	Descrição do produto
`ncm`	string obrigatório	Código NCM (8 dígitos)
`ean`	string obrigatório	Código de barras GTIN ou "SEM GTIN"
`quantidade`	number obrigatório	Quantidade
`unidadeMedida`	string obrigatório	Unidade (UN, KG, M, etc.)
`valorUnitario`	number obrigatório	Valor unitário
`impostos`	object obrigatório	ICMS, PIS, COFINS, IPI
`eanTributavel`	string	EAN da unidade tributável
`cest`	string	Código CEST (7 dígitos, para ST)
`extipi`	string	Código EX TIPI
`descontos`	number	Valor do desconto
`frete`	number	Valor do frete rateado
`outrasDespesas`	number	Outras despesas acessórias
`codigoBeneficioFiscal`	string	Código de benefício fiscal (cBenef)
`impostosDevolucao`	object	Para notas de devolução
`combustivel`	object	Dados ANP (para combustíveis)

Objeto combustivel (para postos de combustível):

Campo	Tipo	Descrição
`codigoProdutoANP`	string obrigatório	Código do produto ANP (ex: "320102001" para gasolina)
`ufConsumo`	string obrigatório	UF de consumo do combustível
`percentualGasNatural`	number	% de gás natural na mistura
`percentualGasNaturalImportado`	number	% de gás natural importado
`percentualGLPDerivadoPetroleo`	number	% de GLP derivado de petróleo
`valorDePartida`	number	Valor de partida (CIDE)

Objeto impostosDevolucao (para notas de devolução):

Campo	Tipo	Descrição
`percentualMercadoriaDevolvida`	number	% da mercadoria devolvida (default: 100)
`ipi`	object	Dados do IPI devolvido

Objeto impostosDevolucao.ipi:

Campo	Tipo	Descrição
`valorIpiDevolvido`	number	Valor do IPI devolvido

Objeto impostos:

Campo	Tipo	Descrição
`icms`	object	Imposto sobre Circulação de Mercadorias
`pis`	object	PIS
`cofins`	object	COFINS
`ipi`	object	IPI (industrializados)
`percentualAproximadoTributos`	object	Carga tributária aproximada (Lei 12.741)
`ibscbs`	object	IBS/CBS - Reforma Tributária (ver seção abaixo)

Objeto impostos.icms:

Campo	Tipo	Descrição
`origem`	integer	0=Nacional, 1=Estrang.Importação Direta, 2=Estrang.Mercado Interno, etc.
`situacaoTributaria`	string obrigatório	CST (regime normal) ou CSOSN (Simples Nacional)
`baseCalculo`	number	Base de cálculo do ICMS
`aliquota`	number	Alíquota do ICMS (%)
`valor`	number	Valor do ICMS
`modalidadeBaseCalculo`	enum	0=MVA, 1=Pauta, 2=Preço Máx, 3=Valor Operação
`percentualReducaoBaseCalculo`	number	% redução da base de cálculo
`aliquotaCreditoSimplesNacional`	number	Alíquota crédito SN (CSOSN 101, 201)
`valorCreditoSimplesNacional`	number	Valor crédito Simples Nacional

Campos ICMS ST (Substituição Tributária):

Campo	Tipo	Descrição
`modalidadeBaseCalculoST`	integer	0=Preço Máx, 4=MVA, 5=Pauta, 6=Valor Op
`percentualMargemValorAdicionadoST`	number	% MVA do ICMS ST
`percentualReducaoBaseCalculoST`	number	% redução BC do ST
`baseCalculoST`	number	Base de cálculo do ICMS ST
`aliquotaST`	number	Alíquota do ICMS ST
`valorST`	number	Valor do ICMS ST

Campos ICMS Efetivo (para ICMS-ST já recolhido):

Campo	Tipo	Descrição
`baseCalculoEfetiva`	number	Base de cálculo efetiva
`aliquotaEfetiva`	number	Alíquota efetiva (%)
`valorEfetivo`	number	Valor efetivo do ICMS
`valorSubstituto`	number	Valor ICMS substituto

Campos ICMS Diferimento:

Campo	Tipo	Descrição
`percentualDiferimento`	number	% de diferimento
`valorDiferimento`	number	Valor diferido
`naoCalcularDifal`	boolean	Não calcular DIFAL
`naoCalcularFCP`	boolean	Não calcular FCP

Objeto impostos.pis / impostos.cofins:

Campo	Tipo	Descrição
`situacaoTributaria`	string obrigatório	CST do PIS/COFINS (01, 04, 06, 07, 08, 49, 99)
`porAliquota`	object	Cálculo por alíquota

Objeto porAliquota (PIS/COFINS/IPI):

Campo	Tipo	Descrição
`aliquota`	number	Alíquota (%) - quando CST 01 ou 02

Objeto impostos.ipi:

Campo	Tipo	Descrição
`situacaoTributaria`	string obrigatório	CST do IPI (00, 49, 50, 99, etc.)
`porAliquota`	object	Cálculo por alíquota

Objeto impostos.percentualAproximadoTributos (Lei 12.741):

Campo	Tipo	Descrição
`fonte`	string obrigatório	Fonte da informação (ex: "IBPT")
`simplificado`	object	Modo simplificado (percentual único)
`detalhado`	object	Modo detalhado (por esfera)

Objeto simplificado:

Campo	Tipo	Descrição
`percentual`	number	Percentual único de carga tributária

Objeto detalhado:

Campo	Tipo	Descrição
`percentualFederal`	number	% tributos federais
`percentualEstadual`	number	% tributos estaduais
`percentualMunicipal`	number	% tributos municipais

💡 Lei da Transparência Fiscal

A Lei 12.741/2012 obriga a informar ao consumidor o valor aproximado de tributos. Use o modo simplificado ou detalhado. Dados podem ser obtidos no IBPT.

Objeto impostos.ibscbs (Reforma Tributária):

🆕 IBS/CBS - Reforma Tributária

O IBSCBS é o novo grupo de impostos da reforma tributária brasileira, substituindo gradualmente PIS, COFINS e ICMS. Campos opcionais por enquanto.

Campo	Tipo	Descrição
`CST`	string	Código Situação Tributária IBS/CBS
`cClassTrib`	string	Código de classificação tributária
`indDoacao`	integer	Indicador de doação
`gIBSCBS`	object	Grupo de tributação IBS/CBS
`gIBSCBSMono`	object	Grupo monofásico IBS/CBS
`gTransfCred`	object	Transferência de crédito
`gAjusteCompet`	object	Ajuste de competência
`gEstornoCred`	object	Estorno de crédito
`gCredPresOper`	object	Crédito presumido da operação
`gCredPresIBSZFM`	object	Crédito presumido IBS ZFM

CST IBS/CBS (enum):

Código	Descrição
`000`	Tributação normal
`010`	Tributação com alíquota diferenciada
`011`	Tributação com alíquota por item
`200`	Tributação monofásica
`220`	Tributação monofásica com retenção
`221`	Tributação monofásica - combustíveis
`222`	Tributação monofásica - outros
`400`	Não tributada
`410`	Isenta
`510`	Diferimento

Objeto gIBSCBS (tributação regular):

Campo	Tipo	Descrição
`vBC`	number	Valor da base de cálculo
`vIBS`	number	Valor total do IBS
`gIBSUF`	object	IBS estadual
`gIBSMun`	object	IBS municipal
`gCBS`	object	CBS federal
`gTribRegular`	object	Tributação regime regular
`gTribCompraGov`	object	Tributação compras governamentais

Objeto gIBSUF / gIBSMun / gCBS:

Campo	Tipo	Descrição
`pIBSUF` / `pIBSMun` / `pCBS`	number	Alíquota (%)
`vIBSUF` / `vIBSMun` / `vCBS`	number	Valor calculado
`gDif`	object	Diferimento
`gDevTrib`	object	Devolução tributária
`gRed`	object	Redução

Objeto gDif (diferimento):

Campo	Tipo	Descrição
`pDif`	number	Percentual de diferimento
`vDif`	number	Valor diferido

Objeto gDevTrib (devolução tributária):

Campo	Tipo	Descrição
`vDevTrib`	number	Valor da devolução tributária

Objeto gRed (redução):

Campo	Tipo	Descrição
`pRedAliq`	number	Percentual de redução da alíquota
`pAliqEfet`	number	Alíquota efetiva após redução

Objeto gTribRegular (tributação regular):

Campo	Tipo	Descrição
`CSTReg`	string	CST regime regular
`cClassTribReg`	string	Classificação tributária regular
`pAliqEfetRegIBSUF`	number	Alíquota efetiva IBS UF
`vTribRegIBSUF`	number	Valor tributação regular IBS UF
`pAliqEfetRegIBSMun`	number	Alíquota efetiva IBS Municipal
`vTribRegIBSMun`	number	Valor tributação regular IBS Municipal
`pAliqEfetRegCBS`	number	Alíquota efetiva CBS
`vTribRegCBS`	number	Valor tributação regular CBS

Objeto gTribCompraGov (compras governamentais):

Campo	Tipo	Descrição
`pAliqIBSUF`	number	Alíquota IBS UF
`vTribIBSUF`	number	Valor tributação IBS UF
`pAliqIBSMun`	number	Alíquota IBS Municipal
`vTribIBSMun`	number	Valor tributação IBS Municipal
`pAliqCBS`	number	Alíquota CBS
`vTribCBS`	number	Valor tributação CBS

Objeto gIBSCBSMono (monofásico):

Campo	Tipo	Descrição
`gMonoPadrao`	object	Monofásico padrão
`gMonoReten`	object	Monofásico com retenção
`gMonoRet`	object	Monofásico retido anteriormente
`gMonoDif`	object	Monofásico com diferimento
`vTotIBSMonoItem`	number	Total IBS monofásico do item
`vTotCBSMonoItem`	number	Total CBS monofásico do item

Objeto gMonoPadrao (monofásico padrão):

Campo	Tipo	Descrição
`qBCMono`	number	Quantidade base de cálculo
`adRemIBS`	number	Alíquota ad rem IBS
`adRemCBS`	number	Alíquota ad rem CBS
`vIBSMono`	number	Valor IBS monofásico
`vCBSMono`	number	Valor CBS monofásico

Objeto gMonoReten (monofásico com retenção):

Campo	Tipo	Descrição
`qBCMonoReten`	number	Quantidade BC retenção
`adRemIBSReten`	number	Alíquota ad rem IBS retenção
`vIBSMonoReten`	number	Valor IBS retido
`adRemCBSReten`	number	Alíquota ad rem CBS retenção
`vCBSMonoReten`	number	Valor CBS retido

Objeto gMonoRet (monofásico retido anteriormente):

Campo	Tipo	Descrição
`qBCMonoRet`	number	Quantidade BC retido
`adRemIBSRet`	number	Alíquota ad rem IBS retido
`vIBSMonoRet`	number	Valor IBS retido anteriormente
`adRemCBSRet`	number	Alíquota ad rem CBS retido
`vCBSMonoRet`	number	Valor CBS retido anteriormente

Objeto gMonoDif (monofásico com diferimento):

Campo	Tipo	Descrição
`pDifIBS`	number	Percentual diferimento IBS
`vIBSMonoDif`	number	Valor IBS diferido
`pDifCBS`	number	Percentual diferimento CBS
`vCBSMonoDif`	number	Valor CBS diferido

Objeto gTransfCred (transferência de crédito):

Campo	Tipo	Descrição
`vIBS`	number	Valor IBS transferido
`vCBS`	number	Valor CBS transferido

Objeto gAjusteCompet (ajuste de competência):

Campo	Tipo	Descrição
`competApur`	datetime	Competência de apuração
`vIBS`	number	Valor IBS do ajuste
`vCBS`	number	Valor CBS do ajuste

Objeto gEstornoCred (estorno de crédito):

Campo	Tipo	Descrição
`vIBSEstCred`	number	Valor IBS estornado
`vCBSEstCred`	number	Valor CBS estornado

Objeto gCredPresOper (crédito presumido operação):

Campo	Tipo	Descrição
`vBCCredPres`	number	Base de cálculo do crédito presumido
`cCredPres`	string	Código do crédito presumido (01 a 13)
`gIBSCredPres`	object	Crédito presumido IBS
`gCBSCredPres`	object	Crédito presumido CBS

Objeto gIBSCredPres / gCBSCredPres:

Campo	Tipo	Descrição
`pCredPres`	number	Percentual do crédito presumido
`vCredPres`	number	Valor do crédito presumido
`vCredPresCondSus`	number	Valor do crédito presumido condição suspensa

Objeto gCredPresIBSZFM (crédito presumido IBS ZFM):

Campo	Tipo	Descrição
`competApur`	datetime	Competência de apuração
`tpCredPresIBSZFM`	integer	Tipo do crédito presumido IBS ZFM
`vCredPresIBSZFM`	number	Valor do crédito presumido IBS ZFM

Crédito Presumido (cCredPres):

Código	Descrição
`01`	Operação com direito a crédito
`02`	Operação sem direito a crédito
`03`	Aquisição de bem para ativo imobilizado
`04`	Aquisição de serviço de transporte
`05` a `13`	Outros tipos de crédito presumido

Objeto transporte:

Campo	Tipo	Descrição
`frete`	object	Dados do frete
`transportadora`	object	Dados da transportadora
`veiculo`	object	Dados do veículo
`volume`	object	Dados do volume
`enderecoEntrega`	object	Endereço de entrega (se diferente)

Objeto transporte.frete:

Campo	Tipo	Descrição
`modalidade`	enum obrigatório	Modalidade do frete (ver valores abaixo)

modalidade (enum):

PorContaDoRemetente PorContaDoDestinatario PorContaDeTerceiros TransporteProprioPorContaDoRemetente TransporteProprioPorContaDoDestinatario SemOcorrenciaDeTransporte

Objeto transporte.transportadora:

Campo	Tipo	Descrição
`usarDadosEmitente`	boolean	Usar dados da empresa emitente
`cpfCnpj`	string	CPF ou CNPJ da transportadora
`tipoPessoa`	enum	`F` ou `J`
`nome`	string	Nome/Razão social
`inscricaoEstadual`	string	IE da transportadora
`enderecoCompleto`	string	Endereço completo
`cidade`	string	Cidade
`uf`	string	UF

Objeto transporte.veiculo:

Campo	Tipo	Descrição
`placa`	string	Placa do veículo
`uf`	string	UF do veículo
`rntc`	string	Registro ANTT (RNTC)

Objeto transporte.volume:

Campo	Tipo	Descrição
`quantidade`	integer	Quantidade de volumes
`especie`	string	Espécie (CAIXA, PACOTE, etc.)
`marca`	string	Marca
`numeracao`	string	Numeração
`pesoLiquido`	number	Peso líquido (kg)
`pesoBruto`	number	Peso bruto (kg)

Objeto cobranca (vendas a prazo):

Campo	Tipo	Descrição
`fatura`	object	Dados da fatura
`parcelas`	array	Lista de parcelas

Objeto cobranca.fatura:

Campo	Tipo	Descrição
`numero`	string	Número da fatura
`valorOriginal`	number	Valor original da fatura
`desconto`	number	Valor do desconto

Objeto cobranca.parcelas[]:

Campo	Tipo	Descrição
`numero`	integer	Número da parcela (1, 2, 3...)
`vencimento`	date	Data de vencimento (YYYY-MM-DD)
`valor`	number	Valor da parcela

Objeto nfeReferenciada[] (para devoluções/complementares):

Campo	Tipo	Descrição
`chaveAcesso`	string obrigatório	Chave de acesso da NFe referenciada (44 dígitos)

💡 Quando usar nfeReferenciada

Use para vincular notas em operações de devolução, complementar ou ajuste. A chave de acesso é o número de 44 dígitos que identifica unicamente a NFe original.

Exemplo completo:

{
  "referencia": "PEDIDO-001",
  "ambiente": "Homologacao",
  "numero": 1,
  "serie": "1",
  "tipoOperacao": "Saida",
  "naturezaOperacao": "Venda de mercadoria",
  "finalidade": "Normal",
  "consumidorFinal": true,
  "enviarPorEmail": true,
  "pedido": {
    "presencaConsumidor": "OperacaoPelaInternet",
    "pagamento": {
      "tipo": "PagamentoAVista",
      "formas": [{
        "tipo": "CartaoDeCredito",
        "valor": 150.00
      }]
    }
  },
  "cliente": {
    "tipoPessoa": "F",
    "cpfCnpj": "12345678900",
    "nome": "João da Silva",
    "email": "[email protected]",
    "indicadorContribuinteICMS": "ContribuinteNaoContribuinte",
    "endereco": {
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01001000"
    }
  },
  "itens": [{
    "cfop": "5102",
    "codigo": "PROD001",
    "descricao": "Camiseta Algodão P",
    "ncm": "61091000",
    "ean": "SEM GTIN",
    "quantidade": 2,
    "unidadeMedida": "UN",
    "valorUnitario": 75.00,
    "impostos": {
      "icms": {
        "origem": 0,
        "situacaoTributaria": "102"
      },
      "pis": { "situacaoTributaria": "07" },
      "cofins": { "situacaoTributaria": "07" }
    }
  }]
}

curl -X POST https://homologacao.notaapi.com.br/v2/nfe \
  -u "sua_api_key:" \
  -H "Content-Type: application/json" \
  -H "companyId: seu-company-id-uuid" \
  -d '{
    "referencia": "PEDIDO-001",
    "ambiente": "Homologacao",
    "tipoOperacao": "Saida",
    "naturezaOperacao": "Venda de mercadoria",
    "finalidade": "Normal",
    "consumidorFinal": true,
    "cliente": { ... },
    "itens": [ ... ]
  }'

const payload = {
  referencia: 'PEDIDO-001',
  ambiente: 'Homologacao',
  tipoOperacao: 'Saida',
  naturezaOperacao: 'Venda de mercadoria',
  finalidade: 'Normal',
  consumidorFinal: true,
  cliente: { /* ... */ },
  itens: [ /* ... */ ]
};

const response = await fetch('https://homologacao.notaapi.com.br/v2/nfe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from('sua_api_key:').toString('base64'),
    'companyId': 'seu-company-id-uuid'
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
console.log('NFe criada:', data.id);

import requests
from requests.auth import HTTPBasicAuth

payload = {
    "referencia": "PEDIDO-001",
    "ambiente": "Homologacao",
    "tipoOperacao": "Saida",
    "naturezaOperacao": "Venda de mercadoria",
    "finalidade": "Normal",
    "consumidorFinal": True,
    "cliente": { # ... },
    "itens": [ # ... ]
}

response = requests.post(
    'https://homologacao.notaapi.com.br/v2/nfe',
    auth=HTTPBasicAuth('sua_api_key', ''),
    headers={'companyId': 'seu-company-id-uuid'},
    json=payload
)

print('NFe criada:', response.json()['id'])

<?php
$payload = [
    'referencia' => 'PEDIDO-001',
    'ambiente' => 'Homologacao',
    'tipoOperacao' => 'Saida',
    'naturezaOperacao' => 'Venda de mercadoria',
    'finalidade' => 'Normal',
    'consumidorFinal' => true,
    'cliente' => [ /* ... */ ],
    'itens' => [ /* ... */ ]
];

$ch = curl_init('https://homologacao.notaapi.com.br/v2/nfe');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => 'sua_api_key:',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'companyId: seu-company-id-uuid'
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);

$response = json_decode(curl_exec($ch), true);
echo 'NFe criada: ' . $response['id'];

Resposta (201 Created):

{ "id": "550e8400-e29b-41d4-a716-446655440000" }

Consultar NFe

GET /nfe/{referencia}

Consulta o status de uma NFe pela referência que você enviou na emissão.

Headers:

companyId: UUID da empresa

Campos da resposta:

Campo	Tipo	Descrição
`id`	uuid	ID único da nota
`referencia`	string	Sua referência
`ambiente`	enum	`Homologacao` ou `Producao`
`status`	integer	0=Novo, 1=Enviado, 2=Autorizado, 3=Cancelado, 4=Inutilizado, 5=Erro
`enviadaPorEmail`	boolean	Se foi enviada por email
`dataCriacao`	datetime	Data de criação
`dataUltimaAlteracao`	datetime	Última alteração
`dataAutorizacao`	datetime	Data de autorização
`dataCompetencia`	date	Data de competência
`clienteNome`	string	Nome do cliente
`clienteDocumento`	string	CPF/CNPJ do cliente
`numero`	integer	Número da nota
`protocolo`	string	Protocolo de autorização
`chaveAcesso`	string	Chave de acesso (44 dígitos)
`cStat`	integer	Código de status SEFAZ (100=autorizado)
`linkDownloadPDF`	string	URL para download do PDF
`linkDownloadXML`	string	URL para download do XML
`erros`	array	Lista de erros (se houver)
`avisos`	array	Lista de avisos (se houver)

Exemplo de resposta:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "referencia": "PEDIDO-001",
  "ambiente": "Homologacao",
  "status": 2,
  "enviadaPorEmail": true,
  "dataCriacao": "2025-12-02T10:00:00Z",
  "dataUltimaAlteracao": "2025-12-02T14:30:00Z",
  "dataAutorizacao": "2025-12-02T14:30:00Z",
  "dataCompetencia": "2025-12-02",
  "clienteNome": "João da Silva",
  "clienteDocumento": "12345678901",
  "numero": 1234,
  "protocolo": "135210000123456",
  "chaveAcesso": "35231112345678000199550010000012341123456789",
  "cStat": 100,
  "linkDownloadPDF": "https://...",
  "linkDownloadXML": "https://...",
  "erros": [],
  "avisos": []
}
            

Cancelar NFe

DELETE /nfe/{referencia}

Cancela uma NFe autorizada.

Corpo da requisição:

Campo	Tipo	Descrição
`justificativa`	string obrigatório	Motivo do cancelamento (15-255 caracteres)

Campos da resposta:

Campo	Tipo	Descrição
`id_cancelamento`	number	ID do cancelamento
`status`	enum	`cancelado`, `erro_cancelamento`, `cancelamento_solicitado`
`erros`	array	Lista de erros (se houver)

⏰ Prazo de cancelamento

O prazo de cancelamento varia por UF. A maioria dos estados permite 24 horas, mas alguns como SP, MG e RS podem ter prazos diferentes (até 168h em alguns casos). Consulte a legislação do estado.

Carta de Correção (CC-e)

POST /nfe/{referencia}/cce

Emite uma Carta de Correção Eletrônica para corrigir informações da NFe após autorização.

Campos:

Campo	Tipo	Descrição
`ambiente`	enum obrigatório	`Homologacao` ou `Producao`
`referencia`	string obrigatório	Referência da nota original
`correcao`	string obrigatório	Texto da correção (15-1000 caracteres)

Exemplo:

curl -X POST https://api.notaapi.com.br/v2/nfe/PEDIDO-001/cce \
  -u "sua_api_key:" \
  -H "Content-Type: application/json" \
  -H "companyId: seu-company-id-uuid" \
  -d '{
    "ambiente": "Producao",
    "referencia": "PEDIDO-001",
    "correcao": "Razão Social correta: Empresa ABC LTDA"
  }'
            

💡 O que pode ser corrigido

A CC-e pode corrigir dados como razão social, endereço, CFOP, entre outros. Não é permitido alterar: valores, quantidades, alíquotas de impostos, dados que alterem o cálculo do imposto, ou a data de emissão/saída.

Resposta:

Campo	Tipo	Descrição
`id`	integer	ID da CC-e
`status`	integer	Status (2 = autorizada)
`protocolo`	string	Protocolo de autorização
`cstat`	integer	Código de status SEFAZ
`xmotivo`	string	Descrição do status
`urlDownloadPDF`	string	Link para download do PDF
`urlDownloadXML`	string	Link para download do XML

Distribuição e Manifesto NFe

GET /nfe/distribuicao

Consulta notas fiscais emitidas contra o CNPJ da empresa (DF-e).

POST /nfe/distribuicao

Busca distribuição de documentos fiscais na SEFAZ.

Parâmetros da requisição:

Campo	Tipo	Descrição
`ambiente`	enum obrigatório	`Homologacao` ou `Producao`
`chaveAcesso`	string	Chave de acesso específica (opcional)
`nsu`	integer	NSU específico para consulta
`ultNSU`	integer	Último NSU processado (para paginação)

Campos da resposta:

Campo	Tipo	Descrição
`cStat`	integer	Código de status SEFAZ
`xMotivo`	string	Descrição do status
`dhResp`	datetime	Data/hora da resposta
`ultNSU`	integer	Último NSU retornado
`maxNSU`	integer	NSU máximo disponível
`itens`	array	Lista de documentos encontrados

POST /nfe/manifesto

Realiza manifestação do destinatário (confirma, desconhece, ciência ou operação não realizada).

Parâmetros manifesto:

Campo	Tipo	Descrição
`ambiente`	enum obrigatório	`Homologacao` ou `Producao`
`chaveAcesso`	string obrigatório	Chave da NFe (44 dígitos)
`tipoEvento`	enum obrigatório	Tipo de manifestação
`justificativa`	string obrigatório	Justificativa (obrigatória para alguns eventos)

tipoEvento (manifesto):

confirmacao desconhecimento ciencia operacao_nao_realizada

Emitir NFCe

POST /nfce

Emite Nota Fiscal de Consumidor Eletrônica (modelo 65) para vendas no varejo.

O payload é similar ao da NFe. Consulte a documentação de NFe para referência.

Consultar NFCe

GET /nfce/{referencia}

Cancelar NFCe

DELETE /nfce/{referencia}

Emitir NFSe

POST /nfse

Emite Nota Fiscal de Serviço Eletrônica para prestação de serviços.

Campos principais:

Campo	Tipo	Descrição
`referencia`	string obrigatório	Seu ID único
`ambiente`	enum obrigatório	`Homologacao` ou `Producao`
`dataCompetencia`	date obrigatório	Data de competência (YYYY-MM-DD)
`naturezaOperacao`	string obrigatório	Natureza da operação
`valorTotal`	number obrigatório	Valor total do serviço
`cliente`	object obrigatório	Dados do tomador
`servico`	object obrigatório	Dados do serviço
`ibscbs`	object	IBS/CBS - Reforma Tributária (ver seção abaixo)
`metadados`	object	Itens detalhados do serviço (ver seção abaixo)
`enviarPorEmail`	boolean	Enviar por email ao tomador
`dadosAdicionaisEmail`	object	Emails adicionais
`outrasInformacoes`	string	Observações adicionais
`deducoes`	number	Valor de deduções
`descontos`	number	Valor de descontos
`outrasRetencoes`	number	Outras retenções
`numeroRpsSubstituido`	number	Número do RPS substituído (para substituição)
`serieRpsSubstituido`	string	Série do RPS substituído
`tipoRpsSubstituido`	string	Tipo do RPS substituído

Campos de retenções (opcionais):

Campo	Tipo	Descrição
`valorPis`	number	Valor do PIS
`valorCofins`	number	Valor do COFINS
`valorCsll`	number	Valor do CSLL
`valorInss`	number	Valor do INSS
`valorIr`	number	Valor do IR
`valorIss`	number	Valor do ISS

Objeto servico:

Campo	Tipo	Descrição
`codigoServicoMunicipio`	string obrigatório	Código do serviço no município
`descricao`	string obrigatório	Descrição do serviço prestado
`aliquotaIss`	number obrigatório	Alíquota de ISS (%)
`itemListaServicoLC116`	string	Item da lista LC 116 (ex: "1.02")
`cnae`	string	Código CNAE
`codigoNbs`	string	Código NBS
`valorIss`	number	Valor do ISS
`issRetidoFonte`	boolean	Se o ISS é retido na fonte
`municipioPrestacaoServico`	string	Código IBGE do município onde o serviço foi prestado
`ufPrestacaoServico`	string	UF onde o serviço foi prestado

Retenções no objeto servico:

Campo	Tipo	Descrição
`valorPis`	number	Valor do PIS
`pisRetido`	boolean	PIS retido na fonte
`valorCofins`	number	Valor do COFINS
`cofinsRetido`	boolean	COFINS retido na fonte
`valorCsll`	number	Valor do CSLL
`csllRetido`	boolean	CSLL retido na fonte
`valorInss`	number	Valor do INSS
`inssRetido`	boolean	INSS retido na fonte
`valorIr`	number	Valor do IR
`irRetido`	boolean	IR retido na fonte

Objeto cliente (tomador):

Campo	Tipo	Descrição
`tipoPessoa`	enum obrigatório	`F` ou `J`
`cpfCnpj`	string obrigatório	CPF ou CNPJ
`nome`	string obrigatório	Nome/Razão social
`endereco`	object obrigatório	Endereço do tomador
`email`	string	E-mail
`telefone`	string	Telefone
`inscricaoMunicipal`	string	Inscrição municipal
`inscricaoEstadual`	string	Inscrição estadual
`nif`	string	NIF (para estrangeiros)
`cNaoNIF`	enum	`nao_informado`, `dispensado`, `nao_exigencia`

Objeto metadados (itens detalhados da NFSe):

Campo	Tipo	Descrição
`itens[]`	array	Lista de itens detalhados do serviço

Objeto metadados.itens[]:

Campo	Tipo	Descrição
`discriminacaoServico`	string obrigatório	Descrição do serviço
`quantidade`	number obrigatório	Quantidade
`valorUnitario`	number obrigatório	Valor unitário
`tributavel`	boolean obrigatório	Se o item é tributável
`aliquotaIss`	number obrigatório	Alíquota de ISS (%)
`itemListaServicoLC116`	string obrigatório	Item da LC 116 (ex: "1.02")
`codigoServicoMunicipio`	string obrigatório	Código do serviço no município
`cnae`	string obrigatório	Código CNAE

Objeto ibscbs (NFSe - Reforma Tributária):

🆕 IBS/CBS para Serviços

Campos do IBS/CBS específicos para NFSe. Será obrigatório gradualmente conforme cronograma da reforma tributária.

Campo	Tipo	Descrição
`finNFSe`	enum obrigatório	Finalidade: `regular`
`indFinal`	boolean obrigatório	Indicador consumidor final
`cIndOp`	string obrigatório	Código indicador da operação
`tpOper`	enum obrigatório	Tipo operação governo (ver abaixo)
`tpEnteGov`	enum obrigatório	Tipo entidade governo (ver abaixo)
`indDest`	enum obrigatório	Indicador destinatário
`valores`	object obrigatório	Valores e tributação
`imovel`	object	Dados do imóvel (quando aplicável)

tpOper - Tipo Operação Governo:

nenhum fornecimento recebimento_pag fornecimento_realizado recebimento_pag_posterior fornecimento_recebimento

tpEnteGov - Tipo Entidade Governo:

nenhum uniao estados distrito_federal municipios

Objeto valores (ibscbs NFSe):

Campo	Tipo	Descrição
`gReeRepRes`	array	Repasse/ressarcimento
`trib`	object	Dados de tributação

Objeto valores.trib:

Campo	Tipo	Descrição
`gIBSCBS`	object obrigatório	Dados de tributação IBS/CBS

Objeto valores.trib.gIBSCBS (tributação):

Campo	Tipo	Descrição
`cst`	string obrigatório	CST IBS/CBS (000, 010, 200, 400, etc.)
`cClassTrib`	string obrigatório	Código classificação tributária
`cCredPres`	string obrigatório	Código crédito presumido (01 a 13)
`gTribRegular`	object	Tributação regular
`gDif`	object	Diferimento

Objeto gDif (diferimento NFSe):

Campo	Tipo	Descrição
`pDifUF`	number obrigatório	Percentual diferimento UF
`pDifMun`	number obrigatório	Percentual diferimento Municipal
`pDifCBS`	number obrigatório	Percentual diferimento CBS

Exemplo:

{
  "referencia": "SERVICO-001",
  "ambiente": "Homologacao",
  "dataCompetencia": "2025-12-02",
  "naturezaOperacao": "1",
  "valorTotal": 5000.00,
  "enviarPorEmail": true,
  "cliente": {
    "tipoPessoa": "J",
    "cpfCnpj": "12345678000199",
    "nome": "Empresa Cliente LTDA",
    "email": "[email protected]",
    "endereco": {
      "logradouro": "Av Paulista",
      "numero": "1000",
      "bairro": "Bela Vista",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01310100"
    }
  },
  "servico": {
    "codigoServicoMunicipio": "1.02",
    "descricao": "Desenvolvimento de software - Projeto XYZ",
    "aliquotaIss": 2.00,
    "itemListaServicoLC116": "1.02"
  }
}

curl -X POST https://homologacao.notaapi.com.br/v2/nfse \
  -u "sua_api_key:" \
  -H "Content-Type: application/json" \
  -H "companyId: seu-company-id-uuid" \
  -d '{
    "referencia": "SERVICO-001",
    "ambiente": "Homologacao",
    "dataCompetencia": "2025-12-02",
    "naturezaOperacao": "1",
    "valorTotal": 5000.00,
    "cliente": { ... },
    "servico": { ... }
  }'

const payload = {
  referencia: 'SERVICO-001',
  ambiente: 'Homologacao',
  dataCompetencia: '2025-12-02',
  naturezaOperacao: '1',
  valorTotal: 5000.00,
  cliente: { /* ... */ },
  servico: {
    codigoServicoMunicipio: '1.02',
    descricao: 'Desenvolvimento de software',
    aliquotaIss: 2.00
  }
};

const response = await fetch('https://homologacao.notaapi.com.br/v2/nfse', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from('sua_api_key:').toString('base64'),
    'companyId': 'seu-company-id-uuid'
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
console.log('NFSe criada:', data.id);

import requests
from requests.auth import HTTPBasicAuth

payload = {
    "referencia": "SERVICO-001",
    "ambiente": "Homologacao",
    "dataCompetencia": "2025-12-02",
    "naturezaOperacao": "1",
    "valorTotal": 5000.00,
    "cliente": { # ... },
    "servico": {
        "codigoServicoMunicipio": "1.02",
        "descricao": "Desenvolvimento de software",
        "aliquotaIss": 2.00
    }
}

response = requests.post(
    'https://homologacao.notaapi.com.br/v2/nfse',
    auth=HTTPBasicAuth('sua_api_key', ''),
    headers={'companyId': 'seu-company-id-uuid'},
    json=payload
)

print('NFSe criada:', response.json()['id'])

<?php
$payload = [
    'referencia' => 'SERVICO-001',
    'ambiente' => 'Homologacao',
    'dataCompetencia' => '2025-12-02',
    'naturezaOperacao' => '1',
    'valorTotal' => 5000.00,
    'cliente' => [ /* ... */ ],
    'servico' => [
        'codigoServicoMunicipio' => '1.02',
        'descricao' => 'Desenvolvimento de software',
        'aliquotaIss' => 2.00
    ]
];

$ch = curl_init('https://homologacao.notaapi.com.br/v2/nfse');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => 'sua_api_key:',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'companyId: seu-company-id-uuid'
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);

$response = json_decode(curl_exec($ch), true);
echo 'NFSe criada: ' . $response['id'];

Consultar NFSe

GET /nfse/{referencia}

Campos da resposta:

Campo	Tipo	Descrição
`id`	uuid	ID único da nota
`referencia`	string	Sua referência
`ambiente`	enum	`Homologacao` ou `Producao`
`status`	integer	0=Novo, 1=Enviado, 2=Autorizado, 3=Cancelado, 5=Erro
`enviadaPorEmail`	boolean	Se foi enviada por email
`dataCriacao`	datetime	Data de criação
`dataUltimaAlteracao`	datetime	Última alteração
`dataAutorizacao`	datetime	Data de autorização
`dataCompetencia`	date	Data de competência
`clienteNome`	string	Nome do tomador
`clienteDocumento`	string	CPF/CNPJ do tomador
`numero`	integer	Número da nota
`codigoVerificacao`	string	Código de verificação
`chaveAcesso`	string	Chave de acesso
`linkDownloadPDF`	string	URL para download do PDF
`linkDownloadXML`	string	URL para download do XML
`LinkPrefeitura`	string	Link para consulta na prefeitura
`numeroRps`	string	Número do RPS
`serieRps`	string	Série do RPS
`erros`	array	Lista de erros (se houver)
`avisos`	array	Lista de avisos (se houver)

Cancelar NFSe

DELETE /nfse/{referencia}

ℹ️ Prazo varia por cidade

Cada prefeitura define seu prazo de cancelamento. Algumas permitem até 24h, outras apenas no mesmo dia.

Emitir NFCom

POST /nfcom

Emite Nota Fiscal de Comunicação Eletrônica (modelo 62) para empresas de telecomunicações (telefonia, internet, TV por assinatura).

Headers obrigatórios:

companyId: UUID da empresa emissora
Content-Type: application/json

Campos principais:

Campo	Tipo	Descrição
`referencia`	string obrigatório	Seu ID único
`ambiente`	enum obrigatório	`Homologacao` ou `Producao`
`tipo_faturamento`	enum obrigatório	`normal`, `centralizado`, `cofaturamento`
`data_emissao`	date obrigatório	Data de emissão (YYYY-MM-DD)
`serie`	string obrigatório	Série da nota
`numero`	string obrigatório	Número da nota
`finalidade`	enum obrigatório	`normal`, `substituicao`, `ajuste_debito`
`pre_pago`	boolean	Se é serviço pré-pago
`cliente`	object obrigatório	Dados do cliente/destinatário
`assinante`	object obrigatório	Dados do assinante
`itens`	array	Lista de serviços/produtos
`fatura`	object	Dados da fatura

Objeto assinante:

Campo	Tipo	Descrição
`codigo`	string obrigatório	Código do assinante
`tipo_assinante`	enum obrigatório	Tipo do assinante
`tipo_servico_utilizado`	enum obrigatório	Tipo de serviço
`numero_contrato`	string obrigatório	Número do contrato
`data_inicio_contrato`	date obrigatório	Data início do contrato
`data_fim_contrato`	date obrigatório	Data fim do contrato
`terminal_principal`	string	Número do terminal principal

tipo_assinante (enum):

comercial industrial residencial produtor_rural orgao_publico prestador_servico_telecom missoes_diplomaticas igrejas_templos outros

tipo_servico_utilizado (enum):

telefonia comunicacao_dados tv_assinatura acesso_internet multimidia combo outros

Objeto item (itens[]):

Campo	Tipo	Descrição
`numero_item`	integer obrigatório	Número sequencial do item
`produto`	object obrigatório	Dados do produto/serviço
`impostos`	object obrigatório	Impostos (ICMS, PIS, COFINS, FUST, FUNTTEL)

Objeto produto:

Campo	Tipo	Descrição
`codigo`	string	Código do produto
`descricao`	string	Descrição
`classificacao`	string	Classificação do produto
`cfop`	string	CFOP
`unidade_medida`	enum	`minuto`, `mb`, `gb`, `un`
`quantidade`	number	Quantidade
`valor_unitario`	number	Valor unitário

Objeto fatura:

Campo	Tipo	Descrição
`data_competencia`	date	Data de competência
`data_vencimento`	date	Data de vencimento
`periodo_uso_inicial`	date	Início do período de uso
`periodo_uso_final`	date	Fim do período de uso
`codigo_barras`	string	Código de barras do boleto
`url_qrcode_pix`	string	URL do QR Code PIX

Exemplo:

{
  "referencia": "TELECOM-001",
  "ambiente": "Homologacao",
  "tipo_faturamento": "normal",
  "data_emissao": "2025-12-02",
  "serie": "1",
  "numero": "1234",
  "finalidade": "normal",
  "pre_pago": false,
  "cliente": {
    "tipoPessoa": "F",
    "cpfCnpj": "12345678900",
    "nome": "João da Silva",
    "email": "[email protected]",
    "indicadorContribuinteICMS": "ContribuinteNaoContribuinte",
    "endereco": {
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01001000"
    }
  },
  "assinante": {
    "codigo": "ASS-12345",
    "tipo_assinante": "residencial",
    "tipo_servico_utilizado": "combo",
    "numero_contrato": "CONT-2024-001",
    "data_inicio_contrato": "2024-01-01",
    "data_fim_contrato": "2025-12-31",
    "terminal_principal": "11999999999"
  },
  "itens": [{
    "numero_item": 1,
    "produto": {
      "codigo": "INTERNET-100",
      "descricao": "Internet Fibra 100MB",
      "classificacao": "06",
      "cfop": "5307",
      "unidade_medida": "un",
      "quantidade": 1,
      "valor_unitario": 99.90
    },
    "impostos": {
      "icms": {
        "cst": "00",
        "base_calculo": 99.90,
        "aliquota": 25,
        "valor": 24.98
      },
      "pis": { "cst": "01", "base_calculo": 99.90, "aliquota": 0.65, "valor": 0.65 },
      "cofins": { "cst": "01", "base_calculo": 99.90, "aliquota": 3, "valor": 3.00 }
    }
  }],
  "fatura": {
    "data_competencia": "2025-12-01",
    "data_vencimento": "2025-12-10",
    "periodo_uso_inicial": "2025-11-01",
    "periodo_uso_final": "2025-11-30",
    "codigo_barras": "23793.38128 60000.000003 00000.000402 1 84340000010000"
  }
}

Resposta (201 Created):

{ "id": "550e8400-e29b-41d4-a716-446655440000" }

Consultar NFCom

GET /nfcom/{referencia}

Consulta o status de uma NFCom pela referência.

Resposta:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "referencia": "TELECOM-001",
  "ambiente": "Homologacao",
  "status": 2,
  "serie": "1",
  "numero": 1234,
  "protocolo": "135210000123456",
  "chave_acesso": "35231112345678000199620010000012341123456789",
  "codigo_status": 100,
  "link_download_pdf": "https://...",
  "link_download_xml": "https://...",
  "data_autorizacao": "2025-12-02T14:30:00Z",
  "erros": [],
  "avisos": []
}
            

Cancelar NFCom

DELETE /nfcom/{referencia}

Cancela uma NFCom autorizada.

Campo	Tipo	Descrição
`justificativa`	string obrigatório	Motivo do cancelamento (15-255 caracteres)

Consultar Webhooks

GET /webhooks

Lista todos os webhooks configurados.

Campos da resposta (cada webhook):

Campo	Tipo	Descrição
`id`	integer	ID do webhook
`url`	string	URL configurada
`tipoDocumento`	array	Tipos de documento
`tipoEvento`	array	Tipos de evento
`customHeader`	string	Header customizado
`customHeaderValue`	string	Valor do header
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data de atualização

Criar Webhook

POST /webhooks

Cria um webhook para receber notificações quando o status de um documento mudar.

Campo	Tipo	Descrição
`url`	string obrigatório	URL que receberá as notificações
`tipoDocumento`	array obrigatório	Tipos: `nfe`, `nfce`, `nfse`, `cte`, `mdfe`
`tipoEvento`	array obrigatório	Eventos (veja abaixo)
`customHeader`	string	Nome do header customizado
`customHeaderValue`	string	Valor do header customizado

tipoEvento (enum):

inclusao autorizacao cancelamento inutilizacao contingencia erro

Exemplo:

{
  "url": "https://meusite.com/webhook/notaapi",
  "tipoDocumento": ["nfe", "nfse"],
  "tipoEvento": ["autorizacao", "cancelamento", "erro"],
  "customHeader": "X-Webhook-Secret",
  "customHeaderValue": "minha-chave-secreta"
}
            

Reforma Tributária (IBS/CBS)

🆕 O que é a Reforma Tributária?

A Reforma Tributária brasileira (EC 132/2023) está substituindo gradualmente PIS, COFINS, IPI, ICMS e ISS por dois novos tributos: IBS (Imposto sobre Bens e Serviços) e CBS (Contribuição sobre Bens e Serviços).

Cronograma de Implementação

Período	O que muda
2026	Início do período de testes. CBS começa a ser cobrada com alíquota reduzida (0,9%).
2027	IBS começa a ser cobrado com alíquota reduzida. PIS/COFINS são extintos.
2028-2032	Transição gradual. ICMS e ISS são reduzidos progressivamente.
2033	Novo sistema totalmente implementado. ICMS e ISS extintos.

Impacto nos Documentos Fiscais

NFe e NFCe

Os campos do grupo ibscbs serão gradualmente obrigatórios nos itens da nota. Durante a transição, você precisará informar tanto os impostos antigos (ICMS, PIS, COFINS) quanto os novos (IBS, CBS).

NFSe

O ISS será substituído pelo IBS municipal. O objeto ibscbs na NFSe contém campos específicos para serviços, incluindo finalidade, tipo de operação governamental e dados de tributação.

Principais Campos IBS/CBS

Campo	Descrição
`CST`	Código de Situação Tributária do IBS/CBS (000, 010, 200, 400, etc.)
`cClassTrib`	Código de classificação tributária do item
`gIBSUF`	Grupo do IBS estadual (alíquota e valor)
`gIBSMun`	Grupo do IBS municipal (alíquota e valor)
`gCBS`	Grupo da CBS federal (alíquota e valor)
`gIBSCBSMono`	Tributação monofásica (combustíveis, medicamentos, etc.)

CST IBS/CBS

Código	Descrição
`000`	Tributação normal
`010`	Tributação com alíquota diferenciada
`011`	Tributação monofásica
`200`	Isenção
`220`	Redução de base de cálculo
`221`	Redução de alíquota
`222`	Diferimento
`400`	Imunidade
`410`	Não incidência
`510`	Suspensão

Recomendações

⚠️ Prepare-se para a transição

Acompanhe as atualizações da legislação e notas técnicas da SEFAZ
Os campos ibscbs já estão disponíveis na API para testes
Durante 2026, comece a incluir os campos IBS/CBS mesmo sendo opcionais
Consulte seu contador para definir classificações tributárias corretas
A NotaAPI será atualizada conforme as regras forem publicadas

Para detalhes técnicos dos campos IBS/CBS, consulte as seções de NFe e NFSe.

Tratamento de Erros

Códigos HTTP

Código	Significado	Ação
`200`	Sucesso	Processar resposta
`201`	Criado	Recurso criado com sucesso
`400`	Requisição inválida	Verificar campos obrigatórios
`401`	Não autorizado	Verificar credenciais
`403`	Permissão negada	Verificar permissões
`404`	Não encontrado	Verificar ID/referência
`422`	Erro de validação	Empresa já existe ou dados inválidos
`500`	Erro interno	Tentar novamente ou contatar suporte

Estrutura de erro

{
  "code": 400,
  "message": "Descrição do erro"
}
            

⚠️ Erros Comuns da SEFAZ

Rejeições mais frequentes e como resolver:

Problemas com Certificado/Credenciais

Código	Mensagem	Causa	Solução
`280`	Certificado Transmissor Inválido	Certificado vencido ou não instalado corretamente	Verificar validade do certificado A1 e refazer upload
`281`	Certificado Transmissor Revogado	Certificado foi revogado pela certificadora	Adquirir novo certificado digital
`282`	Certificado Transmissor Validade	Certificado expirado	Renovar certificado digital A1
`213`	CNPJ-Base do Emitente difere do CNPJ-Base do Certificado	Certificado é de outra empresa	Usar certificado da empresa emissora

Problemas com Destinatário

Código	Mensagem	Causa	Solução
`539`	Duplicidade de NF-e	Já existe NFe com mesmo número/série	Usar outro número ou inutilizar a faixa
`204`	Duplicidade de NF-e (chave de acesso)	Chave de acesso já utilizada	Usar nova referência para gerar nova chave
`232`	IE do destinatário não cadastrada	Inscrição Estadual do cliente inválida	Verificar IE do destinatário na SEFAZ
`236`	CPF do destinatário inválido	CPF não existe ou está irregular	Verificar CPF do cliente
`237`	CNPJ do destinatário inválido	CNPJ não existe ou está irregular	Verificar CNPJ na Receita Federal

Problemas com Produto/Item

Código	Mensagem	Causa	Solução
`321`	NCM inválido	Código NCM não existe na tabela	Verificar NCM correto na tabela TIPI
`778`	NCM incompatível com o CFOP	Combinação NCM + CFOP não permitida	Verificar CFOP correto para o produto
`694`	Não informado GTIN do item	Campo EAN obrigatório não informado	Informar EAN ou usar "SEM GTIN"
`611`	CFOP de entrada para operação de saída	CFOP incompatível com tipo de operação	Usar CFOP de saída (5xxx ou 6xxx)
`598`	Usar código de barras próprio	GTIN/EAN inválido	Corrigir EAN ou usar "SEM GTIN"

Problemas com Impostos

Código	Mensagem	Causa	Solução
`388`	CST incompatível com o CFOP	CST/CSOSN não combina com o CFOP	Verificar combinação CST+CFOP correta
`906`	CSOSN incompatível com regime tributário	Usando CSOSN em empresa que não é Simples	Usar CST normal ao invés de CSOSN
`528`	Valor ICMS diferente do calculado	Base × Alíquota não confere com valor	Recalcular ICMS (base × alíquota ÷ 100)
`627`	Total da NF difere do somatório	Valor total não confere com soma dos itens	Somar valores unitários × quantidade

Problemas com Empresa/Emitente

Código	Mensagem	Causa	Solução
`202`	IE do emitente não vinculada ao CNPJ	IE não está associada ao CNPJ na SEFAZ	Verificar cadastro na SEFAZ do estado
`209`	IE do emitente como não contribuinte	Empresa não habilitada para emitir NFe	Solicitar credenciamento na SEFAZ
`217`	UF emitente não autorizada	Estado não aceita essa operação	Verificar regras específicas do estado

Problemas com Cancelamento

Código	Mensagem	Causa	Solução
`501`	Prazo de cancelamento expirado	Passou do prazo permitido pela UF	Emitir nota de devolução/estorno
`218`	NFe já está cancelada	Tentou cancelar nota já cancelada	Nenhuma ação necessária
`220`	NFe fora do prazo de cancelamento	Fora do prazo permitido pela UF	Emitir nota de ajuste/devolução

💡 Dica de debug

Sempre verifique o campo erros na resposta de consulta da nota. Ele contém a lista completa de rejeições da SEFAZ com código e mensagem detalhada.

Status das Notas

O campo status retornado nas consultas indica o estado do documento:

Código	Status	Descrição
`0`	Novo	Documento criado, aguardando processamento
`1`	Enviado	Enviado para SEFAZ/Prefeitura
`2`	Autorizado ✅	Documento autorizado com sucesso
`3`	Cancelado	Documento foi cancelado
`4`	Inutilizado	Numeração inutilizada
`5`	Erro ❌	Erro na emissão - verificar campo `erros`

Enumerações

tipoContribuinte

simples_nacional simples_excesso_receita regime_normal mei

ambiente

Homologacao Producao

tipoOperacao

Entrada Saida

finalidade

Normal Complementar Ajuste DevolucaoMercadoria

tipoPessoa

F J

indicadorContribuinteICMS

ContribuinteICMS ContribuinteIsento ContribuinteNaoContribuinte

presencaConsumidor

NaoSeAplica OperacaoPresencial OperacaoPelaInternet OperacaoTeleAtendimento EntregaADomicilio OperacaoPresencialForaDoEstabelecimento

tipoPagamento

PagamentoAVista PagamentoAPrazo PagamentoOutros

tipoFormaPagamento

Dinheiro CartaoDeCredito CartaoDeDebito PagamentoInstantaneoPix BoletoBancario DepositoBancario Cheque CreditoLoja ValeAlimentacao ValeRefeicao SemPagamento Outros

modalidadeFrete

PorContaDoRemetente PorContaDoDestinatario PorContaDeTerceiros TransporteProprioPorContaDoRemetente TransporteProprioPorContaDoDestinatario SemOcorrenciaDeTransporte

tipoDocumento (Webhooks)

nfe nfce nfse nfcom

tipoEvento (Webhooks)

inclusao autorizacao cancelamento inutilizacao contingencia erro

tipo_faturamento (NFCom)

normal centralizado cofaturamento

tipo_assinante (NFCom)

comercial industrial residencial produtor_rural orgao_publico prestador_servico_telecom missoes_diplomaticas igrejas_templos outros

tipo_servico_utilizado (NFCom)

telefonia comunicacao_dados tv_assinatura acesso_internet multimidia combo outros

unidade_medida (NFCom)

minuto mb gb un

❓ FAQ - Perguntas Frequentes

Qual a diferença entre NFe e NFCe?

NFe (modelo 55) é usada em vendas B2B ou quando precisa de mais detalhes fiscais. Exige identificação do destinatário. NFCe (modelo 65) é para varejo/consumidor final, substitui o cupom fiscal. Mais simples e permite emissão sem identificar o cliente (CPF opcional).

Posso usar certificado A3?

Não. A NotaAPI suporta apenas certificados A1 (arquivo .pfx). Certificados A3 (token/cartão) não são compatíveis com integração via API. Se você tem um A3, precisará adquirir um A1.

Quanto tempo tenho para cancelar uma nota?

NFe/NFCe: Varia por UF (geralmente 24h, mas pode chegar a 168h em alguns estados como SP e RS). NFSe: Varia por prefeitura - algumas permitem dias, outras apenas horas. Após o prazo, é necessário emitir nota de devolução/estorno.

Posso testar sem emitir notas reais?

Sim! Use o ambiente de Homologação ("ambiente": "Homologacao"). As notas são enviadas para o ambiente de testes da SEFAZ e não têm valor fiscal. Perfeito para desenvolvimento e testes.

O que é o CSC/Token da NFCe?

É um código de segurança obrigatório para NFCe. Você obtém no portal da SEFAZ do seu estado, na área de contribuintes. São dois valores: ID do Token (número) e o Token em si (código alfanumérico).

Como sei se a nota foi autorizada?

Consulte a nota usando GET /nfe/{referencia}. Se o campo status for 2, está autorizada. Se for 5, teve erro - verifique o campo erros para detalhes.

A numeração da nota é automática?

Depende do tipo: Para NFSe, a numeração é automática - a API gerencia para você. Para NFe/NFCe, você precisa enviar o número e série no payload. Você é responsável por controlar a sequência no seu sistema.

Quanto tempo leva para autorizar uma nota?

NFe/NFCe: Normalmente 2-5 segundos. Pode levar mais em horários de pico ou instabilidade da SEFAZ. NFSe: 3-15 segundos, dependendo da prefeitura.

O que fazer quando a SEFAZ está fora do ar?

Para NFCe existe a contingência offline - a nota é emitida localmente e enviada depois. A API gerencia isso automaticamente. Para NFe, aguarde a SEFAZ normalizar ou use contingência SVC (se habilitada no estado).

Como descubro o código IBGE da cidade?

Acesse ibge.gov.br/cidades-e-estados e busque sua cidade. O código é o número de 7 dígitos. Exemplo: São Paulo = 3550308, Rio de Janeiro = 3304557.

Preciso guardar o XML da nota?

Sim! Por lei, você deve guardar o XML por 5 anos. A NotaAPI disponibiliza o link de download, mas recomendamos que você armazene também no seu sistema.

Qual a diferença entre Simples Nacional e Regime Normal?

Simples Nacional: Regime simplificado para pequenas empresas. Usa códigos CSOSN (101, 102, 500...). Regime Normal (Lucro Presumido/Real): Usa códigos CST (00, 10, 60...). Isso afeta como você preenche os impostos na nota.

🚀 Postman Collection

Collection pronta para testar a API no Postman:

NotaAPI v2 - Collection

Todos os endpoints configurados com variáveis de ambiente

✓ Autenticação pré-configurada ✓ Exemplos de request ✓ Variáveis de ambiente

Abrir Swagger

Configuração Manual

Se preferir configurar manualmente:

Configure as variáveis de ambiente

base_url: https://homologacao.notaapi.com.br/v2
api_key: sua API Key
company_id: UUID da empresa

Configure a autenticação

Em "Authorization", selecione "Basic Auth". Use {{api_key}} no username e deixe password vazio

Adicione o header companyId

Em "Headers", adicione companyId: {{company_id}} para as requisições de documentos

Exemplo de Environment

{
  "id": "notaapi-homologacao",
  "name": "NotaAPI - Homologação",
  "values": [
    { "key": "base_url", "value": "https://homologacao.notaapi.com.br/v2" },
    { "key": "api_key", "value": "SUA_API_KEY" },
    { "key": "company_id", "value": "SEU_COMPANY_ID" }
  ]
}