Quickstart

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.

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...

Crie ou busque um cliente

Crie o cliente que vai solicitar o fretamento. Use integration_code para vincular ao ID do seu sistema:

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.

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Empresa Exemplo Ltda",
    "integration_code": "ERP-CLIENTE-001"
  }
}

Inicie uma busca de veículos

Envie apenas os endereços em texto livre — o CGD resolve as coordenadas automaticamente:

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
  }'

{
  "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."
  }
}

Aguarde os resultados (polling)

A busca consulta fornecedores em tempo real. Faça polling a cada ~2 segundos até o status ser complete:

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:

{
  "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.

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:

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.

Crie o pedido

Confirme o orçamento convertendo-o em pedido:

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 }'

{
  "success": true,
  "data": {
    "id": 200,
    "status": "pending_invoice",
    "total_amount": 207000
  }
}

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

Configure seu webhook para receber atualizações

Registre uma URL no seu sistema para receber eventos em tempo real:

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 para mais detalhes.

Próximos passos

Consulte a referência completa de cada endpoint nas páginas desta seção
Configure Webhooks para receber atualizações operacionais automaticamente
Veja Extrato Financeiro para consultar margens e faturamento

Início

Referência

Próximos passos

​Próximos passos

Próximos passos