Instâncias & Setup

Uma instância Booking é a unidade agendável do seu negócio dentro da plataforma: a barbearia, a clínica, o consultório. Serviços, profissionais, escalas e agendamentos vivem dentro dela. Antes de usar qualquer endpoint do Booking (/v1/booking/...), você precisa provisionar uma instância — e é isso que estes endpoints fazem.

A criação é mais do que um simples INSERT: em uma única transação, a plataforma cria a instância com suas políticas de agenda e o primeiro usuário staff com papel de owner, devolvendo as credenciais de acesso e o tokenHeader que identifica a instância em todas as chamadas seguintes.

Headers obrigatórios

Estes endpoints pertencem à área do dono da conta na plataforma. Todas as requisições exigem Authorization: Bearer {token} (autenticação da plataforma, guard user) e o parâmetro de query workspaceId com o ID do projeto. O header X-Booking-Id não é usado aqui — ele é o tokenHeader gerado na criação da instância. Limite de 100 requisições por minuto (429 ao exceder).

Estrutura de Dados Principal

Uma instância Booking contém as seguintes informações principais:

Campo	Tipo	Descrição
`name`	`String`	Nome da unidade (máx. 150 caracteres).
`slug`	`String`	Slug gerado automaticamente a partir do nome, único por workspace.
`tokenHeader`	`String`	UUID que identifica a instância — usado como `X-Booking-Id` nas APIs `/v1/booking/**`.
`timezone`	`String`	Fuso horário da unidade (padrão: `America/Sao_Paulo`) — rege toda a matemática da agenda.
`email` / `phone` / `address`	`String`	Contato e endereço exibidos ao cliente (opcionais).
`slotIntervalMinutes`	`Number`	Granularidade da grade de horários (1 a 480, padrão: `15`).
`minAdvanceMinutes`	`Number`	Antecedência mínima para agendar (padrão: `60`).
`maxAdvanceDays`	`Number`	Antecedência máxima, em dias (padrão: `90`).
`cancellationDeadlineMinutes`	`Number`	Prazo limite para o cliente cancelar pelo portal (padrão: `120`).
`isAllowGuestBooking`	`Boolean`	Permite agendamento sem cadastro (padrão: `true`).
`isAutoConfirm`	`Boolean`	Confirma agendamentos automaticamente quando nenhum serviço exige confirmação (padrão: `false`).
`isActive`	`Boolean`	Indica se a instância está ativa.
`workspaceStorageId`	`Number`	Provedor de armazenamento do projeto (nulo se não vinculado).
`workspaceMailId`	`Number`	Provedor de e-mail do projeto (nulo se não vinculado).

Escolhendo as políticas

O slotIntervalMinutes define os "degraus" da grade (15 min = horários 10:00, 10:15, 10:30…). Os buffers de cada serviço se somam à duração no bloqueio da agenda, mas não aparecem para o cliente. O cancellationDeadlineMinutes só é aplicado no portal do cliente — o staff pode cancelar a qualquer momento.

Setup Inicial

O POST /user/bookings executa todo o provisionamento em uma única transação — se qualquer etapa falhar, nada é persistido:

