Catálogo de Serviços

O catálogo é o que a unidade vende e o que a agenda consome. Três recursos trabalham juntos:

Categorias agrupam os serviços no menu do cliente ("Cabelo", "Barba", "Estética") — evitam uma lista de 40 serviços solta na tela de agendamento.
Serviços são o que se vende. O campo central é durationMinutes, que o algoritmo usa para encaixar o cliente na grade. Junto vêm os buffers (preparo/limpeza que bloqueiam a agenda, mas não são cobrados nem exibidos) e a capacity, que separa atendimento exclusivo de sessão em grupo.
Recursos são o que é fisicamente disputado além da pessoa: cadeira, sala, equipamento. Sem eles, o sistema aceitaria dois agendamentos válidos que na prática brigam pelo mesmo espaço.

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 (index/show/list) é livre para qualquer papel autenticado; a escrita exige owner ou manager (403 FORBIDDEN caso contrário).

Categorias de Serviço

Agrupamento puramente organizacional, com sortOrder para controlar a ordem de exibição no menu.

Listar Categorias

http

GET /v1/booking/user/service-categories

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page` / `perPage`	`number`	Não	Paginação (máx. 100 por página).
`search`	`string`	Não	Busca por nome.
`isActive`	`boolean`	Não	Filtra por categorias ativas/inativas.
`orderBy`	`enum`	Não	`id`, `name`, `sortOrder` ou `createdAt` (padrão: `sortOrder`).
`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/service-categories?isActive=true" \
  -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 categorias no formato meta/data, ordenadas por sortOrder.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "bookingId": 1,
      "name": "Cabelo",
      "slug": "cabelo",
      "sortOrder": 0,
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

Criar Categoria

http

POST /v1/booking/user/service-categories

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome da categoria (máx. 150 caracteres). O `slug` é gerado a partir dele, único por instância.
`sortOrder`	`number`	Não	Ordem de exibição (mín. 0, padrão: `0`).
`isActive`	`boolean`	Não	Indica se já nasce ativa (padrão: `true`).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/service-categories" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cabelo" }'

Respostas

201 Created

Retorna o ID da categoria criada.

json

{
  "id": 1
}

Obter Categoria por ID

http

GET /v1/booking/user/service-categories/:id

Retorna a categoria com seus serviços (bookingServices). Responde 404 quando não existe na instância.

Atualizar Categoria

http

PUT /v1/booking/user/service-categories/:id

Aceita os mesmos campos da criação. O slug é regenerado apenas quando o nome muda. Responde 204 em caso de sucesso.

Remover Categoria

http

DELETE /v1/booking/user/service-categories/:id

Soft delete — a categoria some das listagens; os serviços vinculados não são removidos. Responde 204 em caso de sucesso.

http

GET /v1/booking/user/service-categories/list

Retorna [{ "value", "label" }] com search e isActive opcionais — ideal para o select de categoria no formulário de serviço.

Serviços

O item vendável. durationMinutes + buffers determinam quanto tempo da agenda o serviço ocupa; price é o valor de tabela (cada profissional pode ter preço e duração próprios).

Listar Serviços

http

GET /v1/booking/user/services

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page` / `perPage`	`number`	Não	Paginação (máx. 100 por página).
`search`	`string`	Não	Busca por nome.
`bookingServiceCategoryId`	`number`	Não	Filtra por categoria.
`isActive`	`boolean`	Não	Filtra por ativos/inativos.
`isBookableOnline`	`boolean`	Não	Filtra os agendáveis pelo portal do cliente.
`orderBy`	`enum`	Não	`id`, `name`, `sortOrder`, `price` ou `createdAt` (padrão: `sortOrder`).
`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/services?bookingServiceCategoryId=1&isBookableOnline=true" \
  -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 serviços com a categoria embutida em cada item.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "bookingId": 1,
      "bookingServiceCategoryId": 1,
      "name": "Corte Masculino",
      "slug": "corte-masculino",
      "price": "80.00",
      "durationMinutes": 45,
      "capacity": 1,
      "isBookableOnline": true,
      "sortOrder": 0,
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00",
      "bookingServiceCategory": {
        "id": 1,
        "name": "Cabelo"
      }
    }
  ]
}

Criar Serviço

http

POST /v1/booking/user/services

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome do serviço (máx. 150 caracteres). O `slug` é gerado a partir dele, único por instância.
`price`	`number`	Sim	Preço de tabela (mín. 0).
`durationMinutes`	`number`	Sim	Duração do atendimento em minutos (mín. 1) — é o que a grade usa para encaixar o cliente.
`bookingServiceCategoryId`	`number`	Não	Categoria do serviço (deve existir na instância).
`description`	`string`	Não	Descrição exibida no portal (máx. 10000 caracteres).
`bufferBeforeMinutes`	`number`	Não	Preparo antes do atendimento — bloqueia a agenda, não é cobrado (mín. 0, padrão: `0`).
`bufferAfterMinutes`	`number`	Não	Limpeza/intervalo depois do atendimento (mín. 0, padrão: `0`).
`capacity`	`number`	Não	Atendimentos simultâneos no mesmo horário (mín. 1, padrão: `1`) — acima de 1 = sessão em grupo.
`isRequiresConfirmation`	`boolean`	Não	Exige confirmação manual mesmo com `isAutoConfirm` ligado na instância (padrão: `false`).
`isBookableOnline`	`boolean`	Não	Visível e agendável no portal do cliente (padrão: `true`).
`colorCode`	`string`	Não	Cor na agenda visual (máx. 20 caracteres).
`imageUrl`	`string`	Não	Imagem do serviço (máx. 255 caracteres).
`sortOrder`	`number`	Não	Ordem de exibição (mín. 0, padrão: `0`).
`isActive`	`boolean`	Não	Indica se já nasce ativo (padrão: `true`).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/services" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingServiceCategoryId": 1,
    "name": "Corte Masculino",
    "price": 80,
    "durationMinutes": 45,
    "bufferAfterMinutes": 15,
    "isBookableOnline": true
  }'

