Profissionais e Vínculos

O profissional é quem executa o serviço. Ele fica separado do usuário staff de propósito: nem todo profissional tem login, e nem todo usuário atende cliente — a recepcionista não entra na agenda como recurso disputado.

Duas tabelas de vínculo completam o modelo:

Profissional ↔ serviço: quais serviços cada profissional faz (nem todo barbeiro faz tintura), com preço e duração customizados — o sênior cobra mais caro e é mais rápido no mesmo corte.
Serviço ↔ recurso: quais recursos um serviço exige — é o que permite alocar automaticamente a Sala 2 quando alguém marca uma sessão de laser.

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).

Profissionais

Listar Profissionais

http

GET /v1/booking/user/professionals

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 ativos/inativos.
`isBookableOnline`	`boolean`	Não	Filtra os agendáveis pelo portal do cliente.
`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/professionals?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 profissionais no formato meta/data.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "bookingId": 1,
      "bookingUserId": 2,
      "name": "Ana Souza",
      "slug": "ana-souza",
      "email": "ana.souza@studio.com",
      "phone": "11999990000",
      "avatarUrl": null,
      "colorCode": "#EC4899",
      "isBookableOnline": true,
      "sortOrder": 0,
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

Criar Profissional

http

POST /v1/booking/user/professionals

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome exibido na agenda e no portal (máx. 150 caracteres). O `slug` é gerado a partir dele, único por instância.
`bookingUserId`	`number`	Não	Vínculo com um usuário staff (deve existir na instância) — é o que libera a "própria agenda" para o papel `professional`.
`email`	`string`	Não	E-mail de contato (válido, máx. 250 caracteres).
`phone`	`string`	Não	Telefone (máx. 50 caracteres).
`bio`	`string`	Não	Bio exibida no portal (máx. 5000 caracteres).
`avatarUrl`	`string`	Não	Foto (máx. 255 caracteres).
`colorCode`	`string`	Não	Cor na agenda visual (máx. 20 caracteres).
`timezone`	`string`	Não	Fuso próprio (máx. 64 caracteres) — cobre o consultor remoto que atende de outro fuso.
`isBookableOnline`	`boolean`	Não	Agendável pelo portal do cliente (padrão: `true`).
`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/professionals" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "bookingUserId": 2,
    "colorCode": "#EC4899",
    "isBookableOnline": true
  }'

Respostas

201 Created

Retorna o ID do profissional criado.

json

{
  "id": 1
}

422 Unprocessable Entity

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

Obter Profissional por ID

http

GET /v1/booking/user/professionals/:id

Retorna o profissional completo (bio, timezone) com o usuário vinculado (bookingUser com id, firstName, lastName, email). Responde 404 quando não existe na instância.

Atualizar Profissional

http

PUT /v1/booking/user/professionals/:id

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

Remover Profissional

http

DELETE /v1/booking/user/professionals/:id

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

http

GET /v1/booking/user/professionals/list

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

Serviços do Profissional

Vínculo profissional ↔ serviço. Sem o vínculo, o profissional não aparece como opção ao agendar aquele serviço — e a criação do agendamento falha com 422 PROFESSIONAL_SERVICE_MISMATCH. O vínculo aceita preço e duração customizados, que prevalecem sobre a tabela do serviço.

Listar Vínculos

http

GET /v1/booking/user/professional-services

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.
`bookingServiceId`	`number`	Não	Filtra por serviço.

Respostas

200 OK

Retorna a página de vínculos com profissional e serviço embutidos.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "bookingId": 1,
      "bookingProfessionalId": 1,
      "bookingServiceId": 1,
      "customPrice": "120.00",
      "customDurationMinutes": 60,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00",
      "bookingProfessional": { "id": 1, "name": "Ana Souza" },
      "bookingService": { "id": 1, "name": "Corte Masculino" }
    }
  ]
}

Vincular Serviço ao Profissional

http

