> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bulkroute.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding de uma Nova Empresa

> Passo a passo completo para configurar um novo tenant do zero até o primeiro envio.

Este guia mostra como configurar uma nova empresa (tenant) no BulkRoute do zero — desde a criação até o primeiro despacho real.

## Visão geral do onboarding

```mermaid theme={null}
graph LR
    A[1. Criar tenant] --> B[2. Configurar carriers]
    B --> C[3. Criar CD de origem]
    C --> D[4. Gerar API Key]
    D --> E[5. Testar cotação]
    E --> F[6. Criar primeiro envio]
    F --> G[7. Imprimir etiqueta]
    G --> H[8. Acompanhar rastreio]
```

## Passo 1 — Criar o tenant

1. Acesse o painel como **Administrador do BulkRoute** (não do cliente)
2. Vá em **Empresas** > **Nova Empresa**
3. Preencha:
   * **Nome da empresa**: ex: "Móveis Conforto Ltda"
   * **E-mail de contato**: do gestor logístico
   * **Telefone**
   * **CNPJ** (opcional neste passo)
   * **Plano**: Starter, Pro ou Enterprise
4. Salve

O BulkRoute cria o tenant com:

* ID único (UUID)
* Usuário admin da empresa (e-mail + senha temporária)
* Assinatura no plano selecionado (status `trial` por 14 dias)

## Passo 2 — Configurar carriers

1. Acesse o tenant criado > **Transportadoras**
2. Ative os carriers que a empresa usa:
   * [Braspress](/transportadoras/braspress)
   * [Jadlog](/transportadoras/jadlog)
   * [SSW](/transportadoras/ssw)
   * [Correios](/transportadoras/correios)
   * [Frota Própria](/transportadoras/frota-propria) (se aplicável)
3. Para cada carrier, insira as credenciais e clique em **Testar Conexão**
4. Salve

<Tip>
  Comece com 1-2 carriers no piloto. Adicione mais conforme a operação estabiliza.
</Tip>

## Passo 3 — Criar CD de origem

1. Vá em **Centros de Distribuição** > **Novo CD**
2. Preencha:
   * **Nome**: ex: "CD Matriz - Curitiba"
   * **CEP**: 80000000 (exemplo)
   * **Endereço completo**
   * **Ativo**: sim
3. Salve

O CEP do CD é usado como **origem padrão** nas cotações quando o `originZip` não é enviado no request.

## Passo 4 — Gerar API Key

1. No tenant, acesse **Chaves de API**
2. Clique em **Gerar Nova Chave**
3. Nomeie: ex: "Integração Bling Produção"
4. Copie o valor (`bk_live_...`)

<Warning>
  A chave completa é exibida apenas uma vez. Guarde em local seguro.
</Warning>

## Passo 5 — Testar cotação

Antes de criar um envio real, teste a cotação:

### Via painel

1. Vá em **Cotações** > **Nova Cotação**
2. Preencha CEP origem, destino, peso e dimensões
3. Clique em **Cotar**
4. Verifique se os carriers respondem com preço e prazo

### Via API

```bash theme={null}
curl -X POST "https://api.bulkroute.com.br/api/quotes" \
  -H "X-API-Key: bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destinationZip": "01310100",
    "originZip": "80000000",
    "items": [{ "weight": 30, "length": 100, "width": 60, "height": 40, "value": 1500, "quantity": 1 }]
  }'
```

Se a resposta vier vazia, verifique:

* Credenciais dos carriers (Testar Conexão)
* Faixa de CEP atendida pelo carrier
* Peso/dimensões dentro do limite do carrier

## Passo 6 — Criar primeiro envio

### Via painel

1. **Shipments** > **Novo Envio**
2. Preencha destinatário e carga
3. Selecione o carrier (ou deixe o orquestrador escolher)
4. Clique em **Criar Envio**

### Via API

```bash theme={null}
curl -X POST "https://api.bulkroute.com.br/api/orders" \
  -H "X-API-Key: bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destinationZip": "01310100",
    "originZip": "80000000",
    "carrierCode": "BRASPRESS",
    "recipient": { "name": "João Silva", "phone": "11999999999", "address": { "street": "Av. Paulista", "number": "1000", "district": "Bela Vista", "city": "São Paulo", "state": "SP" } },
    "items": [{ "sku": "SOFA-3L", "description": "Sofá 3 lugares", "weight": 30, "length": 100, "width": 60, "height": 40, "value": 1500, "quantity": 1 }]
  }'
```

## Passo 7 — Imprimir etiqueta

1. Abra o shipment criado
2. Clique em **Imprimir Etiqueta**
3. Escolha o formato:
   * **PDF A4** (impressora comum)
   * **ZPL 100×150mm** (impressora térmica)
4. Imima e cole na carga

## Passo 8 — Acompanhar rastreio

1. Abra o shipment
2. Veja a **timeline** com todos os eventos
3. O status atualiza automaticamente (webhook ou polling a cada 15min)
4. O cliente final recebe notificações em eventos-chave

## Checklist de onboarding

* [ ] Tenant criado
* [ ] Plano selecionado (trial ativo)
* [ ] Carriers configurados e testados
* [ ] CD de origem cadastrado
* [ ] API Key gerada
* [ ] Cotação testada (via painel e/ou API)
* [ ] Primeiro envio criado
* [ ] Etiqueta impressa
* [ ] Tracking funcionando
* [ ] Integração com ERP/marketplace configurada (se aplicável)
* [ ] Branding da página de tracking configurado (se plano pago)
* [ ] Usuários da equipe cadastrados com permissões corretas
* [ ] Webhook outbound configurado (se aplicável)

## Tempo esperado

| Etapa                           | Tempo        |
| :------------------------------ | :----------- |
| Criar tenant + plano            | 5 min        |
| Configurar 2-3 carriers         | 20 min       |
| Criar CD + API Key              | 5 min        |
| Testar cotação + primeiro envio | 15 min       |
| Configurar integração (ERP/ML)  | 30 min       |
| **Total**                       | **\~75 min** |