Instância: criada com nome, slug único no workspace, tokenHeader (UUID) e políticas.
Domínios: os workspaceDomains informados são vinculados à instância — sem eles, as APIs /v1/booking/** recusam requisições (401 por origem não autorizada).
Primeiro usuário staff: criado com o e-mail do usuário autenticado na plataforma, papel owner e senha temporária aleatória.
Resposta 201: inclui email, password (senha temporária, exibida uma única vez) e tokenHeader.

Guarde a senha temporária e o tokenHeader imediatamente — eles não podem ser recuperados depois (o token pode ser regerado, a senha não).

Endpoints

Listar Instâncias

Lista as instâncias Booking do projeto, com paginação e busca por nome.

http

GET /user/bookings

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`workspaceId`	`number`	Sim	ID do projeto (workspace) ao qual a instância pertence.
`page`	`number`	Não	O número da página (mínimo: 1).
`perPage`	`number`	Não	Itens por página (entre 1 e 100, padrão: 25).
`search`	`string`	Não	Busca por termo no nome da instância (máx. 150 caracteres).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/user/bookings?workspaceId=1&page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de instâncias, ordenadas da mais recente para a mais antiga.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "2",
      "name": "Studio Beleza - Filial 2",
      "slug": "studio-beleza-filial-2",
      "tokenHeader": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

403 Forbidden

Ocorre quando o workspaceId não é informado ou o projeto pertence a outro usuário.

json

{
  "notice": "O projeto precisa ser informado",
  "field": "workspaceId"
}

Criar Instância

Provisiona uma nova instância Booking, executando o setup inicial completo em transação.

http

POST /user/bookings

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`booking.name`	`string`	Sim	Nome da unidade (máx. 150 caracteres).
`booking.workspaceStorageId`	`number`	Não	ID do provedor de armazenamento do projeto (deve existir e estar ativo).
`booking.workspaceMailId`	`number`	Não	ID do provedor de e-mail do projeto (deve existir e estar ativo).
`booking.timezone`	`string`	Não	Fuso horário (máx. 64 caracteres, padrão: `America/Sao_Paulo`).
`booking.email`	`string`	Não	E-mail de contato da unidade (válido, máx. 250 caracteres).
`booking.phone`	`string`	Não	Telefone de contato (máx. 50 caracteres).
`booking.address`	`string`	Não	Endereço da unidade (máx. 255 caracteres).
`booking.slotIntervalMinutes`	`number`	Não	Granularidade da grade (1 a 480, padrão: `15`).
`booking.minAdvanceMinutes`	`number`	Não	Antecedência mínima em minutos (mín. 0, padrão: `60`).
`booking.maxAdvanceDays`	`number`	Não	Antecedência máxima em dias (mín. 1, padrão: `90`).
`booking.cancellationDeadlineMinutes`	`number`	Não	Prazo de cancelamento do cliente em minutos (mín. 0, padrão: `120`).
`booking.isAllowGuestBooking`	`boolean`	Não	Aceita agendamento sem cadastro (padrão: `true`).
`booking.isAutoConfirm`	`boolean`	Não	Confirmação automática (padrão: `false`).
`booking.isActive`	`boolean`	Não	Indica se a instância já nasce ativa (padrão: `true`).
`workspaceDomains`	`number[]`	Sim	IDs dos domínios do projeto vinculados à instância (pode ser um array vazio).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/user/bookings?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "booking": {
      "name": "Studio Beleza",
      "timezone": "America/Sao_Paulo",
      "slotIntervalMinutes": 15,
      "isAutoConfirm": true,
      "workspaceStorageId": null,
      "workspaceMailId": null
    },
    "workspaceDomains": [3]
  }'

Respostas

201 Created

Retorna as credenciais do primeiro usuário staff e o token da instância. A senha temporária é exibida uma única vez.

json

{
  "email": "maria@studio.com",
  "password": "a1b2c3d4",
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json

{
  "errors": [
    {
      "message": "Nome é obrigatório",
      "rule": "required",
      "field": "booking.name"
    }
  ]
}

Obter Instância por ID

Recupera os detalhes de uma instância, incluindo os domínios, o provedor de armazenamento e o provedor de e-mail vinculados.

http

GET /user/bookings/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID da instância.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/user/bookings/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna a instância com workspaceDomains, workspaceStorage e workspaceMail.

json

{
  "id": "1",
  "workspaceId": "1",
  "workspaceMailId": null,
  "workspaceStorageId": null,
  "name": "Studio Beleza",
  "slug": "studio-beleza",
  "timezone": "America/Sao_Paulo",
  "email": "contato@studiobeleza.com",
  "phone": "11999990000",
  "address": "Rua das Flores, 100",
  "slotIntervalMinutes": 15,
  "minAdvanceMinutes": 60,
  "maxAdvanceDays": 90,
  "cancellationDeadlineMinutes": 120,
  "isAllowGuestBooking": true,
  "isAutoConfirm": true,
  "isActive": true,
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAt": "2026-09-01T10:05:33.000+00:00",
  "updatedAt": "2026-09-01T10:05:33.000+00:00",
  "deletedAt": null,
  "workspaceDomains": [
    {
      "id": "3",
      "uri": "studio.local"
    }
  ],
  "workspaceStorage": null,
  "workspaceMail": null
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Atualizar Instância

Atualiza as configurações e políticas de uma instância e sincroniza os domínios vinculados. O slug e o tokenHeader não mudam, e o usuário owner não é recriado.

http

PUT /user/bookings/:id

Payload (Body)

Aceita os mesmos campos da criação: o objeto booking e o array workspaceDomains (que substitui os vínculos atuais).

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/user/bookings/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "booking": {
      "name": "Studio Beleza",
      "cancellationDeadlineMinutes": 240,
      "isAutoConfirm": false,
      "workspaceStorageId": null,
      "workspaceMailId": null
    },
    "workspaceDomains": [3]
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Remover Instância

Remove uma instância via soft delete — o registro deixa de aparecer em qualquer consulta, mas não é apagado fisicamente.

http

DELETE /user/bookings/:id

Exemplo de Requisição

bash

curl -X DELETE "https://api.us.basis.tavares.in/user/bookings/1?workspaceId=1" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Retorna as instâncias em formato simplificado (value/label), ideal para selects no frontend.

http

GET /user/bookings/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`workspaceId`	`number`	Sim	ID do projeto (workspace).
`search`	`string`	Não	Busca por termo no nome da instância (máx. 150 caracteres).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/user/bookings/list?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um array com as instâncias ordenadas por nome.

json

[
  {
    "value": 1,
    "label": "Studio Beleza"
  },
  {
    "value": 2,
    "label": "Studio Beleza - Filial 2"
  }
]

Regerar Token da Instância

Gera um novo tokenHeader (UUID) para a instância. O token anterior deixa de ser válido imediatamente — todas as integrações que usam o header X-Booking-Id precisam ser atualizadas.

http

PATCH /user/bookings/:id/change-token

Exemplo de Requisição

bash

curl -X PATCH "https://api.us.basis.tavares.in/user/bookings/1/change-token?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o novo token da instância.

json

{
  "tokenHeader": "9b2f7c1e-4d3a-4e5f-8a6b-1c2d3e4f5a6b"
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Instâncias & Setup ​

Estrutura de Dados Principal ​

Setup Inicial ​

Endpoints ​

Listar Instâncias ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Instância ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Instância por ID ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Atualizar Instância ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Remover Instância ​

Exemplo de Requisição ​

Respostas ​

Listar para Dropdown ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Regerar Token da Instância ​

Exemplo de Requisição ​

Respostas ​

Instâncias & Setup

Estrutura de Dados Principal

Setup Inicial

Endpoints

Listar Instâncias

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Instância

Payload (Body)

Exemplo de Requisição

Respostas

Obter Instância por ID

Parâmetros de Rota

Exemplo de Requisição

Respostas

Atualizar Instância

Payload (Body)

Exemplo de Requisição

Respostas

Remover Instância

Exemplo de Requisição

Respostas

Listar para Dropdown

Parâmetros de Query

Exemplo de Requisição

Respostas

Regerar Token da Instância

Exemplo de Requisição

Respostas