Começando

Este guia leva você da chave de teste até a primeira NF-e autorizada em homologação, sem valor fiscal. Tudo aqui acontece no sandbox: nada vale como nota de verdade, e nada é cobrado.

1. Use a chave de teste no endereço do sandbox

Ao contratar a emitza você recebe duas chaves:

Cada chave só funciona no seu endereço. Envie a chave no cabeçalho Authorization e confira:

curl https://api-sandbox.emitza.com.br/v1/me \
  -H "Authorization: Bearer $EMITZA_KEY"

A resposta traz "mode": "test". Guarde a chave numa variável de ambiente ou num cofre de segredos, nunca no código.

2. Cadastre a empresa emitente

{
  "cnpj": "11222333000181",
  "ie": "110042490114",
  "crt": 1,
  "legalName": "Calçados Exemplo Indústria Ltda",
  "address": {
    "street": "Rua das Indústrias", "number": "100", "district": "Distrito Industrial",
    "cityName": "Franca", "cityCode": "3516200", "uf": "SP", "zip": "14406000"
  }
}

crt é o regime: 1 Simples Nacional, 2 Simples com excesso de sublimite, 3 regime normal (Presumido ou Real), 4 MEI. cityCode é o código IBGE do município. A resposta traz o id da empresa: é o companyId de todas as emissões.

3. Envie o certificado digital A1

A SEFAZ só aceita nota assinada com o e-CNPJ da empresa. Envie o arquivo .pfx em base64 com a senha:

curl -X PUT https://api-sandbox.emitza.com.br/v1/companies/$COMPANY_ID/certificate \
  -H "Authorization: Bearer $EMITZA_KEY" -H "Content-Type: application/json" \
  -d "{\"pfxBase64\": \"$(base64 -w0 empresa.pfx)\", \"password\": \"$PFX_PASSWORD\"}"

A emitza confere se o certificado é do mesmo CNPJ, se está dentro da validade e se é da ICP-Brasil, e guarda o arquivo cifrado. A senha não fica guardada em texto. Antes de vencer, você recebe os webhooks certificate.expiring (30, 15 e 7 dias antes).

4. Cadastre a série da NF-e

{ "number": 1, "next": 1 }

Se a empresa já emitia por outro sistema, use uma série nova ou informe em next o próximo número que ainda não foi usado.

5. Emita a NF-e

{
  "externalId": "pedido-1234",
  "companyId": "6710a1b2c3d4e5f601234567",
  "operation": "sale",
  "natureOfOperation": "Venda de produção do estabelecimento",
  "recipient": {
    "cnpj": "11444777000161",
    "name": "Loja Exemplo Comércio de Calçados Ltda",
    "ieIndicator": "1",
    "ie": "123456785004",
    "address": {
      "street": "Avenida Paulista", "number": "1000", "district": "Bela Vista",
      "cityName": "São Paulo", "cityCode": "3550308", "uf": "SP", "zip": "01310100"
    }
  },
  "items": [{
    "code": "BOT-COURO-38", "description": "Bota de couro nº 38", "ncm": "64039190",
    "origin": "0", "cfop": "5101", "unit": "PAR", "quantity": "10", "unitPrice": "129.90",
    "taxes": { "icms": { "csosn": "101", "creditRate": "1.25" }, "pis": { "cst": "49" }, "cofins": { "cst": "49" } }
  }],
  "transport": { "mode": "9" },
  "payments": [{ "method": "17" }]
}

A resposta chega na hora, com status 202 e "status": "queued". A emitza calcula os impostos (o IBS/CBS inclusive), monta o XML, assina e envia à SEFAZ em segundo plano. Valores decimais vão sempre em texto, com ponto: "129.90".

6. Acompanhe o resultado

Consulte a nota até ela sair de queued, sending ou pending:

curl https://api-sandbox.emitza.com.br/v1/nfe/$NFE_ID -H "Authorization: Bearer $EMITZA_KEY"

Em poucos segundos ela fica authorized, com accessKey (a chave de acesso de 44 dígitos) e protocol. Daí:

• GET /v1/nfe/{id}/danfe devolve o DANFE em PDF;
• GET /v1/nfe/{id}/xml devolve o XML autorizado, que a empresa deve guardar por 5 anos.

Em vez de consultar, prefira receber o resultado por webhook.

Próximos passos

• Conceitos: emissão assíncrona, idempotência e erros. Leia antes de ir para produção.
• Webhooks: receba o resultado sem consultar.
• NF-e e NFS-e: os detalhes de cada documento.
• Indo para produção: o que conferir antes de trocar a chave.

Esta página em Markdown, para IA: index.md