API de emissão do EasyNotas

Novidades de setembro/2026

Tudo que o painel do EasyNotas ganhou desde julho agora também funciona pela API. Integrações que já existem continuam funcionando sem mudança: todos os campos novos são opcionais.

Visão geral

Seu sistema chama a API com os dados da nota. A API valida autenticação, pagamento do escritório, habilitação da empresa e as regras fiscais, coloca a nota na fila e responde na hora com um id. A autorização na SEFAZ ou na prefeitura acontece em seguida, e o resultado chega por webhook ou por consulta.

Os dados do emitente nunca vêm do seu sistema. Você informa só o cnpj_emitente, e regime tributário, inscrições, endereço, certificado e padrões fiscais saem do cadastro da empresa no EasyNotas. Se o cadastro estiver errado, a nota sai errada: corrija no painel, não no payload.

O que a API faz

Quem usa

ERPs e sistemas de gestão que precisam emitir a nota logo depois do faturamento, plataformas que vendem serviços e querem emitir a NFS-e do cliente, e escritórios contábeis que automatizam a rotina dos clientes. A integração exige trabalho de desenvolvimento do lado de quem consome a API. O EasyNotas fornece a API, esta documentação e o suporte.

Primeiros passos

1. Gere a chave

No EasyNotas, o dono do escritório abre Configurações → API / Desenvolvedores, escolhe o ambiente, aceita os Termos de Uso da API e clica em Gerar nova API key. A chave de sandbox começa com enk_test_ e a de produção com enk_live_.

2. Teste a conexão

curl -i https://pufsgcaxubzxdtmsenjx.supabase.co/functions/v1/api-v1/v1/health

Resposta 200 {"status":"ok"}. Essa rota não exige autenticação.

3. Emita a primeira nota

curl -i -X POST 'https://pufsgcaxubzxdtmsenjx.supabase.co/functions/v1/api-v1/v1/invoices' \
  -H 'Authorization: Bearer enk_test_SUA_CHAVE' \
  -H 'X-EasyNotas-Environment: sandbox' \
  -H 'Idempotency-Key: fatura-2026-000123-teste' \
  -H 'Content-Type: application/json' \
  -d '{
    "tipo": "nfse_nacional",
    "cnpj_emitente": "12345678000190",
    "tomador": {
      "documento": "11222333000181",
      "razao_social": "Cliente Exemplo LTDA",
      "email": "financeiro@exemplo.com.br"
    },
    "servico": {
      "discriminacao": "Consultoria mensal em tecnologia - setembro/2026",
      "valor_servicos": 1500.00,
      "codigo_tributacao_nacional": "010701"
    }
  }'

A resposta é 202 Accepted com o id da nota e status: "queued". Guarde o id: é por ele que você acompanha a nota. O 202 quer dizer "aceita e na fila", não "autorizada".

4. Acompanhe o resultado

Configure a URL de webhook no mesmo painel e o EasyNotas avisa quando a nota for autorizada, rejeitada ou cancelada (veja Webhooks). Se preferir consultar, use GET /v1/invoices/{id}: enquanto a nota está em processing a resposta traz Retry-After: 5; antes disso, na fila, consultar a cada poucos minutos basta.

5. Vá para produção

Gere uma chave de produção, troque o header para production e confirme no cadastro que a empresa está habilitada para o tipo de nota e tem certificado digital válido.

Autenticação e escopos

Escopos

Cada chave carrega uma lista de permissões. Uma rota chamada sem o escopo responde 403 insufficient_scope.

Ambientes

Idempotência, fila e limites

Idempotência

Emitir nota é irreversível. Se a rede cair no meio da chamada e você reenviar, a Idempotency-Key impede a segunda nota. Use um valor estável do seu sistema, como o número da fatura.

• Mesma chave e mesmo corpo: a API devolve a resposta original, com o header Idempotency-Replayed: true.
• Mesma chave e corpo diferente: 409 idempotency_conflict, mas só quando a chave já gerou um 202. Se a primeira tentativa foi recusada (4xx ou 5xx), corrija o corpo e reenvie com a mesma chave.
• A proteção vale por 30 dias. Depois disso a mesma chave pode ser aceita como uma nota nova.
• Mesma chave enquanto a primeira chamada ainda roda: 409 idempotency_in_flight. Espere e repita com a mesma chave.

Fila de emissão

A nota entra na fila e a fila roda a cada 10 minutos. Depois do despacho, a SEFAZ ou a prefeitura costuma responder em segundos. Não trave a tela do seu usuário esperando a autorização.

Limites

O limite por CNPJ protege o certificado do cliente contra bloqueio na SEFAZ Ele conta as emissões feitas pela API; emissões pelo painel, por lote e por recorrência não entram nessa conta.

Emitir nota

O campo tipo, na raiz do corpo, escolhe o documento e as regras aplicadas.

