Clientes

Gerenciamento de clientes (pessoas atendidas). Requer papel de attendant ou superior.

Endpoints

Método	Endpoint	Descrição	Role Mínimo
GET	/api/v1/customers	Listar clientes	attendant
POST	/api/v1/customers	Criar cliente	attendant
GET	/api/v1/customers/:id	Buscar cliente	attendant
PUT	/api/v1/customers/:id	Atualizar cliente	attendant
DELETE	/api/v1/customers/:id	Excluir cliente	attendant
POST	/api/v1/customers/merge	Mesclar clientes duplicados	supervisor

---

Listar Clientes

GET /api/v1/customers

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página
page_size	integer	20	Itens por página
sort_by	string	name	Campo para ordenação (name, email, inserted_at)
sort_order	string	asc	Direção da ordenação
search	string	-	Busca por nome, email ou telefone

Exemplo de Request

curl -X GET "https://voki.avanter.com.br/api/v1/customers?search=carlos&page=1" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": [
    {
      "id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
      "name": "Carlos Ferreira",
      "email": "carlos@email.com",
      "phone": "+5511999998888",
      "document": "123.456.789-00",
      "notes": "Cliente preferencial",
      "call_count": 5,
      "last_call_at": "2026-02-15T14:30:00Z",
      "inserted_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-02-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

---

Criar Cliente

POST /api/v1/customers

Request Body

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome completo
email	string	Não	Email
phone	string	Não	Telefone
document	string	Não	CPF ou CNPJ
notes	string	Não	Observações

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/customers \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Ana Costa",
      "email": "ana@email.com",
      "phone": "+5511977776655",
      "document": "987.654.321-00"
    }
  }'

Resposta de Sucesso (201)

{
  "data": {
    "id": "3b4c5d6e-7f8a-9012-cdef-345678901234",
    "name": "Ana Costa",
    "email": "ana@email.com",
    "phone": "+5511977776655",
    "document": "987.654.321-00",
    "notes": null,
    "call_count": 0,
    "last_call_at": null,
    "inserted_at": "2026-02-18T15:00:00Z",
    "updated_at": "2026-02-18T15:00:00Z"
  }
}

---

Buscar Cliente

GET /api/v1/customers/:id

Exemplo de Request

curl -X GET https://voki.avanter.com.br/api/v1/customers/2a3b4c5d-6e7f-8901-bcde-f23456789012 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

---

Atualizar Cliente

PUT /api/v1/customers/:id

Exemplo de Request

curl -X PUT https://voki.avanter.com.br/api/v1/customers/2a3b4c5d-6e7f-8901-bcde-f23456789012 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "notes": "Cliente VIP - tratamento preferencial"
    }
  }'

---

Excluir Cliente

DELETE /api/v1/customers/:id

Exemplo de Request

curl -X DELETE https://voki.avanter.com.br/api/v1/customers/3b4c5d6e-7f8a-9012-cdef-345678901234 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (204)

Sem corpo na resposta.

---

Mesclar Clientes

Mescla dois ou mais registros de clientes duplicados em um único registro. Requer papel de supervisor.

POST /api/v1/customers/merge

Request Body

Campo	Tipo	Obrigatório	Descrição
target_id	uuid	Sim	ID do cliente que receberá os dados
source_ids	uuid[]	Sim	IDs dos clientes a serem mesclados

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/customers/merge \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
    "source_ids": ["3b4c5d6e-7f8a-9012-cdef-345678901234"]
  }'

Resposta de Sucesso (200)

{
  "data": {
    "id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
    "name": "Carlos Ferreira",
    "email": "carlos@email.com",
    "phone": "+5511999998888",
    "document": "123.456.789-00",
    "call_count": 7,
    "merged_count": 1
  }
}

Nota

Os clientes fonte (source_ids) serão removidos e todas as suas chamadas serão reatribuídas ao cliente alvo.