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

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

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

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