---
title: "Primeiros passos — integração com NFe/CTe Inbound"
description: "Tutorial guiado em 6 etapas: obter credenciais, localizar company_id, ativar inbound, configurar webhook, validar recepção e migrar para produção."
source_url: https://nfe.io/docs/distribuicao-nfe-cte-primeiros-passos/
last_updated: 2026-07-30
---

# Guia de Primeiros Passos

Se você está integrando pela primeira vez, siga esta sequência em ordem. Não pule etapas.

## Sumário

- [Fluxo geral](#fluxo-geral)
- [Etapa 1 — Obter credenciais](#etapa-1--obter-credenciais)
- [Etapa 2 — Localizar seu company_id](#etapa-2--localizar-seu-company_id)
- [Etapa 3 — Ativar o inbound](#etapa-3--ativar-o-inbound)
- [Etapa 4 — Configurar seu endpoint de webhook](#etapa-4--configurar-seu-endpoint-de-webhook)
- [Etapa 5 — Verificar que documentos chegam](#etapa-5--verificar-que-documentos-chegam)
- [Etapa 6 — Migrar para produção](#etapa-6--migrar-para-produção)

## Fluxo geral

```mermaid
flowchart LR
    A[1. API Key] --> B[2. company_id]
    B --> C[3. Ativar inbound]
    C --> D[4. Endpoint webhook]
    D --> E[5. Validar recepção]
    E --> F[6. Promover para Production]
```

## Etapa 1 — Obter credenciais

No painel nfe.io, crie uma API Key em **Configurações → Chaves de API**. Guarde-a com segurança — ela só é exibida uma vez.

## Etapa 2 — Localizar seu company_id

Em **Empresas**, clique na empresa que deseja integrar e copie o `company_id` exibido na URL ou nos detalhes da empresa.

## Etapa 3 — Ativar o inbound

Faça uma requisição para ativar o monitoramento do CNPJ:

```bash
curl -X POST \
  "https://api.nfe.io/v2/companies/SEU_COMPANY_ID/inbound/productinvoices" \
  -H "Authorization: ApiKey SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "StartFromNsu": 0,
    "StartFromDate": "2024-01-01T00:00:00Z",
    "EnvironmentSEFAZ": "Production",
    "WebhookVersion": 2
  }'
```

Resposta esperada: `{ "status": "Active", ... }`

## Etapa 4 — Configurar seu endpoint de webhook

No painel nfe.io, vá em **Webhooks** e cadastre a URL do seu servidor que vai receber as notificações.

Mínimo necessário no seu endpoint:

```python
# Python (Flask)
@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    access_key = data['accessKey']
    # Processar...
    return '', 200  # OBRIGATÓRIO retornar 200
```

## Etapa 5 — Verificar que documentos chegam

Após ativar, aguarde entre 15 minutos e 4 horas. Consulte documentos recebidos:

```bash
curl "https://api.nfe.io/v2/companies/SEU_COMPANY_ID/inbound/productinvoices/CHAVE_44_DIGITOS" \
  -H "Authorization: ApiKey SUA_API_KEY"
```

## Etapa 6 — Migrar para produção

Quando seus testes estiverem OK com `"EnvironmentSEFAZ": "Test"`, recrie a configuração com `"Production"`:

```bash
# 1. Desativar o inbound de homologação
curl -X DELETE \
  "https://api.nfe.io/v2/companies/SEU_COMPANY_ID/inbound/productinvoices" \
  -H "Authorization: ApiKey SUA_API_KEY"

# 2. Ativar com ambiente de produção
curl -X POST \
  "https://api.nfe.io/v2/companies/SEU_COMPANY_ID/inbound/productinvoices" \
  -H "Authorization: ApiKey SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "StartFromNsu": 0,
    "StartFromDate": "2024-01-01T00:00:00Z",
    "EnvironmentSEFAZ": "Production",
    "WebhookVersion": 2
  }'
```

> **Importante:** Documentos de ambiente `Test` (homologação SEFAZ) e `Production` são separados. Nunca misture os dois na mesma configuração.

## Veja também

- [Quickstart (≤5 minutos)](../00-quickstart.md)
- [Exemplos de integração (C#, Node, Python, PHP)](./exemplos-integracao.md)
- [Ativar via API](../how-to/ativar-via-api.md)
- [Configurar webhook](../how-to/configurar-webhook.md)
- [Endpoints de NF-e](../reference/endpoints-nfe.md)