Disponibilidade e Exceções

A disponibilidade é o que alimenta a grade de horários que o portal mostra ao cliente. Dois recursos trabalham juntos:

Availabilities são a escala recorrente: "João trabalha segunda das 9h às 18h". Um turno com almoço são duas linhas (9h–12h e 14h–18h).
Overrides são a exceção pontual que a regra recorrente não cobre: o barbeiro ficou doente, é feriado, ou ele topou fazer hora extra no sábado.

O modelo mental

A grade de um dia é calculada em três passos: (1) carrega as escalas recorrentes do dia da semana, (2) aplica as exceções da data — isAvailable: false bloqueia a janela sobreposta, isAvailable: true abre uma janela extra fora da escala — e (3) gera os horários no intervalo slotIntervalMinutes onde cabe a duração do serviço, removendo o que já está ocupado. Agenda rígida quebra na primeira semana de uso real; é esse par de tabelas que dá a flexibilidade.

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 ou manager (403 FORBIDDEN caso contrário) — escalas são gestão.

Escalas (Availabilities)

Listar Escalas

http

GET /v1/booking/user/availabilities

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page` / `perPage`	`number`	Não	Paginação (máx. 100 por página).
`bookingProfessionalId`	`number`	Não	Filtra por profissional.
`dayOfWeek`	`number`	Não	Filtra por dia da semana (`0` = domingo … `6` = sábado).
`date`	`string`	Não	Filtra escalas vigentes em uma data (`YYYY-MM-DD`).
`isActive`	`boolean`	Não	Filtra por ativas/inativas.

O resultado é sempre ordenado por dayOfWeek e depois por startTime.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/availabilities?bookingProfessionalId=1&dayOfWeek=1" \
  -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 escalas no formato meta/data.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "bookingId": 1,
      "bookingProfessionalId": 1,
      "dayOfWeek": 1,
      "startTime": "08:00:00",
      "endTime": "18:00:00",
      "validFrom": null,
      "validUntil": null,
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

Criar Escala

http

POST /v1/booking/user/availabilities

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`dayOfWeek`	`number`	Sim	Dia da semana (`0` = domingo … `6` = sábado).
`startTime`	`string`	Sim	Início do turno, no formato `HH:mm`.
`endTime`	`string`	Sim	Fim do turno, no formato `HH:mm`.
`bookingProfessionalId`	`number`	Não	Profissional (deve existir na instância). Nulo = horário de funcionamento da unidade inteira.
`validFrom`	`string`	Não	Início da vigência (`YYYY-MM-DD`) — permite trocar a escala a partir de uma data sem apagar como era antes.
`validUntil`	`string`	Não	Fim da vigência (`YYYY-MM-DD`).
`isActive`	`boolean`	Não	Indica se já nasce ativa (padrão: `true`).

Escala da unidade vs. do profissional

Quando um profissional não tem escala própria para um dia, a grade usa a escala da unidade (bookingProfessionalId nulo). Assim, o horário de funcionamento do salão serve de padrão e você só cadastra exceções de equipe quando necessário.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/availabilities" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingProfessionalId": 1,
    "dayOfWeek": 1,
    "startTime": "08:00",
    "endTime": "18:00"
  }'

Respostas

201 Created

Retorna o ID da escala criada.

json

{
  "id": 1
}

422 Unprocessable Entity

Ocorre quando o profissional não existe na instância ou os horários estão fora do formato HH:mm.

json

{
  "errors": [
    {
      "message": "Horário inicial inválido, use HH:mm",
      "rule": "regex",
      "field": "startTime"
    }
  ]
}

Obter Escala por ID

http

GET /v1/booking/user/availabilities/:id

Retorna a escala com o profissional embutido. Responde 404 quando não existe na instância.

Atualizar Escala

http

PUT /v1/booking/user/availabilities/:id

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

Remover Escala

http

DELETE /v1/booking/user/availabilities/:id

Soft delete — escalas passadas continuam auditáveis para agendamentos antigos. Responde 204 em caso de sucesso.

Exceções (Overrides)

A exceção pontual de uma data específica, aplicável a um profissional ou à unidade inteira.

Listar Exceções

http

GET /v1/booking/user/overrides

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page` / `perPage`	`number`	Não	Paginação (máx. 100 por página).
`bookingProfessionalId`	`number`	Não	Filtra por profissional.
`from`	`string`	Não	Data inicial (`YYYY-MM-DD`).
`to`	`string`	Não	Data final (`YYYY-MM-DD`).
`isAvailable`	`boolean`	Não	Filtra bloqueios (`false`) ou aberturas extras (`true`).
`orderBy`	`enum`	Não	`id`, `date` ou `createdAt` (padrão: `date`).
`orderDirection`	`enum`	Não	`asc` ou `desc` (padrão: `asc`).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/overrides?from=2026-12-01&to=2026-12-31" \
  -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 exceções no formato meta/data.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "bookingId": 1,
      "bookingProfessionalId": null,
      "date": "2026-12-25",
      "isAvailable": false,
      "startTime": null,
      "endTime": null,
      "reason": "Fechado - Natal",
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