Resposta 202:

{
  "id": "920d1d7a-f721-40d7-a44b-f79af97dd208",
  "status": "queued",
  "idempotency_key": "fatura-2026-000123",
  "created_at": "2026-09-30T13:47:21.816Z"
}
// Header: Location: /v1/invoices/920d1d7a-f721-40d7-a44b-f79af97dd208

NFS-e

Um só tipo para NFS-e. O EasyNotas decide o emissor pelo município da empresa: São Paulo capital usa o sistema da prefeitura, os demais usam o Ambiente Nacional.

{
  "tipo": "nfse_nacional",
  "cnpj_emitente": "12345678000190",
  "tomador": {
    "documento": "11222333000181",
    "razao_social": "Cliente Exemplo LTDA",
    "email": "financeiro@exemplo.com.br",
    "endereco": {
      "logradouro": "Rua das Flores", "numero": "100", "complemento": "Sala 2",
      "bairro": "Centro", "municipio": "Araçatuba", "uf": "SP", "cep": "16010000"
    }
  },
  "servico": {
    "discriminacao": "Intermediação na venda do veículo Onix 2022",
    "valor_servicos": 1500.00,
    "codigo_tributacao_nacional": "100501",
    "aliquota": 2.0,
    "informacoes_complementares": "Veículo placa ABC1D23, chassi 9BG...",
    "codigo_municipio_prestacao": "3502804",
    "codigo_nbs": "102010000",
    "codigo_indicador_operacao": "100301",
    "ibs_cbs_situacao_tributaria": "000",
    "ibs_cbs_classificacao_tributaria": "000001",
    "iss_retido": false
  }
}

Tomador

Serviço

Os quatro campos da Reforma Tributária seguem a regra do painel: o que vier na nota vale; o que não vier sai do padrão cadastrado na empresa. Quando qualquer um deles está presente, o EasyNotas preenche sozinho a finalidade, o consumidor final e o indicador de destinatário exigidos pelo layout novo.

Retenções federais

Só se aplicam a emitente do Lucro Presumido ou Lucro Real. Retenção com valor para empresa do Simples ou MEI é recusada com 422 retencao_not_applicable.

Campos de regime (codigo_opcao_simples_nacional, regime_especial_tributacao e parecidos) não são aceitos no corpo, porque vêm do cadastro. Enviar um deles responde 422 field_inherited_from_company.

NF-e modelo 55

{
  "tipo": "nfe",
  "cnpj_emitente": "12345678000190",
  "destinatario": {
    "nome": "Cliente Exemplo Ltda",
    "documento": "98765432000188",
    "ie": "123456789",
    "contribuinte": true,
    "email": "financeiro@exemplo.com.br",
    "endereco": { "logradouro": "Rua das Palmeiras", "numero": "450", "bairro": "Centro",
                  "municipio": "Campinas", "uf": "SP", "cep": "13010000" }
  },
  "itens": [{
    "codigo": "SKU-1042", "descricao": "Camiseta algodão branca M",
    "quantidade": 2, "valor_unitario": 49.90,
    "ncm": "61091000", "unidade": "UN", "cst_csosn": "102", "origem": 0
  }],
  "pagamento": [{ "forma": "01", "valor": 99.80 }],
  "operacao": { "informacoes_adicionais_contribuinte": "Pedido 5531" }
}

Destinatário e pagamento

Itens

De 1 a 200 itens por nota.

Operação (opcional)

NF-e de devolução

A devolução tem quatro exigências da SEFAZ que o EasyNotas aplica sozinho. Você só precisa informar a finalidade 4, a chave da nota original e o item correspondente.

{
  "tipo": "nfe",
  "cnpj_emitente": "12345678000190",
  "destinatario": {
    "nome": "Supermercado Exemplo Ltda", "documento": "11444777000161",
    "ie": "111222333444", "contribuinte": true,
    "endereco": { "logradouro": "Av. Brasil", "numero": "1000", "bairro": "Centro",
                  "municipio": "Araçatuba", "uf": "SP", "cep": "16010000" }
  },
  "itens": [{
    "codigo": "FERM-01", "descricao": "Fermento biológico", "quantidade": 10,
    "valor_unitario": 9.98, "ncm": "21023000", "cst_csosn": "900",
    "aliquota_icms": 18, "origem": 3, "cfop": "5202",
    "numero_item_referenciado": 2
  }],
  "operacao": {
    "natureza_operacao": "Devolução de compra",
    "finalidade_emissao": 4,
    "chave_nfe_referenciada": "35260911444777000161550010000123451123456780"
  }
}

Neste exemplo, o CSOSN 900 com alíquota de 18% destaca base de R$ 99,80 e ICMS de R$ 17,96. A chave de 44 dígitos, agrupada de 4 em 4, fica assim: 3526 0911 4447 7700 0161 5500 1000 0123 4511 2345 6780.