Respostas

201 Created

Retorna o ID do serviço criado.

json

{
  "id": 1
}

422 Unprocessable Entity

Ocorre quando a categoria não existe na instância ou o payload é inválido.

json

{
  "errors": [
    {
      "message": "Categoria de serviço não encontrada",
      "rule": "database.exists",
      "field": "bookingServiceCategoryId"
    }
  ]
}

Obter Serviço por ID

http

GET /v1/booking/user/services/:id

Retorna o serviço completo (descrição, buffers, flags) com a categoria. Responde 404 quando não existe na instância.

Atualizar Serviço

http

PUT /v1/booking/user/services/:id

Aceita os mesmos campos da criação. O slug é regenerado apenas quando o nome muda. Responde 204 em caso de sucesso.

Remover Serviço

http

DELETE /v1/booking/user/services/:id

Soft delete. Agendamentos já criados preservam nome, preço e duração congelados — remover o serviço não afeta o histórico. Responde 204 em caso de sucesso.

http

GET /v1/booking/user/services/list

Retorna [{ "value", "label" }] com search, bookingServiceCategoryId, isActive e isBookableOnline opcionais.

Recursos

Cadeiras, salas, equipamentos — qualquer coisa fisicamente disputada além do profissional. Um recurso se torna obrigatório para um serviço via vínculo serviço ↔ recurso; na criação do agendamento, o sistema aloca automaticamente o primeiro recurso livre e falha com 422 RESOURCE_UNAVAILABLE se todos estiverem ocupados.

Listar Recursos

http

GET /v1/booking/user/resources

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page` / `perPage`	`number`	Não	Paginação (máx. 100 por página).
`search`	`string`	Não	Busca por nome.
`type`	`string`	Não	Filtra por tipo livre (`room`, `chair`, `equipment`…).
`isActive`	`boolean`	Não	Filtra por ativos/inativos.
`orderBy`	`enum`	Não	`id`, `name` ou `createdAt` (padrão: `id`).
`orderDirection`	`enum`	Não	`asc` ou `desc` (padrão: `desc`).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/resources?type=room" \
  -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 recursos no formato meta/data.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "bookingId": 1,
      "name": "Sala 1",
      "type": "room",
      "capacity": 1,
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

Criar Recurso

http

POST /v1/booking/user/resources

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome do recurso (máx. 150 caracteres).
`type`	`string`	Não	Tipo livre para agrupar (máx. 100 caracteres).
`capacity`	`number`	Não	Capacidade do recurso (mín. 1, padrão: `1`).
`isActive`	`boolean`	Não	Indica se já nasce ativo (padrão: `true`).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/resources" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sala 1", "type": "room" }'

Respostas

201 Created

Retorna o ID do recurso criado.

json

{
  "id": 1
}

Obter Recurso por ID

http

GET /v1/booking/user/resources/:id

Responde 404 quando não existe na instância.

Atualizar Recurso

http

PUT /v1/booking/user/resources/:id

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

Remover Recurso

http

DELETE /v1/booking/user/resources/:id

Soft delete. Responde 204 em caso de sucesso.

http

GET /v1/booking/user/resources/list

Retorna [{ "value", "label" }] com search, type e isActive opcionais.

Catálogo de Serviços ​

Categorias de Serviço ​

Listar Categorias ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Categoria ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Categoria por ID ​

Atualizar Categoria ​

Remover Categoria ​

Listar para Dropdown ​

Serviços ​

Listar Serviços ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Serviço ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Serviço por ID ​

Atualizar Serviço ​

Remover Serviço ​

Listar para Dropdown ​

Recursos ​

Listar Recursos ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Recurso ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Recurso por ID ​

Atualizar Recurso ​

Remover Recurso ​

Listar para Dropdown ​

Catálogo de Serviços

Categorias de Serviço

Listar Categorias

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Categoria

Payload (Body)

Exemplo de Requisição

Respostas

Obter Categoria por ID

Atualizar Categoria

Remover Categoria

Listar para Dropdown

Serviços

Listar Serviços

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Serviço

Payload (Body)

Exemplo de Requisição

Respostas

Obter Serviço por ID

Atualizar Serviço

Remover Serviço

Listar para Dropdown

Recursos

Listar Recursos

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Recurso

Payload (Body)

Exemplo de Requisição

Respostas

Obter Recurso por ID

Atualizar Recurso

Remover Recurso

Listar para Dropdown