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

# Quickstart

> Faça sua primeira busca e crie um pedido em minutos

Este guia mostra o fluxo completo da CGD: desde a autenticação até a criação de um pedido de fretamento. Siga os passos na ordem indicada.

<Steps>
  <Step title="Obtenha sua API Key">
    Acesse **Configurações → API Partner** no painel do CGD e copie a chave de API.

    Se ainda não houver uma chave gerada, clique em **Gerar nova chave**.

    A chave tem o formato `gds_` seguido de 64 caracteres e deve ser usada no header `Authorization` de todas as requisições:

    ```
    Authorization: Bearer gds_4f3a8b9c2d1e7f0a...
    ```
  </Step>

  <Step title="Crie ou busque um cliente">
    Crie o cliente que vai solicitar o fretamento. Use `integration_code` para vincular ao ID do seu sistema:

    ```bash theme={null}
    curl -X POST https://gds.fretatech.com.br/api/partner/v1/customers \
      -H "Authorization: Bearer SUA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Empresa Exemplo Ltda",
        "type": "company",
        "cnpj_cpf": "12.345.678/0001-95",
        "email": "contato@exemplo.com.br",
        "phone": "(11) 99999-0000",
        "integration_code": "ERP-CLIENTE-001"
      }'
    ```

    Anote o `id` do cliente criado — você precisará dele para criar o orçamento.

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": 42,
        "name": "Empresa Exemplo Ltda",
        "integration_code": "ERP-CLIENTE-001"
      }
    }
    ```
  </Step>

  <Step title="Inicie uma busca de veículos">
    Envie apenas os endereços em texto livre — o CGD resolve as coordenadas automaticamente:

    ```bash theme={null}
    curl -X POST https://gds.fretatech.com.br/api/partner/v1/search \
      -H "Authorization: Bearer SUA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "origin": "Aeroporto de Guarulhos, Guarulhos - SP",
        "destination": "Av. Paulista, 1000, São Paulo - SP",
        "trip_date": "2026/04/15",
        "trip_time": "10:00",
        "trip_type": "onewaytrip",
        "passengers": 40
      }'
    ```

    ```json theme={null}
    {
      "success": true,
      "data": {
        "search_db_id": 123,
        "status": "pending",
        "origin": { "description": "Aeroporto Internacional de Guarulhos", "lat": -23.4356, "lng": -46.4731 },
        "destination": { "description": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP", "lat": -23.563, "lng": -46.6543 },
        "message": "Busca iniciada. Use GET /search/{id} para consultar."
      }
    }
    ```
  </Step>

  <Step title="Aguarde os resultados (polling)">
    A busca consulta fornecedores em tempo real. Faça polling a cada \~2 segundos até o status ser `complete`:

    ```bash theme={null}
    curl -X GET "https://gds.fretatech.com.br/api/partner/v1/search/123" \
      -H "Authorization: Bearer SUA_API_KEY"
    ```

    Quando `status` for `complete`, você terá a lista de veículos disponíveis:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "search_db_id": 123,
        "status": "complete",
        "vehicles": [
          {
            "id": "abc123",
            "name": "Ônibus Executivo 50 lugares",
            "capacity": 50,
            "type": "bus",
            "price_cents": 180000,
            "tenant_id": "tenant-uuid",
            "tenant_name": "Viação Exemplo"
          }
        ]
      }
    }
    ```

    Anote o `id` do veículo desejado.
  </Step>

  <Step title="Crie um orçamento">
    Com os dados do veículo e do cliente, crie o orçamento. Use `default_margin_percentage` para definir a margem desta operação:

    ```bash theme={null}
    curl -X POST https://gds.fretatech.com.br/api/partner/v1/quotes \
      -H "Authorization: Bearer SUA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "customer_id": 42,
        "default_margin_percentage": 15,
        "simpleTrip": { ... }
      }'
    ```

    Anote o `id` do orçamento criado.
  </Step>

  <Step title="Crie o pedido">
    Confirme o orçamento convertendo-o em pedido:

    ```bash theme={null}
    curl -X POST https://gds.fretatech.com.br/api/partner/v1/orders \
      -H "Authorization: Bearer SUA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "quote_id": 99 }'
    ```

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": 200,
        "status": "pending_invoice",
        "total_amount": 207000
      }
    }
    ```

    O pedido é enviado automaticamente ao fornecedor. Acompanhe as atualizações via webhook.
  </Step>

  <Step title="Configure seu webhook para receber atualizações">
    Registre uma URL no seu sistema para receber eventos em tempo real:

    ```bash theme={null}
    curl -X POST https://gds.fretatech.com.br/api/partner/v1/webhooks \
      -H "Authorization: Bearer SUA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://seu-sistema.com.br/webhooks/gds",
        "events": ["order.status_changed", "order_item.driver_assigned", "order_item.vehicle_assigned"]
      }'
    ```

    O `secret` HMAC é gerado automaticamente — use-o para verificar a assinatura dos eventos recebidos. Veja [Webhooks](/partner/webhooks) para mais detalhes.
  </Step>
</Steps>

## Próximos passos

* Consulte a referência completa de cada endpoint nas páginas desta seção
* Configure [Webhooks](/partner/webhooks) para receber atualizações operacionais automaticamente
* Veja [Extrato Financeiro](/partner/statements) para consultar margens e faturamento