Transporte e comunicação

Para cte, cte_os, cte_simp, mdfe, nfcom e dce, o corpo fiscal vai dentro de documento, no mesmo formato que o painel usa. O bloco do emitente é sempre montado a partir do cadastro e substitui qualquer empresa enviada.

{
  "tipo": "cte",
  "cnpj_emitente": "12345678000190",
  "documento": { /* campos do CT-e, iguais aos da tela de emissão */ }
}

Consultar e listar

{
  "id": "920d1d7a-f721-40d7-a44b-f79af97dd208",
  "status": "authorized",
  "tipo": "nfe",
  "numero": "26",
  "pdf_url": "https://…/danfe.pdf",
  "xml_url": "https://…/35260911444777000161550010000123451123456780-nfe.xml",
  "chave_acesso": "35260911444777000161550010000123451123456780",
  "chave_nfe": "35260911444777000161550010000123451123456780",
  "mensagem": null,
  "created_at": "2026-09-30T13:47:21Z",
  "updated_at": "2026-09-30T13:50:03Z"
}

chave_acesso novo vem preenchida para documentos com chave de 44 dígitos (NF-e, CT-e, MDF-e…). Para NFS-e é null. chave_nfe continua existindo para integrações antigas. mensagem traz o motivo quando o status é rejected ou failed_internal.

Lista as notas do escritório, das mais novas para as mais antigas. page_size vai até 100 (padrão 20). A resposta traz data, page, page_size e has_more.

Diz se a nota ainda está no prazo estimado de cancelamento. É informativo e não bloqueia nada. Leia o campo confiavel: quando é false, o prazo é estimativa. NF-e: 24 horas. Transporte: 7 dias. NFS-e: null, porque o prazo é municipal, e há prefeituras que não aceitam cancelamento por sistema.

Cancelar nota

{ "justificativa": "Serviço não executado conforme contrato" }

Justificativa de 15 a 255 caracteres. A resposta é 202 com status: "processing", e a confirmação chega pelo webhook invoice.cancelled, normalmente em segundos. O 202 quer dizer "pedido enviado", não "cancelada": até a confirmação, o GET continua mostrando authorized. Nota já cancelada responde 200 com already_cancelled: true. Nota que não está autorizada responde 409 not_cancelable.

Inutilizar numeração de NF-e novo

Quando um número de NF-e foi pulado, a SEFAZ exige que ele seja inutilizado. A chamada é síncrona e a resposta já traz o resultado da SEFAZ.

{
  "cnpj_emitente": "12345678000190",
  "serie": "2",
  "numero_inicial": 15,
  "numero_final": 17,
  "justificativa": "Numeração pulada por falha no sistema de origem"
}

Regras: série de 1 a 3 dígitos, números inteiros maiores que zero, no máximo 1000 números por chamada e justificativa de 15 a 255 caracteres. Se algum número da faixa já foi transmitido pelo EasyNotas, inclusive em nota cancelada, a API recusa com 422 number_already_used antes de chegar à SEFAZ.

Autorizada, responde 201; recusada pela SEFAZ, 422. O corpo é o mesmo nos dois casos:

{
  "id": "7c1e…",
  "environment": "production",
  "status": "authorized",
  "serie": "2", "numero_inicial": 15, "numero_final": 17,
  "protocolo_sefaz": "135260001234567",
  "status_sefaz": "102",
  "mensagem_sefaz": "Inutilização de número homologado"
}

Histórico de inutilizações de produção da empresa, feitas pelo painel ou pela API (campo origem: app ou api). Tentativas recusadas também aparecem, com status: "rejected". Paginado com page e page_size.

Notas recebidas novo

O Buscador XML do EasyNotas acompanha na SEFAZ as notas que fornecedores emitem contra o CNPJ de cada empresa do escritório. A API lê o que já foi sincronizado; ela não dispara uma nova busca.

{
  "data": [{
    "chave": "35260944555666000177550010000360621003500819",
    "tipo": "nfe",
    "emitente": { "cnpj": "44555666000177", "razao_social": "Distribuidora Exemplo Ltda" },
    "cnpj_destinatario": "12345678000190",
    "valor": 1280.40,
    "data_emissao": "2026-09-12T10:31:00-03:00",
    "situacao": "autorizada",
    "nivel": "resumo",
    "manifestacao": null,
    "xml_disponivel": false,
    "recebida_em": "2026-09-12T13:40:11Z"
  }],
  "page": 1, "page_size": 20, "has_more": false
}

Busca a nota pela chave em todas as empresas do escritório. A chave tem 44 dígitos (NF-e, NFC-e, CT-e) ou 50 dígitos (NFS-e do Ambiente Nacional). Quando o XML completo existe, a resposta traz xml_url, um link de download válido por 10 minutos (xml_url_expires_in: 600). Baixe na hora e não guarde o link.