POST /v1/booking/user/professional-services

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`bookingProfessionalId`	`number`	Sim	Profissional (deve existir na instância).
`bookingServiceId`	`number`	Sim	Serviço (deve existir na instância).
`customPrice`	`number`	Não	Preço customizado (mín. 0) — prevalece sobre o preço de tabela.
`customDurationMinutes`	`number`	Não	Duração customizada em minutos (mín. 1) — prevalece sobre a duração padrão.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/professional-services" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingProfessionalId": 1,
    "bookingServiceId": 1,
    "customPrice": 120,
    "customDurationMinutes": 60
  }'

Respostas

201 Created

Retorna o ID do vínculo criado.

json

{
  "id": 1
}

422 Unprocessable Entity

Ocorre quando o vínculo já existe ("Este serviço já está vinculado ao profissional") ou um dos lados não existe na instância.

Atualizar Vínculo

http

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

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`customPrice`	`number`	Não	Novo preço customizado (`null` volta ao preço de tabela).
`customDurationMinutes`	`number`	Não	Nova duração customizada (`null` volta à duração padrão).

Responde 204 em caso de sucesso.

Remover Vínculo

http

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

Soft delete. Responde 204 em caso de sucesso.

Recursos do Serviço

Vínculo serviço ↔ recurso. Quando isRequired é true, o agendamento do serviço aloca automaticamente o primeiro recurso vinculado que estiver ativo e livre na janela — e falha com 422 RESOURCE_UNAVAILABLE se nenhum estiver disponível.

Listar Vínculos

http

GET /v1/booking/user/service-resources

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page` / `perPage`	`number`	Não	Paginação (máx. 100 por página).
`bookingServiceId`	`number`	Não	Filtra por serviço.
`bookingResourceId`	`number`	Não	Filtra por recurso.

Vincular Recurso ao Serviço

http

POST /v1/booking/user/service-resources

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`bookingServiceId`	`number`	Sim	Serviço (deve existir na instância).
`bookingResourceId`	`number`	Sim	Recurso (deve existir na instância).
`isRequired`	`boolean`	Não	Indica se o recurso é obrigatório para o agendamento (padrão: `false`).

Exemplo de Requisição

bash

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

Respostas

201 Created

Retorna o ID do vínculo criado.

json

{
  "id": 1
}

422 Unprocessable Entity

Ocorre quando o vínculo já existe ("Este recurso já está vinculado ao serviço") ou um dos lados não existe na instância.

Atualizar Vínculo

http

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

Altera apenas isRequired. Responde 204 em caso de sucesso.

Remover Vínculo

http

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

Soft delete. Responde 204 em caso de sucesso.

Profissionais e Vínculos ​

Profissionais ​

Listar Profissionais ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Profissional ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Profissional por ID ​

Atualizar Profissional ​

Remover Profissional ​

Listar para Dropdown ​

Serviços do Profissional ​

Listar Vínculos ​

Parâmetros de Query ​

Respostas ​

Vincular Serviço ao Profissional ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Atualizar Vínculo ​

Payload (Body) ​

Remover Vínculo ​

Recursos do Serviço ​

Listar Vínculos ​

Parâmetros de Query ​

Vincular Recurso ao Serviço ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Atualizar Vínculo ​

Remover Vínculo ​

Profissionais e Vínculos

Profissionais

Listar Profissionais

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Profissional

Payload (Body)

Exemplo de Requisição

Respostas

Obter Profissional por ID

Atualizar Profissional

Remover Profissional

Listar para Dropdown

Serviços do Profissional

Listar Vínculos

Parâmetros de Query

Respostas

Vincular Serviço ao Profissional

Payload (Body)

Exemplo de Requisição

Respostas

Atualizar Vínculo

Payload (Body)

Remover Vínculo

Recursos do Serviço

Listar Vínculos

Parâmetros de Query

Vincular Recurso ao Serviço

Payload (Body)

Exemplo de Requisição

Respostas

Atualizar Vínculo

Remover Vínculo