--- title: "Guia Rápido: Sua Primeira Emissão de NF-e" description: "Um guia passo a passo para emitir sua primeira Nota Fiscal Eletrônica (NF-e) em ambiente de testes usando nossa API." source_url: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-produto/quickstart-nfe-api last_updated: 2026-06-23 --- # 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. :::info * Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas. * Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria) ::: ## 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`:** ```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. ```bash 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):** ```json { "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. ```bash 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:** ```json { "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:** ```json { "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.