Criar Exceção

http

POST /v1/booking/user/overrides

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`date`	`string`	Sim	A data da exceção (`YYYY-MM-DD`).
`isAvailable`	`boolean`	Sim	`false` bloqueia a data/janela; `true` abre uma janela extra fora da escala.
`bookingProfessionalId`	`number`	Não	Profissional (deve existir na instância). Nulo = unidade inteira.
`startTime`	`string`	Condicional	Início da janela (`HH:mm`). Obrigatório quando `isAvailable: true`. No bloqueio, omitir significa o dia inteiro.
`endTime`	`string`	Condicional	Fim da janela (`HH:mm`). Mesma regra do `startTime`.
`reason`	`string`	Não	Motivo exibido à equipe (máx. 255 caracteres).

Exemplo de Requisição

Bloqueio de dia inteiro (feriado):

bash

curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/overrides" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-12-25",
    "isAvailable": false,
    "reason": "Fechado - Natal"
  }'

Abertura extra (hora extra no sábado):

bash

curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/overrides" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingProfessionalId": 1,
    "date": "2026-12-27",
    "isAvailable": true,
    "startTime": "09:00",
    "endTime": "12:00",
    "reason": "Hora extra"
  }'

Respostas

201 Created

Retorna o ID da exceção criada.

json

{
  "id": 1
}

422 Unprocessable Entity

Ocorre quando isAvailable: true sem startTime/endTime (code: OVERRIDE_WINDOW_REQUIRED) ou o profissional não existe na instância.

json

{
  "message": "Informe o horário de início e fim da abertura extra",
  "code": "OVERRIDE_WINDOW_REQUIRED"
}

Obter Exceção por ID

http

GET /v1/booking/user/overrides/:id

Retorna a exceção com o profissional embutido. Responde 404 quando não existe na instância.

Atualizar Exceção

http

PUT /v1/booking/user/overrides/:id

Aceita os mesmos campos da criação — inclusive a regra de janela obrigatória quando isAvailable: true. Responde 204 em caso de sucesso.

Remover Exceção

http

DELETE /v1/booking/user/overrides/:id

Soft delete. Responde 204 em caso de sucesso.

Disponibilidade e Exceções ​

Escalas (Availabilities) ​

Listar Escalas ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Escala ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Escala por ID ​

Atualizar Escala ​

Remover Escala ​

Exceções (Overrides) ​

Listar Exceções ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Exceção ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Exceção por ID ​

Atualizar Exceção ​

Remover Exceção ​

Disponibilidade e Exceções

Escalas (Availabilities)

Listar Escalas

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Escala

Payload (Body)

Exemplo de Requisição

Respostas

Obter Escala por ID

Atualizar Escala

Remover Escala

Exceções (Overrides)

Listar Exceções

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Exceção

Payload (Body)

Exemplo de Requisição

Respostas

Obter Exceção por ID

Atualizar Exceção

Remover Exceção