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

# Orçamentos

> Crie e consulte orçamentos de fretamento

Um orçamento (quote) é criado a partir dos resultados de uma busca de veículos. Ele representa uma proposta de fretamento para um cliente, com o preço do fornecedor acrescido da margem configurada.

<Warning>
  **Busca obrigatória.** Não é possível criar um orçamento sem uma busca prévia. Os preços são sempre extraídos do resultado da busca armazenado — o parceiro não informa valores.

  **Validade de 30 minutos.** A busca expira 30 minutos após a conclusão do polling. Após esse prazo, realize uma nova busca antes de criar o orçamento.
</Warning>

## Endpoints

| Método | Endpoint       | Descrição               |
| ------ | -------------- | ----------------------- |
| `POST` | `/quotes`      | Criar orçamento         |
| `GET`  | `/quotes`      | Listar orçamentos       |
| `GET`  | `/quotes/{id}` | Buscar orçamento por ID |

***

## Criar orçamento

O payload usa os dados retornados pelo [polling da busca](/partner/search). Informe o `search_id` e o veículo escolhido; os preços e os dados de rota são extraídos automaticamente do resultado armazenado.

### Campos da requisição

| Campo                       | Tipo          | Obrigatório          | Descrição                                                                              |
| --------------------------- | ------------- | -------------------- | -------------------------------------------------------------------------------------- |
| `customer_id`               | integer       | Sim                  | ID do cliente no CGD                                                                   |
| `search_id`                 | string        | Sim                  | `search_id` retornado pelo endpoint de busca                                           |
| `selectedVehicle`           | object        | Sim                  | Veículo escolhido nos resultados                                                       |
| `selectedVehicle.id`        | integer       | Sim                  | `id` do veículo retornado pela busca                                                   |
| `selectedVehicle.tenant_id` | string (UUID) | Sim                  | `tenant_id` do veículo retornado pela busca                                            |
| `customRouter`              | array         | Só para `customtrip` | Paradas do roteiro (veja abaixo)                                                       |
| `default_margin_percentage` | number        | Não                  | Margem em percentual (ex: `15`). Se omitido, usa a margem padrão configurada na conta. |

<Note>
  Os campos `simpleTrip` (origin, destination, tripType) e o preço do veículo são extraídos automaticamente da busca. O parceiro não precisa — e não pode — enviá-los.
</Note>

***

## Exemplos por tipo de viagem

O `tripType` da busca define o tipo do orçamento automaticamente. Não é necessário informá-lo na criação do orçamento.

### Ida simples, ida e volta ou hora (`onewaytrip` / `roundtrip` / `hourtrip`)

Para todos esses tipos, o payload é idêntico — o tipo é herdado da busca.

```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": 5,
    "search_id": "dMeazSmRgEikWVxe",
    "default_margin_percentage": 15,
    "selectedVehicle": {
      "id": 28,
      "tenant_id": "fb4a8f4c-617a-45f8-a2e9-0aebbc5cd0f5"
    }
  }'
```

***

### Roteiro personalizado (`customtrip`)

Para roteiros com múltiplas paradas, inclua o array `customRouter` com as paradas em ordem. A busca deve ter sido feita com `trip_type: "customtrip"`.

```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": 5,
    "search_id": "Ox2VB6xxOL4HOVae",
    "default_margin_percentage": 15,
    "selectedVehicle": {
      "id": 28,
      "tenant_id": "fb4a8f4c-617a-45f8-a2e9-0aebbc5cd0f5"
    },
    "customRouter": [
      {
        "address": "São Paulo, SP, Brasil",
        "lat": "-23.5505199",
        "lng": "-46.6333094",
        "date": "15/04/2026",
        "time": "07:00"
      },
      {
        "address": "Campinas, SP, Brasil",
        "lat": "-22.9056099",
        "lng": "-47.0607605",
        "date": "15/04/2026",
        "time": "09:00"
      },
      {
        "address": "Ribeirão Preto, SP, Brasil",
        "lat": "-21.1774886",
        "lng": "-47.8103017",
        "date": "15/04/2026",
        "time": "15:00"
      }
    ]
  }'
```

#### Campos de cada parada em `customRouter`

| Campo     | Tipo   | Descrição                              |
| --------- | ------ | -------------------------------------- |
| `address` | string | Endereço completo da parada            |
| `lat`     | string | Latitude                               |
| `lng`     | string | Longitude                              |
| `date`    | string | Data da parada no formato `DD/MM/YYYY` |
| `time`    | string | Horário da parada no formato `HH:MM`   |

***

## Como o preço é calculado

O preço final exibido ao cliente inclui a taxa central da viação, a taxa de serviço do CGD e a margem do parceiro:

