Guia Rápido (Quickstart): Sua Primeira Emissão de NF-e

Este guia mostra o passo a passo para emitir sua primeira Nota Fiscal Eletrônica (NF-e) em ambiente de testes (Homologação) usando nossa API. O objetivo é realizar uma operação simples de venda para validar a comunicação e entender o fluxo básico.

---

Pré-requisitos

Antes de começar, você vai precisar de:

1. API Key: Sua chave de acesso à API. Você pode obtê-la no painel da sua conta.
2. ID da Empresa (companyId): O identificador único da empresa emitente.
3. Certificado Digital: Um certificado A1 válido, já configurado e associado à empresa na nossa plataforma.
4. cURL: Uma ferramenta de linha de comando para fazer requisições HTTP. Você pode usar outras ferramentas como Postman ou Insomnia, se preferir.

---

Passo 1: Entendendo o Ambiente de Testes

Todas as operações neste guia serão realizadas no ambiente de Homologação (Testes). As notas emitidas aqui não possuem validade jurídica e servem apenas para validar sua integração.

Para emitir notas fiscais reais, você precisará usar o ambiente de Produção.

---

Passo 2: Preparando o Payload (JSON)

Vamos criar um arquivo chamado payload.json com os dados mínimos para uma NF-e de venda simples. Note que usamos "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO" na descrição para deixar claro que é um teste.

Arquivo payload.json:

{
  "operationType": "Outgoing",
  "purposeType": "Normal",
  "destination": "Internal_Operation",
  "consumerType": "FinalConsumer",
  "presenceType": "Internet",
  "buyer": {
    "name": "NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL",
    "federalTaxNumber": "01234567890",
    "type": "NaturalPerson",
    "stateTaxNumberIndicator": "NonTaxPayer",
    "address": {
      "street": "Av. Teste",
      "number": "123",
      "district": "Centro",
      "city": {
        "code": "3550308",
        "name": "Sao Paulo"
      },
      "state": "SP",
      "postalCode": "01000000",
      "country": "BRA"
    }
  },
  "items": [
    {
      "code": "P001",
      "description": "PRODUTO TESTE - NOTA FISCAL EMITIDA EM AMBIENTE DE HOMOLOGACAO",
      "ncm": "85171300",
      "cfop": 5102,
      "quantity": 1,
      "unit": "UN",
      "unitAmount": 10.00,
      "totalAmount": 10.00,
      "totalIndicator": true,
      "tax": {
        "icms": {
          "origin": "0",
          "cst": "00",
          "baseTax": 10.00,
          "rate": 18.00,
          "amount": 1.80
        },
        "pis": {
          "cst": "07"
        },
        "cofins": {
          "cst": "07"
        }
      }
    }
  ],
  "payment": [
    {
      "paymentDetail": [
        {
          "method": "InstantPayment",
          "paymentType": "InCash",
          "amount": 10.00
        }
      ]
    }
  ]
}

---

Passo 3: Enviando a Requisição de Emissão

Agora, vamos enviar o payload.json para a API usando cURL. Substitua YOUR_COMPANY_ID e YOUR_API_KEY pelos seus dados.

curl --location --request POST 'https://api.nfse.io/v2/companies/YOUR_COMPANY_ID/productinvoices' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_KEY' \
--data-raw '@payload.json'

A API processa as emissões de forma assíncrona. Se sua requisição for válida, você receberá uma resposta HTTP 202 Accepted, indicando que a nota foi enfileirada para processamento.

Resposta Esperada (HTTP 202):

{
  "id": "xxxxxxxxxxxxxxxx"
  ...
}

Guarde o id retornado. Ele será usado para consultar o status final da nota.

---

Passo 4: Consultando o Status Final da Nota

Após alguns segundos, consulte o status da nota usando o id obtido no passo anterior.

curl --location --request GET \
  https://api.nfse.io/v2/companies/YOUR_COMPANY_ID/productinvoices/xxxxxxxxxxxxxxxx \
  --header "Authorization: YOUR_API_KEY"

Cenário de Sucesso

Se tudo correu bem, o status da nota será Issued (Emitida) e a resposta incluirá a chave de acesso e os links para download do XML e do DANFE (PDF).

Resposta de Sucesso:

{
  "id": "xxxxxxxxxxxxxxxx",
  "status": "Issued",
  "authorization": {
    "accessKey": "35240811223344000155550010000001231000001234",
    "message": "Autorizado o uso da NF-e",
    ...
  },
  "xml": { "uri": "https://..." },
  "pdf": { "uri": "https://..." }
}

Cenário de Erro (Rejeição)

Se a SEFAZ rejeitar a nota por alguma regra de negócio (ex: NCM inválido), o status será Error e a resposta conterá o código e a mensagem da rejeição.

Resposta de Erro:

{
  "id": "xxxxxxxxxxxxxxxx",
  "status": "Error",
  "errors": [
    {
      "code": 778,
      "message": "Rejeicao: Informado NCM inexistente"
    }
  ]
}

Neste caso, você deve corrigir o dado no payload.json e reenviar a nota (preferencialmente com um novo número para evitar duplicidade).

---

Próximos Passos

Parabéns! Você emitiu sua primeira NF-e de teste. Agora você pode:

• Explorar a Documentação Completa: Consulte o Guia de Solução de Problemas e a Documentação Funcional para entender todos os campos e cenários.
• Testar Cenários da Reforma Tributária: Adicione o grupo IBSCBS aos itens para testar as novas regras.
• Configurar Webhooks: Em vez de consultar o status, configure um webhook para ser notificado automaticamente quando a nota for autorizada ou rejeitada.