Primeiros passos

Siga os 4 passos abaixo. O acesso é por pedido revisado (sem cartão, sem agente comercial); empresa, certificado e emissão são self-service assim que seu acesso é liberado.

Todo emissor nasce em homologação (SEFAZ de teste, sem validade fiscal). Não existe um campo environment que você define no cadastro. Ver Sandbox para o que isso significa na prática e como ir pra produção.

Antes de integrar o cenário do seu cliente: confira se o regime tributário e a operação dele (ST, DIFAL, exportação, transporte…) já emitem hoje em Cobertura Fiscal, documento × regime × cenário, com o erro exato onde não emite.

Peça acesso e gere sua API Key

POST /v1/auth/register não cria conta na hora: grava um pedido de acesso antecipado e responde 202. Nosso time revisa e, se liberar, você recebe um e-mail de convite para criar sua senha: aí sim nasce seu partner (a software house), com o plano Dev (R$0) já ativo.

cURL
Node.js
Python

curl -X POST https://api.engineapi.com.br/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Minha Software House Ltda",
    "name": "Dev Exemplo",
    "email": "dev@minhaempresa.com",
    "whatsapp": "11988887777",
    "emits": "NFe e NFCe para os clientes da minha plataforma",
    "volumePerMonth": "500",
    "erpStack": "Node + Postgres"
  }'

const resp = await fetch('https://api.engineapi.com.br/v1/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    companyName: 'Minha Software House Ltda',
    name: 'Dev Exemplo',
    email: 'dev@minhaempresa.com',
    whatsapp: '11988887777',
    emits: 'NFe e NFCe para os clientes da minha plataforma',
    volumePerMonth: '500',
    erpStack: 'Node + Postgres',
  }),
});

const { data } = await resp.json();
console.log(data.message); // "Pedido de acesso recebido. ..."

import httpx

resp = httpx.post('https://api.engineapi.com.br/v1/auth/register', json={
    'companyName': 'Minha Software House Ltda',
    'name': 'Dev Exemplo',
    'email': 'dev@minhaempresa.com',
    'whatsapp': '11988887777',
    'emits': 'NFe e NFCe para os clientes da minha plataforma',
    'volumePerMonth': '500',
    'erpStack': 'Node + Postgres',
})

print(resp.json()['data']['message'])

whatsapp exige DDD completo: 10 dígitos (fixo) ou 11 (celular, com o nono dígito). A validação ignora máscara, aceitando tanto dígitos crus (11988887777) quanto formatado ((11) 98888-7777), mas rejeita telefone incompleto (ex.: 11).

Resposta de sucesso (202)

{
  "data": {
    "message": "Pedido de acesso recebido. Nossa equipe vai analisar e entrar em contato em breve.",
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-07-06T12:00:00.000Z"
  }
}

Liberado? O e-mail de convite traz um link para criar a senha (POST /v1/invite/accept). Depois de entrar no dashboard, gere sua ek_test_ em Configurações → API Keys (ou via POST /v1/auth/api-keys/test/regenerate, autenticado). Ela só aparece uma vez: guarde-a. Nenhum caminho de acesso antecipado emite ek_live_: a key de produção exige assinatura de plano pago, ver Autenticação.

Cadastre uma empresa emissora

Registre o CNPJ que vai emitir os documentos fiscais. A empresa nasce em homologação; guarde o id retornado: é o issuerId usado para escolher o emissor na emissão (opcional com um único emissor, obrigatório a partir do segundo).

cURL
Node.js
Python

curl -X POST https://api.engineapi.com.br/v1/companies \
  -H "x-api-key: ek_test_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "11222333000181",
    "name": "Empresa Exemplo Ltda",
    "tradeName": "Exemplo",
    "ie": "123456789",
    "crt": 1,
    "cep": "74063010",
    "address": "Rua Exemplo",
    "number": "100",
    "neighborhood": "Centro",
    "city": "Goiânia",
    "state": "GO",
    "ibgeCode": "5208707"
  }'

const resp = await fetch('https://api.engineapi.com.br/v1/companies', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    cnpj: '11222333000181',
    name: 'Empresa Exemplo Ltda',
    tradeName: 'Exemplo',
    ie: '123456789',
    crt: 1, // 1=Simples Nacional, 3=Regime Normal (ver /conceitos/regimes-tributarios)
    cep: '74063010',
    address: 'Rua Exemplo',
    number: '100',
    neighborhood: 'Centro',
    city: 'Goiânia',
    state: 'GO',
    ibgeCode: '5208707',
  }),
});