Manifestação do destinatário novo

{
  "cnpj_emitente": "12345678000190",
  "tipo": "ciencia"
}

Resposta 200:

{
  "chave": "35260944555666000177550010000360621003500819",
  "manifestacao": "ciencia",
  "xml_disponivel": true,
  "consumiu_franquia": true
}

É o mesmo processo do botão do painel: registra o evento na SEFAZ, baixa o XML quando liberado e consome a franquia do plano quando o XML é baixado. Uma nota só pode ser manifestada uma vez: a segunda chamada responde 409 already_manifested.

Webhooks

Cadastre uma URL em Configurações → API / Desenvolvedores → Webhook. O EasyNotas faz um POST quando uma nota criada por aquela chave chega a um estado final.

POST https://seu-sistema.com.br/webhooks/easynotas
X-EasyNotas-Event: invoice.authorized
X-EasyNotas-Delivery: 9f2c6a1e-…        // igual em todas as tentativas desta entrega
X-EasyNotas-Signature: t=1790780400,v1=8a1f…

{
  "event": "invoice.authorized",
  "created_at": "2026-09-30T13:50:03Z",
  "data": {
    "id": "920d1d7a-…", "status": "authorized", "tipo": "nfe",
    "environment": "production", "numero_nota": "26",
    "chave_nfe": "35260911444777000161550010000123451123456780",
    "pdf_url": "https://…", "xml_url": "https://…",
    "emitida_at": "2026-09-30T13:50:01Z", "cancelada_at": null
  }
}

O webhook traz a chave de acesso no campo chave_nfe (só dígitos), o mesmo valor que o GET devolve em chave_acesso.

Validando a assinatura

A assinatura é um HMAC-SHA256 de {t}.{corpo}, em hexadecimal, com o segredo whsec_… mostrado ao cadastrar o webhook. Cada vez que a URL é salva, um segredo novo é gerado e o anterior deixa de valer: atualize os dois juntos no seu sistema. Use o corpo bruto, exatamente como chegou, e compare em tempo constante.

const crypto = require('crypto');

function assinaturaValida(rawBody, header, secret) {
  const partes = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const esperado = crypto.createHmac('sha256', secret)
    .update(`${partes.t}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(partes.v1 || '', 'hex');
  const b = Buffer.from(esperado, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;
  return Math.abs(Date.now() / 1000 - Number(partes.t)) < 300; // recusa avisos com mais de 5 min
}

Reentrega

A entrega pode chegar mais de uma vez. Responda 2xx em até 10 segundos e processe depois. São 6 tentativas no total: a primeira na hora e as outras após 30 s, 2 min, 8 min, 32 min e cerca de 2 h. Depois disso a entrega é dada como falha. Redirecionamentos (301/302) contam como falha: a URL precisa responder 2xx direto. As entregas chegam com User-Agent: EasyNotas-Webhooks/1. Use X-EasyNotas-Delivery para descartar duplicatas. A URL precisa ser HTTPS pública na porta 443; endereços internos (localhost, 10.x, 172.16–31.x, 192.168.x, 169.254.x, 100.64.x, IPv6 local, domínios .local/.internal) e URLs com usuário e senha são recusados.

Estados fiscais

Códigos de erro

Todo erro vem como { "error": { "code", "message", "field"? } }. Nos erros de validação, field diz exatamente qual campo corrigir.

Limitações conhecidas

• Documentos de transporte ainda sem emissão real pela API.
• Carta de correção (CC-e) é feita só pelo painel.
• tomador.codigo_municipio é validado, mas o município do tomador é resolvido pelo nome da cidade.
• Os prazos de cancelamento da janela são estimativas; quem decide é a SEFAZ ou a prefeitura.
• A API lê as notas recebidas já sincronizadas; a sincronização com a SEFAZ roda no próprio EasyNotas.
• O domínio da API é o do provedor de infraestrutura. Um domínio próprio pode ser adotado no futuro, com aviso prévio.

OpenAPI

A especificação OpenAPI 3.1 (versão 1.1.0) cobre todas as rotas, os schemas e os erros. Ela está publicada em /openapi.yaml. Com ela você gera um cliente tipado na sua linguagem:

# TypeScript
npx openapi-typescript openapi.yaml -o easynotas.d.ts

# C#, PHP, Python, Java: troque o -g
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g csharp -o ./easynotas-client

Para navegar visualmente, abra o arquivo em editor.swagger.io.

Termos de Uso

O uso da API segue os Termos de Uso da API, aceitos por quem gera a chave no painel.

Suporte

Dúvidas de integração, habilitação de tipos de nota e configuração de empresas: fale com o time do EasyNotas pelo canal de suporte do seu escritório.