```
base          = priceCents do veículo (extraído da busca, já inclui a taxa central da viação)
              + despesas do motorista (quando aplicável)
service_fee   = base × service_fee_percentage   (padrão: 7%)
margin        = base × margin_percentage
total         = base + service_fee + margin
```

Exemplo com veículo de R$ 17.718,81 (já com taxa central 10%), despesas R$ 280, margem 15%:

```
base:         R$ 17.998,81  (17.718,81 + 280,00)
service_fee:  R$  1.259,92  (7%)
margin:       R$  2.699,82  (15%)
total:        R$ 21.958,55
```

***

## Erros possíveis na criação

| HTTP  | Mensagem                           | Causa                                                      |
| ----- | ---------------------------------- | ---------------------------------------------------------- |
| `404` | Busca não encontrada               | `search_id` inválido                                       |
| `422` | Busca expirada                     | Mais de 30 min desde a conclusão da busca. Refaça a busca. |
| `422` | Veículo não encontrado nesta busca | `vehicle_id` ou `tenant_id` incorreto                      |

***

## Resposta

```json theme={null}
{
  "success": true,
  "data": {
    "id": 76,
    "uuid": "621cebbd-cf60-4ab5-a6d6-8dd9545cb9d6",
    "customer": {
      "id": 5,
      "uuid": "6039e108-f7ac-4b19-9a2c-bbf822d6de18",
      "name": "AC DA SILVA",
      "email": "email@email.com.br",
      "phone": null
    },
    "pricing": {
      "subtotal": 1799881,
      "total": 2195855,
      "discount": 0,
      "addition": 0,
      "service_fee_percentage": "7.00",
      "service_fee_value": 125992,
      "margin_percentage": "15.00",
      "margin_value": 269982
    },
    "status": "pending",
    "items": [
      {
        "id": 83,
        "uuid": "be1734d6-05b6-4501-9ce7-bd5bc3ade306",
        "tenant_id": "fb4a8f4c-617a-45f8-a2e9-0aebbc5cd0f5",
        "vehicle_id": 28,
        "type": "onewaytrip",
        "price_cents": 1771881,
        "trip_details": {
          "origin": {
            "address": "Peruíbe, SP, Brasil",
            "city": "Peruíbe",
            "date": "08/03/2026",
            "time": "21:00",
            "lat": "-24.3182917",
            "lng": "-46.9940600"
          },
          "destination": {
            "address": "Aparecida, SP, Brasil",
            "city": "Aparecida",
            "date": "09/03/2026",
            "time": "07:00",
            "lat": "-22.8469289",
            "lng": "-45.2316803"
          }
        },
        "tenant_display": {
          "name": "Viação Mimo - Várzea Paulista",
          "logo": null
        },
        "created_at": "2026-03-08T17:30:00-03:00"
      }
    ],
    "created_at": "2026-03-08T17:30:00-03:00",
    "updated_at": "2026-03-08T17:30:10-03:00"
  },
  "message": "Orçamento criado com sucesso"
}
```

### Campos da resposta

| Campo                       | Tipo    | Descrição                                        |
| --------------------------- | ------- | ------------------------------------------------ |
| `id`                        | integer | ID do orçamento                                  |
| `uuid`                      | string  | UUID do orçamento                                |
| `status`                    | string  | Status do orçamento (veja abaixo)                |
| `pricing.subtotal`          | integer | Subtotal em centavos (base + despesas motorista) |
| `pricing.service_fee_value` | integer | Taxa de serviço em centavos                      |
| `pricing.margin_value`      | integer | Margem em centavos                               |
| `pricing.total`             | integer | Valor total em centavos                          |
| `items`                     | array   | Itens do orçamento (um por trecho da viagem)     |

***

## Status do orçamento

| Status      | Descrição                                         |
| ----------- | ------------------------------------------------- |
| `pending`   | Orçamento criado, aguardando aprovação do cliente |
| `approved`  | Aprovado pelo cliente                             |
| `rejected`  | Recusado pelo cliente                             |
| `converted` | Convertido em pedido                              |
| `expired`   | Prazo de validade expirado                        |

***

## Listar orçamentos

```bash theme={null}
curl -X GET "https://gds.fretatech.com.br/api/partner/v1/quotes?status=pending&customer_id=5" \
  -H "Authorization: Bearer SUA_API_KEY"
```

### Parâmetros de filtro

| Parâmetro     | Tipo    | Descrição                      |
| ------------- | ------- | ------------------------------ |
| `status`      | string  | Filtra por status do orçamento |
| `customer_id` | integer | Filtra por cliente             |
| `date_from`   | string  | Data inicial (`YYYY-MM-DD`)    |
| `date_to`     | string  | Data final (`YYYY-MM-DD`)      |

***

## Buscar orçamento por ID

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

Retorna o objeto completo do orçamento, idêntico ao retorno da criação.