const { data } = await resp.json();
const issuerId = data.id;

resp = httpx.post('https://api.engineapi.com.br/v1/companies',
    headers={'x-api-key': api_key},
    json={
        'cnpj': '11222333000181',
        'name': 'Empresa Exemplo Ltda',
        'tradeName': 'Exemplo',
        'ie': '123456789',
        'crt': 1,
        'cep': '74063010',
        'address': 'Rua Exemplo',
        'number': '100',
        'neighborhood': 'Centro',
        'city': 'Goiânia',
        'state': 'GO',
        'ibgeCode': '5208707',
    },
)

issuer_id = resp.json()['data']['id']

O payload usa cep/address/number/neighborhood/city/state/ibgeCode em campos soltos na raiz (não um objeto address.{street,district,cityCode,zipCode}), e crt (não taxRegime). Não existe campo environment, todo emissor nasce em homologação, ver Sandbox.

Faça upload do certificado digital

Envie o certificado .pfx (A1) da empresa emissora. Ele será criptografado e armazenado com segurança.

cURL
Node.js
Python

curl -X POST https://api.engineapi.com.br/v1/companies/ISSUER_ID/certificate \
  -H "x-api-key: ek_test_SUA_API_KEY" \
  -F "file=@certificado.pfx" \
  -F "password=senhaDoCertificado"

import { readFileSync } from 'fs';

const form = new FormData();
form.append('file', new Blob([readFileSync('certificado.pfx')]));
form.append('password', 'senhaDoCertificado');

await fetch(`https://api.engineapi.com.br/v1/companies/${issuerId}/certificate`, {
  method: 'POST',
  headers: { 'x-api-key': apiKey },
  body: form,
});

with open('certificado.pfx', 'rb') as f:
    resp = httpx.post(
        f'https://api.engineapi.com.br/v1/companies/{issuer_id}/certificate',
        headers={'x-api-key': api_key},
        files={'file': ('cert.pfx', f, 'application/x-pkcs12')},
        data={'password': 'senhaDoCertificado'},
    )

O campo multipart é file, não certificate.

Não tem certificado digital para testes? Em homologação, você pode usar um certificado de teste emitido por qualquer AC (Autoridade Certificadora) habilitada. Veja nosso guia de certificados.

Emita sua primeira NF-e

Com a empresa e o certificado configurados, emita a nota.

Quais campos enviar? O exemplo abaixo cobre o mínimo. A lista completa de campos de emissão, navegável por grupo (Identificação, Destinatário, Itens, Impostos, Transporte, Pagamento…), gerada direto do contrato real, está no Catálogo de campos: NF-e. Emitindo NFC-e ou NFS-e? Veja os catálogos de NFC-e e NFS-e.

cURL
Node.js
Python

curl -X POST https://api.engineapi.com.br/v1/nfe \
  -H "x-api-key: ek_test_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "naturezaOperacao": "VENDA DE MERCADORIA",
    "idDest": 1,
    "indFinal": 1,
    "destinatario": {
      "cnpjCpf": "99888777000100",
      "nome": "Cliente Exemplo SA",
      "endereco": {
        "logradouro": "Av Goiás", "numero": "500",
        "bairro": "Centro", "codigoMunicipio": "5208707",
        "municipio": "Goiânia", "uf": "GO", "cep": "74063010"
      },
      "indicadorIE": 9
    },
    "items": [{
      "codigo": "PROD001",
      "descricao": "Produto Teste",
      "ncm": "84713012",
      "cfop": "5102",
      "unidade": "UN",
      "quantidade": 2,
      "valorUnitario": 150.00,
      "icms": { "origem": 0, "csosn": "400" }
    }],
    "pagamentos": [{ "forma": "01", "valor": 300.00 }]
  }'

