# API de Motoristas

Todos os endpoints requerem o seguinte header:

| Header | Descrição |
|---|---|
| `x-abbiamo-seller-group-key` | Chave de autenticação usada para identificar e autorizar o seller group que está fazendo a requisição. |

---

## 1. Listar Motoristas

**`GET /v1/drivers`**

Retorna uma lista paginada de motoristas associados ao seller group autenticado. Os resultados são ordenados por data de criação, do mais recente para o mais antigo.

### Query Params

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| `page` | string | Não | `1` | Número da página a ser retornada. |
| `page_size` | string | Não | `10` | Quantidade de motoristas por página. Valor máximo permitido é `100`. |

### Resposta — 200 OK

```json
{
  "page": 1,
  "page_size": 10,
  "total_pages": 3,
  "has_next_page": true,
  "total_results": 25,
  "results": [
    {
      "id": "b3d2f1a0-4c5e-4f6d-8e9b-1a2b3c4d5e6f",
      "name": "João Silva Santos",
      "document_number": "12345678901",
      "phone": "5511999999999",
      "active": true,
      "seller_identifiers": ["seller-sp-01", "seller-sp-02"]
    }
  ]
}
```

### Erros

| Status | Código | Descrição |
|---|---|---|
| 400 | `INVALID_PARAMS` | `page_size` excede o valor máximo de 100. |
| 404 | `SELLER_NOT_FOUND` | Nenhum seller encontrado para o seller group. |

---

## 2. Buscar Motorista por Documento

**`GET /v1/drivers/:document_number`**

Retorna os dados de um único motorista. O motorista deve estar associado ao seller group autenticado.

### Path Params

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `document_number` | string | Sim | Número do documento do motorista (ex: CPF). |

### Resposta — 200 OK

```json
{
  "id": "b3d2f1a0-4c5e-4f6d-8e9b-1a2b3c4d5e6f",
  "name": "João Silva Santos",
  "document_number": "12345678901",
  "phone": "5511999999999",
  "active": true,
  "created_at": "2026-03-19T10:00:00.000Z",
  "updated_at": "2026-03-19T10:00:00.000Z",
  "seller_identifiers": ["seller-sp-01"]
}
```

### Erros

| Status | Código | Descrição |
|---|---|---|
| 404 | `DRIVER_NOT_FOUND` | Motorista não encontrado. |
| 400 | `DRIVER_NOT_FOUND` | Motorista não possui sellers associados. |
| 400 | `DRIVER_NOT_FOUND` | Motorista não está associado ao seller group autenticado. |

---

## 3. Criar ou Atualizar Motorista

**`POST /v1/drivers`**

Cria um novo motorista ou atualiza um existente dentro do seller group autenticado. O `document_number` é usado para determinar se é uma criação ou atualização. Os campos `name`, `phone` e `seller_identifiers` são obrigatórios. Na atualização, apenas motoristas já pertencentes ao seller group podem ser modificados.

### Body

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `document_number` | string | Sim | Número do documento do motorista (apenas: CPF). Usado para identificar se é criação ou atualização. |
| `name` | string | Sim | Nome completo do motorista obrigatório. |
| `phone` | string | Sim | Número de telefone do motorista obrigatório. |
| `seller_identifiers` | string[] | Apenas na criação | Lista de identificadores de sellers para associar ao motorista. Obrigatório na criação. Na atualização, adiciona os sellers informados às associações existentes do motorista dentro do seller group. Todos os identificadores devem pertencer ao seller group autenticado. |
| `password` | string | Não | Senha do motorista no aplicativo. Na criação é obrigatório para definir a senha inicial. Na atualização, substitui a senha atual mas não é obrigatório. |

### Resposta — 201 Created

```json
{
  "id": "b3d2f1a0-4c5e-4f6d-8e9b-1a2b3c4d5e6f",
  "name": "João Silva Santos",
  "document_number": "12345678901",
  "phone": "5511999999999",
  "seller_identifiers": ["seller-sp-01", "seller-sp-02"],
  "created_at": "2026-03-19T10:00:00.000Z",
  "password": "senha123"
}
```

### Erros

| Status | Código | Descrição |
|---|---|---|
| 400 | `INVALID_PARAMS` | `name` ou `phone` não informados na criação. |
| 400 | `SELLER_NOT_FOUND` | `seller_identifiers` não informado na criação. |
| 400 | `SELLER_NOT_FOUND` | Um ou mais seller identifiers não encontrados no seller group. |
| 404 | `DRIVER_NOT_FOUND` | Motorista existe mas pertence a outro seller group. |