Guia de Início Rápido (Quickstart)

Este tutorial conduz você do zero até a emissão da sua primeira NF-e (Nota Fiscal Eletrônica) em ambiente de homologação.

---

1. Obtenha sua API Key

Toda requisição deve ser autenticada por um cabeçalho x-api-key.

AMBIENTE DE TESTES

No ambiente local ou de desenvolvimento, você pode utilizar a chave de demonstração padrão: test_api_key_12345

---

2. Emita sua primeira Nota Fiscal

Envie uma requisição POST /v1/invoices/nfe com os dados do emitente, destinatário e itens da nota:

cURL

curl --request POST \
  --url http://localhost:3333/v1/invoices/nfe \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: test_api_key_12345' \
  --header 'Idempotency-Key: req-exemplo-001' \
  --data '{
    "naturezaOperacao": "VENDA DE MERCADORIA",
    "recipient": {
      "cnpjCpf": "11222333000181",
      "legalName": "CLIENTE TESTE LTDA",
      "street": "Av Paulista",
      "number": "1000",
      "neighborhood": "Bela Vista",
      "cityCode": "3550308",
      "cityName": "São Paulo",
      "state": "SP",
      "zipCode": "01310100"
    },
    "items": [
      {
        "code": "PROD-001",
        "description": "Livro Técnico de Programação",
        "ncm": "49019900",
        "cfop": "5102",
        "unit": "UN",
        "quantity": 1,
        "unitPrice": 150.00,
        "icms": { "cst": "102", "orig": 0 },
        "pis": { "cst": "07" },
        "cofins": { "cst": "07" }
      }
    ],
    "payments": [
      { "paymentType": "01", "amount": 150.00 }
    ]
  }'

Node.js (TypeScript)

import axios from 'axios';

const response = await axios.post(
  'http://localhost:3333/v1/invoices/nfe',
  {
    naturezaOperacao: 'VENDA DE MERCADORIA',
    recipient: {
      cnpjCpf: '11222333000181',
      legalName: 'CLIENTE TESTE LTDA',
      street: 'Av Paulista',
      number: '1000',
      neighborhood: 'Bela Vista',
      cityCode: '3550308',
      cityName: 'São Paulo',
      state: 'SP',
      zipCode: '01310100'
    },
    items: [
      {
        code: 'PROD-001',
        description: 'Livro Técnico de Programação',
        ncm: '49019900',
        cfop: '5102',
        unit: 'UN',
        quantity: 1,
        unitPrice: 150.00,
        icms: { cst: '102', orig: 0 },
        pis: { cst: '07' },
        cofins: { cst: '07' }
      }
    ],
    payments: [{ paymentType: '01', amount: 150.00 }]
  },
  {
    headers: {
      'x-api-key': 'test_api_key_12345',
      'Idempotency-Key': 'req-exemplo-001'
    }
  }
);

console.log('Chave de Acesso:', response.data.data.accessKey);
console.log('Status SEFAZ:', response.data.data.cStat);

Python

import requests

url = "http://localhost:3333/v1/invoices/nfe"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "test_api_key_12345",
    "Idempotency-Key": "req-exemplo-001"
}
payload = {
    "naturezaOperacao": "VENDA DE MERCADORIA",
    "recipient": {
        "cnpjCpf": "11222333000181",
        "legalName": "CLIENTE TESTE LTDA",
        "street": "Av Paulista",
        "number": "1000",
        "neighborhood": "Bela Vista",
        "cityCode": "3550308",
        "cityName": "São Paulo",
        "state": "SP",
        "zipCode": "01310100"
    },
    "items": [
        {
            "code": "PROD-001",
            "description": "Livro Técnico de Programação",
            "ncm": "49019900",
            "cfop": "5102",
            "unit": "UN",
            "quantity": 1,
            "unitPrice": 150.00,
            "icms": {"cst": "102", "orig": 0},
            "pis": {"cst": "07"},
            "cofins": {"cst": "07"}
        }
    ],
    "payments": [{"paymentType": "01", "amount": 150.00}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

---

3. Estrutura do Retorno

Quando a nota é autorizada com sucesso pela SEFAZ (cStat: 100), a resposta traz a chave de acesso oficial de 44 dígitos e os dados de protocolo:

{
  "id": "clt1983hx0001va93jflam789",
  "status": "AUTORIZADA",
  "cStat": 100,
  "xMotivo": "Autorizado o uso da NF-e",
  "chaveAcesso": "35261011222333000181550010000000011987654321",
  "protocolo": "135260000012345",
  "dataEmissao": "2026-10-07T10:20:00.000Z",
  "pdfUrl": "http://localhost:3333/v1/invoices/clt1983hx0001va93jflam789/pdf",
  "xmlUrl": "http://localhost:3333/v1/invoices/clt1983hx0001va93jflam789/xml"
}

---

4. Download do DANFE em PDF

Para baixar o PDF gerado no padrão oficial:

curl --request GET \
  --url http://localhost:3333/v1/invoices/clt1983hx0001va93jflam789/pdf \
  --header 'x-api-key: test_api_key_12345' \
  --output danfe.pdf