Guia rápido

Da chave de API à primeira nota autorizada. Pré-requisitos no portal: emitente cadastrado com certificado A1 válido (ambiente homologação para testar) e a matriz de impostos configurada para a operação.

export BASE="https://SEU-DOMINIO/api/integracao"
export KEY="enfe_..."   # criada em Administração → Integração

1. Sincronize os cadastros (upsert)

# Produto
curl -X PUT "$BASE/produtos/CANETA-AZ" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "descricao": "Caneta esferográfica azul",
    "ncm": "96081000",
    "unidadeComercial": "UN",
    "valorUnitario": 2.50,
    "origemMercadoria": 0
  }'

# Cliente (a rota usa o CPF/CNPJ como identificador)
curl -X PUT "$BASE/clientes/12345678000190" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "tipoPessoa": 1,
    "razaoSocial": "Cliente Exemplo LTDA",
    "indicadorIe": 9,
    "email": "fiscal@clienteexemplo.com.br",
    "endereco": {
      "logradouro": "Av. Exemplo", "numero": "100", "bairro": "Centro",
      "municipio": "São Paulo", "codigoMunicipioIbge": "3550308",
      "uf": "SP", "cep": "01000-000"
    }
  }'

# Operação fiscal
curl -X PUT "$BASE/operacoes-fiscais/VENDA" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ "descricao": "Venda de mercadoria", "tipoOperacao": 1, "finalidade": 1,
        "consumidorFinal": true, "cfopDentroEstado": "5102", "cfopForaEstado": "6102" }'

PUT é idempotente: não existe → cria; existe → atualiza. Rode quantas vezes quiser.

2. Emita a nota

curl -X POST "$BASE/emissoes" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "referenciaExterna": "pedido-1001",
    "cnpjEmitente": "43636483000128",
    "cpfCnpjCliente": "12345678000190",
    "codigoOperacao": "VENDA",
    "itens": [
      { "codigoProduto": "CANETA-AZ", "quantidade": 100, "valorUnitario": 2.50 }
    ],
    "pagamentos": [ { "forma": "17", "valor": 250.00, "aVista": true } ]
  }'

Resposta:

HTTP/1.1 202 Accepted
{ "jobId": "0e63b9a4-...", "status": "Pendente" }

referenciaExterna (ex.: o nº do pedido) garante idempotência: reenviar o mesmo POST devolve o mesmo job, sem emitir duas vezes.

3. Acompanhe o job

curl -H "X-Api-Key: $KEY" "$BASE/emissoes/0e63b9a4-..."

{
  "jobId": "0e63b9a4-...",
  "tipo": "Emissao",
  "status": "Concluido",
  "referenciaExterna": "pedido-1001",
  "resultado": {
    "chaveAcesso": "35260643636483000128550010000000011234567890",
    "numero": 1, "serie": 1, "protocolo": "135260000000001"
  }
}

Polling sugerido: a cada 2–5 s, com desistência amigável após ~2 min. Melhor ainda: configure um webhook e seja avisado na conclusão.

4. Baixe XML e DANFE

curl -H "X-Api-Key: $KEY" "$BASE/notas/35260.../xml"   -o nota.xml
curl -H "X-Api-Key: $KEY" "$BASE/notas/35260.../danfe" -o danfe.pdf

Pronto. Próximos passos: emissão completa e eventos (frete, transporte, duplicatas, cancelamento, CC-e) e tratamento de erros.

Prefere testar sem sair do navegador? Use o Sandbox — os mesmos exemplos, prontos para enviar com a sua chave.