Quickstart
Emita sua primeira nota fiscal em homologação em minutos.
Quickstart
Siga os 4 passos abaixo. Sem falar com ninguém: cadastro, empresa, certificado e emissão são todos self-service.
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.
Crie sua conta
POST /v1/auth/register cria sua conta completa em uma chamada: seu partner (a software
house), um usuário ADMIN, o plano Dev (R$0, ativo na hora) e uma API Key de teste
(ek_test_...), tudo na mesma resposta.
A senha precisa ter de 8 a 72 caracteres, com pelo menos uma letra e um número, e não pode ser uma das senhas mais comuns (recusamos coisas como "12345678" ou "senha123"). Senha fora da regra volta 400 com a mensagem do que falta. A mesma regra vale para redefinir senha, trocar senha e aceitar convite de equipe.
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",
"password": "senhaSegura123"
}'
{
"data": {
"message": "Conta criada com sucesso (plano Dev ativo)",
"partnerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"plan": "dev",
"apiKeyTest": "ek_test_9f8e7d6c-5b4a-3210-fedc-ba9876543210",
"apiKeyTestPrefix": "ek_test_9f8e",
"warning": "A ek_test_ é mostrada apenas uma vez. Armazene em local seguro.",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "u1b2c3d4-e5f6-7890-abcd-ef1234567890",
"email": "dev@minhaempresa.com",
"name": "Dev Exemplo",
"partnerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"role": "ADMIN"
}
},
"meta": {
"requestId": "req_abc123",
"timestamp": "2026-07-06T12:00:00.000Z"
}
}
A ek_test_ só aparece nesta resposta (o backend guarda só o hash). Guarde-a agora;
se perder, gere outra em POST /v1/auth/api-keys/test/regenerate (precisa do
access_token). O cadastro nunca emite ek_live_: a key de produção exige assinatura de
plano pago, ver Autenticação.
A resposta também traz access_token (JWT), útil para o dashboard. Os próximos passos
usam x-api-key com a ek_test_, o formato recomendado para integração server-to-server
(o público desta doc). Ver Autenticação para os dois métodos.
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 -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"
}'
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 -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"
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 NFe
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: NFe. Emitindo NFCe ou NFSe? Veja os catálogos de NFCe e NFSe.
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 }]
}'
{
"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 NFe/NFCe/NFSe: 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.