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

# Clientes

> Gerenciamento completo de clientes (TMCs e empresas)

O endpoint de clientes permite criar, consultar e atualizar cadastros de pessoas físicas (PF) e jurídicas (PJ) no CGD. Ao criar um cliente, o CGD retorna automaticamente um `integration_code` — use esse código para referenciar o cliente em chamadas futuras (orçamentos, pedidos etc.).

## Endpoints

| Método | Endpoint                                | Descrição                             |
| ------ | --------------------------------------- | ------------------------------------- |
| `GET`  | `/customers`                            | Listar clientes                       |
| `POST` | `/customers`                            | Criar cliente                         |
| `GET`  | `/customers/{id}`                       | Buscar cliente por ID                 |
| `GET`  | `/customers/by-code/{integration_code}` | Buscar cliente pelo integration\_code |
| `PUT`  | `/customers/{id}`                       | Atualizar cliente                     |

***

## Listar clientes

```bash theme={null}
curl -X GET "https://gds.fretatech.com.br/api/partner/v1/customers?type=company&search=exemplo" \
  -H "Authorization: Bearer SEU_TOKEN"
```

### Parametros de filtro

| Parametro          | Tipo    | Descricao                                       |
| ------------------ | ------- | ----------------------------------------------- |
| `search`           | string  | Busca por nome, documento ou e-mail             |
| `type`             | string  | `individual` (PF) ou `company` (PJ)             |
| `integration_code` | string  | Filtra pelo codigo de integracao do seu sistema |
| `page`             | integer | Numero da pagina (padrao: 1)                    |
| `per_page`         | integer | Itens por pagina (padrao: 15, maximo: 100)      |

### Resposta

```json theme={null}
{
  "data": [
    {
      "id": "01jk2m3n4p5q6r7s8t9u0vwxyz",
      "name": "Empresa Exemplo Ltda",
      "type": "company",
      "document": "12345678000195",
      "email": "contato@exemplo.com.br",
      "phone": "11999990000",
      "integration_code": "ERP-CLIENTE-001",
      "created_at": "2026-01-10T09:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 42
  }
}
```

***

## Criar cliente

```bash theme={null}
curl -X POST https://gds.fretatech.com.br/api/partner/v1/customers \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "type": "individual",
    "cnpj_cpf": "12345678901",
    "email": "joao.silva@email.com",
    "tel": "11988887777"
  }'
```

### Campos da requisição

| Campo         | Tipo   | Obrigatório    | Descrição                                                     |
| ------------- | ------ | -------------- | ------------------------------------------------------------- |
| `name`        | string | Sim            | Nome completo (PF) ou razão social (PJ)                       |
| `type`        | string | Sim            | `individual` para PF, `company` para PJ                       |
| `cnpj_cpf`    | string | Não            | CPF (PF, 11 dígitos) ou CNPJ (PJ, 14 dígitos), apenas dígitos |
| `email`       | string | Não            | E-mail de contato (único por CGD)                             |
| `tel`         | string | Não            | Telefone principal com DDD                                    |
| `last_name`   | string | Não            | Sobrenome (PF)                                                |
| `trade_name`  | string | PJ obrigatório | Nome fantasia da empresa                                      |
| `responsible` | string | PJ obrigatório | Nome do responsável                                           |

### Diferença entre tipos

| Campo         | PF (`individual`) | PJ (`company`)    |
| ------------- | ----------------- | ----------------- |
| `cnpj_cpf`    | CPF (11 dígitos)  | CNPJ (14 dígitos) |
| `name`        | Nome completo     | Razão social      |
| `trade_name`  | —                 | Obrigatório       |
| `responsible` | —                 | Obrigatório       |

### Resposta

```json theme={null}
{
  "success": true,
  "data": {
    "id": 42,
    "name": "João Silva",
    "type": "individual",
    "cnpj_cpf": "12345678901",
    "email": "joao.silva@email.com",
    "tel": "11988887777",
    "integration_code": "42",
    "created_at": "2026-03-06T14:00:00.000000Z"
  }
}
```

<Note>
  O campo `integration_code` é gerado automaticamente pelo CGD no momento da criação e corresponde ao ID interno do cliente. Salve esse valor no seu sistema para referenciar este cliente em orçamentos, pedidos e consultas futuras.
</Note>

***

## Buscar cliente por ID

```bash theme={null}
curl -X GET https://gds.fretatech.com.br/api/partner/v1/customers/01jk2m3n4p5q6r7s8t9u0vwxyz \
  -H "Authorization: Bearer SEU_TOKEN"
```

***

## Atualizar cliente

Apenas os campos enviados serao atualizados (PATCH semantics via PUT):

```bash theme={null}
curl -X PUT https://gds.fretatech.com.br/api/partner/v1/customers/01jk2m3n4p5q6r7s8t9u0vwxyz \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo.email@exemplo.com.br",
    "phone": "11977776666"
  }'
```

***

## Buscar por integration\_code

Use este endpoint para encontrar um cliente pelo `integration_code` que você salvou no seu sistema:

```bash theme={null}
curl -X GET https://gds.fretatech.com.br/api/partner/v1/customers/by-code/42 \
  -H "Authorization: Bearer SEU_TOKEN"
```

Você também pode usar o filtro `integration_code` na listagem:

```bash theme={null}
curl -X GET "https://gds.fretatech.com.br/api/partner/v1/customers?integration_code=42" \
  -H "Authorization: Bearer SEU_TOKEN"
```

***

## O campo integration\_code

O `integration_code` é atribuído **automaticamente** pelo CGD no momento da criação do cliente. Seu valor é o ID interno do cliente no CGD.

**Fluxo recomendado:**

1. Crie o cliente via `POST /customers`
2. Salve o `integration_code` retornado na resposta no seu sistema
3. Use esse código para buscar o cliente em chamadas futuras (`GET /customers/by-code/{code}`)
4. Ao criar orçamentos ou pedidos, referencie o cliente pelo `integration_code`