Como integrar o engineAPI em 30 minutos

Essa é a pergunta que mais recebemos de software houses na primeira semana: quanto tempo leva para emitir a primeira nota?

A resposta honesta: 30 minutos se você já tem o certificado A1 em mãos. Esse post documenta exatamente o que você precisa fazer, passo a passo, sem enrolação.

O que você vai precisar

• Conta no engineAPI (plano dev, gratuito)
• Certificado digital A1 do emissor (arquivo .pfx e a senha)
• CNPJ ativo em ambiente de homologação no SEFAZ (ou use um dos nossos CNPJs de teste)
• Terminal com curl ou qualquer cliente HTTP (Insomnia, Postman, etc.)

Passo 1 — Criar sua conta (2 min)

Acesse app.engineapi.com.br e cadastre seu partner. O plano dev não pede cartão de crédito e já dá acesso ao sandbox de homologação.

Após o cadastro, copie sua API Key no dashboard em Configurações → API Keys.

# Guarde sua API Key como variável de ambiente
export ENGINEAPI_KEY="ea_live_xxxxxxxxxxxxxxxx"

Passo 2 — Cadastrar o emissor (5 min)

No dashboard, vá em Emissores → Novo Emissor e informe:

• CNPJ do emissor
• Razão Social e Nome Fantasia
• Endereço completo (necessário para o XML da NF-e)
• Regime Tributário (Simples Nacional, Lucro Presumido, etc.)
• Ambiente: Homologação (mude para Produção só quando estiver tudo validado)

Ou via API:

curl -X POST https://api.engineapi.com.br/v1/issuers \
  -H "X-API-Key: $ENGINEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12.345.678/0001-90",
    "name": "Empresa Teste Ltda.",
    "trade_name": "Empresa Teste",
    "tax_regime": "SIMPLES",
    "environment": "HOMOLOGATION",
    "address": {
      "street": "Rua Teste", "number": "100",
      "district": "Centro", "city_code": "3550308",
      "state": "SP", "postal_code": "01310-100"
    }
  }'

Guarde o issuer_id retornado.

Passo 3 — Upload do certificado A1 (3 min)

curl -X POST https://api.engineapi.com.br/v1/issuers/{issuer_id}/certificate \
  -H "X-API-Key: $ENGINEAPI_KEY" \
  -F "file=@/caminho/para/certificado.pfx" \
  -F "password=SUA_SENHA_DO_CERTIFICADO"

O certificado é criptografado com AES-256 antes de ser persistido. Você verá a data de validade no dashboard logo após o upload.

Passo 4 — Emitir a primeira NF-e (5 min)

curl -X POST https://api.engineapi.com.br/v1/nfe/emit \
  -H "X-API-Key: $ENGINEAPI_KEY" \
  -H "X-Issuer-Id: {issuer_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "nature_of_operation": "Venda de mercadoria",
    "recipient": {
      "document": "98.765.432/0001-10",
      "name": "Cliente Teste Ltda.",
      "address": {
        "street": "Rua Cliente", "number": "200",
        "district": "Bairro", "city_code": "3550308",
        "state": "SP", "postal_code": "01310-200"
      }
    },
    "items": [{
      "code": "PROD001",
      "description": "Produto de Teste",
      "ncm": "84713012",
      "cfop": "5102",
      "unit": "UN",
      "quantity": 1,
      "unit_value": 100.00,
      "total_value": 100.00
    }],
    "payment": {
      "method": "MONEY",
      "total": 100.00
    }
  }'

Se tudo correu bem, você recebe de volta:

{
  "nfe_key": "35260512345678000190550010000012341234567890",
  "nfe_number": "1234",
  "series": "1",
  "status": "AUTHORIZED",
  "authorization_date": "2026-05-20T14:32:00Z",
  "xml_url": "https://storage.engineapi.com.br/...",
  "danfe_url": "https://storage.engineapi.com.br/..."
}

Passo 5 — Configurar webhooks (5 min)

Para receber eventos em tempo real (NF-e autorizada, cancelada, etc.):

curl -X POST https://api.engineapi.com.br/v1/webhooks \
  -H "X-API-Key: $ENGINEAPI_KEY" \
  -d '{
    "url": "https://seu-sistema.com.br/webhooks/engineapi",
    "events": ["nfe.authorized", "nfe.cancelled", "nfe.error"],
    "secret": "seu_webhook_secret"
  }'

O engineAPI assina cada payload com HMAC-SHA256 usando o secret que você definiu.

Próximos passos

Com a primeira NF-e emitida em homologação, você está pronto para:

1. Emitir em produção — mude environment do emissor para PRODUCTION
2. Integrar NFS-e — mesma estrutura, endpoint /v1/nfse/emit
3. Configurar o MCP Server — para integrar com agentes de IA e automações n8n

Qualquer dúvida, fale com o suporte em suporte@engineapi.com.br.