Início rápido de NF-e

Tudo com a chave de teste (sdr_test_): a nota vai de verdade à homologação da SEFAZ, sem valor fiscal e sem cobrança, e o cadastro de produtos do sandbox é separado do de produção. Nos exemplos, a chave está em SUDREL_API_KEY e o id da empresa (de GET /v1/companies) em EMPRESA. Prefere clicar a copiar curl? A mesma sequência está na coleção do Postman.

1. Prontidão. Certificado A1 do CNPJ, inscrição estadual ativa na SEFAZ, endereço completo e regime tributário:

curl https://api.sudrel.com.br/api/v1/nfe/prontidao/$EMPRESA \
  -H "Authorization: Bearer $SUDREL_API_KEY"

2. Produto. Cadastre uma vez; NCM, CEST e GTIN são conferidos nas tabelas oficiais aqui, não na nota:

curl https://api.sudrel.com.br/api/v1/produtos \
  -H "Authorization: Bearer $SUDREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":"'$EMPRESA'","codigo":"SKU-123","descricao":"Camiseta de algodão","ncm":"61091000","unidade":"UN","origem":"0","perfil_fiscal":{"icms":"tributado","pis_cofins":"tributado","ibs_cbs":{"cst":"000","classificacao_tributaria":"000001"}}}'

3. Perfil da empresa e aprovação. Grave o perfil fiscal da empresa e aprove os dois perfis: nada é calculado sem uma pessoa aprovar. No sandbox, aprove você mesmo:

curl -X PUT https://api.sudrel.com.br/api/v1/nfe/perfil-fiscal/$EMPRESA \
  -H "Authorization: Bearer $SUDREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contribuinte_ipi":false}'

curl https://api.sudrel.com.br/api/v1/nfe/perfil-fiscal/$EMPRESA/aprovacao \
  -H "Authorization: Bearer $SUDREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aprovado_por":{"nome":"Ana Souza","email":"[email protected]"}}'

curl "https://api.sudrel.com.br/api/v1/produtos/SKU-123/aprovacao-perfil?empresa_id=$EMPRESA" \
  -H "Authorization: Bearer $SUDREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aprovado_por":{"nome":"Ana Souza","email":"[email protected]"}}'

Esse perfil serve ao Simples Nacional. Empresa do regime normal acrescenta "regime_pis_cofins" (cumulativo ou nao_cumulativo); veja Produtos e motor fiscal.

4. Emita. Só o CNPJ do destinatário, o produto, a quantidade e o valor:

curl https://api.sudrel.com.br/api/v1/nfe \
  -H "Authorization: Bearer $SUDREL_API_KEY" \
  -H "Idempotency-Key: 8f1c2e4a-1b2c-4d5e-9f00-112233445566" \
  -H "Prefer: wait=15" \
  -H "Content-Type: application/json" \
  -d '{
    "empresa_id": "'$EMPRESA'",
    "referencia": "PED-10294",
    "modo": "calcular",
    "presenca": "internet",
    "destinatario": { "documento": "13937073000156" },
    "itens": [ { "produto": "SKU-123", "quantidade": 2, "valor_unitario": 89.90 } ],
    "pagamentos": [ { "forma": "pix" } ]
  }'

A Sudrel busca nome e endereço do CNPJ na Receita e a inscrição estadual na SEFAZ, resolve CFOP, natureza da operação e tributos, e põe no pagamento o valor da nota calculada. Cada valor volta em ajustes, com a regra e a fonte legal. O CNPJ precisa existir na Receita: o do exemplo é o da SEFAZ-BA; troque pelo de um cliente seu. CNPJ inventado volta destinatario_nao_encontrado.

Resposta	O que aconteceu	Próximo passo
201 autorizada	Protocolo e chave de acesso preenchidos.	Baixe o DANFE em GET /v1/nfe/PED-10294/danfe.
202 transmitindo	A Sudrel continua cuidando.	Espere o webhook NFE_AUTORIZADA ou consulte GET /v1/nfe/PED-10294. Não emita de novo.
422 fora_de_cobertura	O motor não calcula esta operação (lista em fora_de_cobertura).	Mande a mesma nota no modo informado, com os tributos.
422 nfe_rejeitada	A SEFAZ recusou.	Leia rejeicao e corrija em POST /v1/nfe/{id}/correcao.

Validar antes é opcional. POST /v1/nfe/previas recebe o mesmo corpo e devolve erros, ajustes e o XML que seria enviado, sem reservar número. A emissão faz as mesmas conferências, então a prévia serve para ver o XML antes ou validar no seu sistema, não é um passo obrigatório.

O seu ERP já calcula os tributos? Pule os passos 2 e 3 e mande, em cada item, codigo, descricao, ncm, cfop, origem, unidade e os grupos icms, pis e cofins (modo informado, o padrão). O exemplo venda de POST /v1/nfe tem o corpo completo, e Emissão de NF-e tem a tabela do que é obrigatório em cada modo.

Para testar os desvios sem depender da SEFAZ, use o cabeçalho X-Sudrel-Simular (veja Simulador de falhas).