const resp = await fetch('https://api.engineapi.com.br/v1/nfe', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    naturezaOperacao: 'VENDA DE MERCADORIA',
    idDest: 1,
    indFinal: 1,
    destinatario: {
      cnpjCpf: '99888777000100',
      nome: 'Cliente Exemplo SA',
      endereco: {
        logradouro: 'Av Goiás', numero: '500',
        bairro: 'Centro', codigoMunicipio: '5208707',
        municipio: 'Goiânia', uf: 'GO', cep: '74063010',
      },
      indicadorIE: 9,
    },
    items: [{
      codigo: 'PROD001', descricao: 'Produto Teste',
      ncm: '84713012', cfop: '5102', unidade: 'UN',
      quantidade: 2, valorUnitario: 150.00,
      icms: { origem: 0, csosn: '400' },
    }],
    pagamentos: [{ forma: '01', valor: 300.00 }],
  }),
});

const { data } = await resp.json();
console.log('NFe autorizada:', data.accessKey, data.status);

resp = httpx.post('https://api.engineapi.com.br/v1/nfe',
    headers={'x-api-key': api_key},
    json={
        'naturezaOperacao': 'VENDA DE MERCADORIA',
        'idDest': 1,
        'indFinal': 1,
        'destinatario': {
            'cnpjCpf': '99888777000100',
            'nome': 'Cliente Exemplo SA',
            'endereco': {
                'logradouro': 'Av Goiás', 'numero': '500',
                'bairro': 'Centro', 'codigoMunicipio': '5208707',
                'municipio': 'Goiânia', 'uf': 'GO', 'cep': '74063010',
            },
            'indicadorIE': 9,
        },
        'items': [{
            'codigo': 'PROD001', 'descricao': 'Produto Teste',
            'ncm': '84713012', 'cfop': '5102', 'unidade': 'UN',
            'quantidade': 2, 'valorUnitario': 150.00,
            'icms': {'origem': 0, 'csosn': '400'},
        }],
        'pagamentos': [{'forma': '01', 'valor': 300.00}],
    },
)

data = resp.json()['data']
print(f"NFe autorizada: {data['accessKey']}")

Resposta de sucesso

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "AUTHORIZED",
    "accessKey": "35260211222333000181550010000000011000000019",
    "protocol": "135260000001234",
    "number": 1,
    "series": 1,
    "model": "55",
    "amount": "300",
    "destCNPJ": "99888777000100",
    "destName": "Cliente Exemplo SA",
    "createdAt": "2026-07-06T12:00:00.000Z",
    "updatedAt": "2026-07-06T12:00:01.000Z",
    "downloads": {
      "xml": "/v1/nfe/xml/35260211222333000181550010000000011000000019",
      "pdf": "/v1/nfe/pdf/35260211222333000181550010000000011000000019"
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-07-06T12:00:00.000Z"
  }
}

issuerId (UUID) é aceito na RAIZ do payload de NF-e/NFC-e/NFS-e: opcional se você tem um único emissor (a API usa o seu emissor), obrigatório a partir do segundo emissor (sem ele, 400). Não existe itens/pagamento singular/cnpj separados: os nomes reais são items/pagamentos[]/cnpjCpf. Ver Autenticação e Primeira Emissão para o contrato completo.

A resposta não tem xml/xmlPath/pdfPath/invoiceId/message: esses campos da versão antiga da doc nunca existiram no shape real (ou eram caminho de arquivo interno). status é "AUTHORIZED" (inglês, mesmo valor usado em GET /v1/nfe/{id} e no webhook invoice.authorized), amount é uma string decimal ("300", sem zeros à direita, não number, evita imprecisão de ponto flutuante em dinheiro), e downloads.xml/downloads.pdf são os caminhos para baixar o XML/PDF (GET /v1/nfe/xml/{accessKey}, GET /v1/nfe/pdf/{accessKey}).

Sua primeira nota fiscal foi emitida e autorizada pelo SEFAZ de homologação.

Próximos passos

Catálogo de campos

Todo campo de NF-e/NFC-e/NFS-e, navegável por grupo, gerado do contrato real

Autenticação

JWT, API Keys e multi-tenancy explicados

Primeira Emissão

Todos os campos obrigatórios detalhados

Webhooks

Notificações em tempo real de cada evento

Comece aqui

Emissão

Tributação

Erros e operação

IA e automação

Conceitos

Migração

Perguntas frequentes

Próximos passos

Catálogo de campos

Autenticação

Primeira Emissão

Webhooks

​Próximos passos

Catálogo de campos

Autenticação

Primeira Emissão

Webhooks

Próximos passos