NFER
Visão GeralAutenticaçãoQuick StartChangelogConceitosEndpointsWebhooksErrosEmpresaCadastrosNumeraçãoPlanos

Quick Start

Da API Key à primeira NF-e autorizada.

Emita sua primeira NF-e em 4 passos. A autorização na SEFAZ é assíncrona: você cria o rascunho, enfileira o envio e recebe um webhook (recomendado) — ou faz polling a cada 3–5 s até o status terminal.

  1. 1 · API Key
  2. 2 · Cliente
  3. 3 · Criar NF-e
  4. 4 · Send + poll
1

Obter API Key

No cadastro (Criar conta) ou via POST /v1/companies, a API Key é exibida uma única vez. Guarde com segurança.

Formato

<8-chars-do-uuid>.<segredo> — ex.: a0eebc99.super-secret-key-123
2

Cliente (opcional se usar customer inline)

Pode cadastrar o cliente antes ou enviar customer direto no POST /v1/nfe. O cMun pode vir no payload ou ser resolvido (UF+cidade / CEP) na base IBGE local.

POST/v1/customers
POST /v1/customersbash
curl -X POST https://api.nfer.me/v1/customers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NFER_KEY" \
  -d '{
    "nome": "Cliente Exemplo LTDA",
    "cpfCnpj": "00000000000191",
    "tipoPessoa": "J",
    "endereco": {
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "cMun": "4106902",
      "xMun": "Curitiba",
      "UF": "PR",
      "CEP": "80010000"
    }
  }'
201 Createdjson
{
  "id": "uuid-do-cliente",
  "nome": "Cliente Exemplo LTDA",
  "cpf_cnpj": "00000000000191"
}
3

Criar rascunho da NF-e

Modo smart: informe customerId ou customer inline, e fiscalProfileId no item. O número da nota é reservado na hora.

POST/v1/nfe
POST /v1/nfe — customerIdbash
curl -X POST https://api.nfer.me/v1/nfe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NFER_KEY" \
  -d '{
    "customerId": "UUID-DO-CLIENTE",
    "naturezaOperacao": "VENDA DE MERCADORIA",
    "tipoOperacao": "1",
    "finalidade": 1,
    "serie": 1,
    "transporte": { "modFrete": 9 },
    "itens": [{
      "fiscalProfileId": "UUID-DO-PERFIL",
      "codigo": "SKU-001",
      "descricao": "PRODUTO TESTE",
      "quantidade": 2,
      "valorUnitario": 125.50,
      "ncm": "61091000",
      "unidade": "UN"
    }],
    "pagamentos": [{ "forma": "01", "valor": 251.00 }]
  }'
POST /v1/nfe — customer inlinebash
curl -X POST https://api.nfer.me/v1/nfe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NFER_KEY" \
  -d '{
    "customer": {
      "cpfCnpj": "00000000000191",
      "nome": "Cliente Exemplo LTDA",
      "endereco": {
        "logradouro": "Rua Exemplo",
        "numero": "100",
        "bairro": "Centro",
        "xMun": "Cianorte",
        "UF": "PR",
        "CEP": "87200000"
      }
    },
    "naturezaOperacao": "VENDA DE MERCADORIA",
    "tipoOperacao": "1",
    "finalidade": 1,
    "itens": [{
      "fiscalProfileId": "UUID-DO-PERFIL",
      "descricao": "PRODUTO TESTE",
      "quantidade": 1,
      "valorUnitario": 100,
      "ncm": "61091000",
      "unidade": "UN"
    }],
    "pagamentos": [{ "forma": "01", "valor": 100 }]
  }'
201 — rascunhojson
{
  "id": "uuid-da-nfe",
  "status": "rascunho",
  "numero": 143,
  "serie": 1
}
4

Enviar à SEFAZ e acompanhar

POST /v1/nfe/:id/send responde 202 e Preferência: cadastre um webhook. Sem webhook, faça polling em GET /v1/nfe/:id a cada 3–5 s até sair de processando (não menos que 3 s — rate limit da API).

POST/v1/nfe/:id/send
GET/v1/nfe/:id
POST /v1/nfe/:id/sendbash
curl -X POST https://api.nfer.me/v1/nfe/$NFE_ID/send \
  -H "X-API-Key: $NFER_KEY"
202 Acceptedjson
{
  "message": "NF-e queued for sending",
  "jobId": "job-uuid",
  "status": "processando"
}
GET — autorizadajson
{
  "id": "uuid-da-nfe",
  "status": "autorizada",
  "chave_acesso": "4126...",
  "numero": 143
}
AnteriorAutenticaçãoPróximoChangelog