Basis

Appearance

Clientes ​

O cliente é quem é atendido. A senha é opcional de propósito: o cliente que a recepcionista cadastrou por telefone existe como registro sem nunca ter tido conta — e se um dia criar acesso no portal, reaproveita o mesmo cadastro.

Cada cliente carrega dois contadores mantidos automaticamente: totalAppointments (agendamentos criados) e totalNoShows (faltas). Eles alimentam o alerta de cliente problemático sem varrer o histórico — e o staff pode bloquear novos agendamentos quando necessário.

Headers obrigatórios

Todas as requisições devem incluir o header X-Booking-Id (UUID) e Authorization: Bearer {token} com o token de um usuário staff. A leitura é livre para qualquer papel autenticado; a escrita exige owner, manager ou receptionist (403 FORBIDDEN caso contrário) — clientes fazem parte da operação da agenda.

Endpoints ​

Listar Clientes ​

http
GET /v1/booking/user/customers

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
page / perPagenumberNãoPaginação (máx. 100 por página).
searchstringNãoBusca por nome, e-mail, telefone ou documento.
isBlockedbooleanNãoFiltra bloqueados/desbloqueados.
isMarketingOptInbooleanNãoFiltra por aceite de marketing.
orderByenumNãoid, name, email ou createdAt (padrão: id).
orderDirectionenumNãoasc ou desc (padrão: desc).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/customers?search=11987654321" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna a página de clientes no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "bookingId": 1,
      "name": "Maria Silva",
      "email": "maria.silva@email.com",
      "phone": "11987654321",
      "document": "12345678901",
      "isMarketingOptIn": true,
      "totalAppointments": 12,
      "totalNoShows": 1,
      "isBlocked": false,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

Criar Cliente ​

Cadastra um cliente sem senha — o acesso ao portal é criado depois pelo próprio cliente, no registro que assume o cadastro existente.

http
POST /v1/booking/user/customers

Payload (Body) ​

AtributoTipoObrigatórioDescrição
namestringSimNome completo (máx. 150 caracteres).
emailstringNãoE-mail (válido, máx. 250 caracteres).
phonestringNãoTelefone (máx. 50 caracteres).
documentstringNãoDocumento (CPF etc., máx. 30 caracteres).
birthDatestringNãoData de nascimento (YYYY-MM-DD).
notesstringNãoObservações internas (máx. 10000 caracteres).
isMarketingOptInbooleanNãoAceite de marketing (padrão: false).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/customers" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "phone": "11987654321",
    "isMarketingOptIn": true
  }'

Respostas ​

201 Created

Retorna o ID do cliente criado.

json
{
  "id": 1
}

Listar para Dropdown ​

http
GET /v1/booking/user/customers/list

Retorna [{ "value", "label" }] com search opcional — ideal para o select de cliente na criação manual de agendamento.

Obter Cliente por ID ​

http
GET /v1/booking/user/customers/:id

Retorna o cadastro completo (nascimento, notas, contadores). Responde 404 quando não existe na instância.

Atualizar Cliente ​

http
PUT /v1/booking/user/customers/:id

Aceita os mesmos campos da criação. Responde 204 em caso de sucesso.

Remover Cliente ​

http
DELETE /v1/booking/user/customers/:id

Soft delete — o histórico de agendamentos é preservado. Responde 204 em caso de sucesso.

Bloquear Cliente ​

Impede novos agendamentos e o acesso ao portal (403 nas rotas privadas do portal). O histórico não é afetado.

http
PATCH /v1/booking/user/customers/:id/block

Exemplo de Requisição ​

bash
curl -X PATCH "https://api.us.basis.tavares.in/v1/booking/user/customers/1/block" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Respostas ​

204 No Content

Cliente bloqueado. Novos agendamentos para ele falham com 422 CUSTOMER_BLOCKED.

json
{
  "message": "Cliente bloqueado para novos agendamentos",
  "code": "CUSTOMER_BLOCKED"
}

Desbloquear Cliente ​

http
PATCH /v1/booking/user/customers/:id/unblock

Respostas ​

204 No Content

Cliente desbloqueado — volta a agendar normalmente.