Primeira Emissão
Guia completo para emitir seu primeiro documento fiscal. Todos os campos obrigatórios, erros comuns e melhores práticas.
Primeira Emissão
Antes de emitir sua primeira NFe em produção, você precisa ter três coisas prontas. Sem uma delas, a emissão vai falhar.
Conta criada
Partner registrado e token JWT em mãos
Empresa cadastrada
CNPJ emissor cadastrado e com issuerId
Certificado enviado
Arquivo .pfx (A1) com senha válida
Não tem os três? Volte para o Quickstart e siga os passos.
Checklist de pré-requisitos
Token JWT disponível
Você tem o retorno de POST /auth/login ou POST /auth/register-partner?
Guarde o campo token.
issuerId disponível
Você tem o ID da empresa emissora? É retornado em POST /companies.
Formato: UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
Certificado enviado
Você já fez POST /companies/{issuerId}/certificate?
Se sim, a resposta foi 200 OK sem erros de senha?
Ambiente definido
Sua empresa está em environment: 2 (homologação) ou environment: 1 (produção)?
Para o primeiro teste, use sempre homologação.
Estrutura de uma NFe
Uma NFe é composta por 5 blocos obrigatórios:
NFe
├── 1. Identificação (natureza, data, série, número)
├── 2. Emissor (issuerId já resolve isso automaticamente)
├── 3. Destinatário (CNPJ/CPF, nome, endereço)
├── 4. Itens (produtos, NCM, CFOP, impostos)
└── 5. Pagamento (forma, valor)
Campos obrigatórios
Raiz da nota
| Campo | Tipo | Obrigatório | Exemplo |
|-------|------|-------------|---------|
| issuerId | UUID | Sim | "3fa85f64-..." |
| naturezaOperacao | string | Sim | "VENDA DE MERCADORIA" |
| destinatario | objeto | Sim | ver abaixo |
| itens | array | Sim | mínimo 1 item |
| pagamento | objeto | Sim | ver abaixo |
Destinatário
| Campo | Tipo | Obrigatório | Exemplo |
|-------|------|-------------|---------|
| cnpj ou cpf | string | Sim (um dos dois) | "99888777000155" |
| nome | string | Sim | "Cliente Exemplo SA" |
| indicadorIE | número | Sim | 1 = contribuinte, 9 = não contribuinte |
| endereco.logradouro | string | Sim | "Av Brasil" |
| endereco.numero | string | Sim | "500" |
| endereco.bairro | string | Sim | "Centro" |
| endereco.codigoMunicipio | string | Sim | "3550308" (São Paulo) |
| endereco.municipio | string | Sim | "São Paulo" |
| endereco.uf | string | Sim | "SP" |
| endereco.cep | string | Sim | "01001000" |
Item
| Campo | Tipo | Obrigatório | Exemplo |
|-------|------|-------------|---------|
| numero | número | Sim | 1 |
| codigo | string | Sim | "PROD001" |
| descricao | string | Sim | "Produto Teste" |
| ncm | string | Sim | "84713012" (8 dígitos) |
| cfop | string | Sim | "5102" (venda interna) |
| unidade | string | Sim | "UN" |
| quantidade | número | Sim | 2 |
| valorUnitario | número | Sim | 150.00 |
| valorTotal | número | Sim | 300.00 |
| icms | objeto | Sim | ver abaixo |
ICMS simplificado (Simples Nacional)
"icms": {
"origem": 0,
"csosn": "400"
}
ICMS completo (Lucro Real / Lucro Presumido)
"icms": {
"origem": 0,
"cst": "00",
"aliquota": 18,
"baseCalculo": 300.00,
"valor": 54.00
}
Pagamento
| Campo | Tipo | Valores |
|-------|------|---------|
| forma | string | "01" Dinheiro, "03" Cartão crédito, "04" Cartão débito, "15" Boleto, "99" Outros |
| valor | número | Total da nota |
Exemplo completo mínimo
curl -X POST https://api.engineapi.com.br/nfe/emitir \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"issuerId": "SEU_ISSUER_ID",
"naturezaOperacao": "VENDA DE MERCADORIA",
"destinatario": {
"cnpj": "99888777000155",
"nome": "Cliente Exemplo SA",
"indicadorIE": 1,
"endereco": {
"logradouro": "Av Brasil",
"numero": "500",
"bairro": "Centro",
"codigoMunicipio": "3550308",
"municipio": "São Paulo",
"uf": "SP",
"cep": "01001000"
}
},
"itens": [{
"numero": 1,
"codigo": "PROD001",
"descricao": "Produto Teste",
"ncm": "84713012",
"cfop": "5102",
"unidade": "UN",
"quantidade": 1,
"valorUnitario": 100.00,
"valorTotal": 100.00,
"icms": {
"origem": 0,
"csosn": "400"
}
}],
"pagamento": {
"forma": "01",
"valor": 100.00
}
}'
Resposta de sucesso
{
"success": true,
"invoice": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"accessKey": "35260211222333000144550010000000011000000019",
"number": 1,
"series": 1,
"status": "AUTHORIZED",
"danfeUrl": "/nfe/3fa85f64.../danfe"
}
}
NFe com status: "AUTHORIZED" está aprovada pela SEFAZ e tem validade fiscal.
Erros mais comuns nesta etapa
| Erro | Causa | Solução |
|------|-------|---------|
| 400 Certificado não encontrado | Nenhum .pfx enviado para o issuerId | Faça POST /companies/{issuerId}/certificate |
| 400 Senha do certificado inválida | Senha errada no upload | Reenvie com a senha correta |
| 422 Rejeição 225 | Campo NCM ou CFOP inválido | Verifique a tabela de CFOP |
| 422 Rejeição 539 | Nota duplicada (mesmo número/série) | Incremente o número da nota |
| 422 Rejeição 999 | SEFAZ de homologação fora do ar | Tente novamente em alguns minutos |
| 401 Token inválido | Token expirado (24h) | Faça login novamente |