Basis

Appearance

Disponibilidade & Exceções ​

A agenda de funcionamento do que se vende é montada em duas camadas:

  • Janelas de disponibilidade (availability windows): a grade semanal — em quais dias da semana (dayOfWeek, de 0 = domingo a 6 = sábado) e em quais horários (startTime/endTime) o tipo de recurso opera, com a duração de cada slot vendável (slotDurationMinutes) e a vigência da grade (validFrom/validUntil). Uma janela pode ser por tipo (tourResourceTypeId — vale para todas as unidades) ou por recurso (tourResourceId — exceção pontual de uma unidade física).
  • Exceções de calendário (calendar exceptions): datas fora da grade — feriados em que o estabelecimento fecha (isClosed: true) ou dias com horário especial (isClosed: false + startTime/endTime sobrescrevendo a janela daquele dia).

As reservas só podem ser criadas dentro das janelas vigentes e fora das exceções de fechamento (ver Reservas & Alocações).

Headers obrigatórios

Todas as requisições devem incluir o header X-Tour-Id (UUID) com o identificador da instância e Authorization: Bearer {token} com o token de um usuário staff (guard toursUser). Não há endpoints públicos nesta página.

Permissão

As mutações (criar, atualizar e remover) exigem a permissão settings.manage. A consulta é livre para qualquer usuário staff autenticado. Nenhum dos dois recursos possui endpoint de lista simplificada (/list).

Janelas de Disponibilidade (Availability Windows) ​

Listar Janelas ​

Lista as janelas de disponibilidade da instância, com paginação e filtros por tipo, recurso e dia da semana.

http
GET /v1/tours/user/availability-windows

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
pagenumberNãoO número da página (mínimo: 1).
perPagenumberNãoItens por página (entre 1 e 100).
tourResourceTypeIdnumberNãoFiltra por tipo de recurso.
tourResourceIdnumberNãoFiltra por recurso físico.
dayOfWeeknumberNãoFiltra por dia da semana (0 = domingo … 6 = sábado).
fromstringNãoVigência a partir de, no formato YYYY-MM-DD.
tostringNãoVigência até, no formato YYYY-MM-DD.
orderByenumNãoid, dayOfWeek, startTime ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/availability-windows?dayOfWeek=0" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

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

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": []
}

Criar Janela ​

Cadastra uma janela semanal para um tipo ou recurso. Exige a permissão settings.manage.

http
POST /v1/tours/user/availability-windows

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourResourceTypeIdnumberNãoID do tipo de recurso — janela vale para todas as unidades do tipo.
tourResourceIdnumberNãoID do recurso físico — janela específica de uma unidade.
dayOfWeeknumberSimDia da semana (0 = domingo … 6 = sábado).
startTimestringSimHorário de abertura, no formato HH:mm.
endTimestringSimHorário de fechamento, no formato HH:mm.
slotDurationMinutesnumberNãoDuração de cada slot vendável, em minutos (mín. 1).
validFromstringNãoInício da vigência, no formato YYYY-MM-DD (null = sem início).
validUntilstringNãoFim da vigência, no formato YYYY-MM-DD (null = sem fim).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/availability-windows" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourResourceTypeId": 1,
    "dayOfWeek": 0,
    "startTime": "08:00",
    "endTime": "18:00",
    "slotDurationMinutes": 120,
    "validFrom": "2026-10-07",
    "validUntil": "2027-10-07"
  }'

Respostas ​

201 Created

Retorna o ID da janela criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o payload é inválido (horário fora do formato HH:mm, dia fora de 0–6) ou o tipo/recurso informado não existe na instância.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão settings.manage (code: FORBIDDEN).

Obter Janela por ID ​

Recupera os detalhes de uma janela de disponibilidade.

http
GET /v1/tours/user/availability-windows/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da janela.

Respostas ​

200 OK

Retorna a janela com o tipo/recurso relacionado. Os horários são serializados como timestamps ISO na data de referência.

json
{
  "id": 4,
  "tourId": 1,
  "tourResourceTypeId": 1,
  "tourResourceId": null,
  "dayOfWeek": 0,
  "startTime": "2026-10-07T08:00:00.000-03:00",
  "endTime": "2026-10-07T18:00:00.000-03:00",
  "slotDurationMinutes": 120,
  "validFrom": "2026-10-07",
  "validUntil": "2027-10-07",
  "createdAt": "2026-10-07T15:10:36.721-03:00",
  "updatedAt": "2026-10-07T15:10:36.721-03:00",
  "toursResource": null,
  "toursResourceType": {
    "id": 1,
    "code": "SJZSKZ",
    "name": "Frozen Marble Chair"
  }
}

404 Not Found

Ocorre quando a janela não existe na instância.

Atualizar Janela ​

Atualiza dia, horários, duração do slot ou vigência de uma janela. Exige a permissão settings.manage.

http
PUT /v1/tours/user/availability-windows/:id

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais — envie apenas o que deve mudar.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/availability-windows/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourResourceTypeId": 1,
    "dayOfWeek": 0,
    "startTime": "09:00",
    "endTime": "19:00",
    "slotDurationMinutes": 120,
    "validFrom": "2026-10-07",
    "validUntil": "2027-10-07"
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão settings.manage (code: FORBIDDEN).

Remover Janela ​

Remove uma janela via soft delete. Exige a permissão settings.manage.

http
DELETE /v1/tours/user/availability-windows/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão settings.manage (code: FORBIDDEN).

Exceções de Calendário (Calendar Exceptions) ​

Listar Exceções ​

Lista as exceções de calendário da instância, com paginação e filtros por tipo, período e tipo de exceção.

http
GET /v1/tours/user/calendar-exceptions

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
pagenumberNãoO número da página (mínimo: 1).
perPagenumberNãoItens por página (entre 1 e 100).
tourResourceTypeIdnumberNãoFiltra por tipo de recurso.
fromstringNãoExceções a partir de, no formato YYYY-MM-DD.
tostringNãoExceções até, no formato YYYY-MM-DD.
isClosedbooleanNãotrue para fechamentos; false para horários especiais.
orderByenumNãoid, onDate ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/calendar-exceptions?isClosed=true&from=2026-12-01&to=2026-12-31" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -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": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourResourceTypeId": 1,
      "onDate": "2026-10-15",
      "isClosed": true,
      "startTime": null,
      "endTime": null,
      "reason": "Cunctatio claro antiquus atavus compono cognatus.",
      "createdAt": "2026-10-07T11:56:14.222-03:00",
      "updatedAt": "2026-10-07T11:56:14.222-03:00"
    }
  ]
}

Criar Exceção ​

Cadastra um fechamento ou horário especial em uma data. Exige a permissão settings.manage.

http
POST /v1/tours/user/calendar-exceptions

Payload (Body) ​

AtributoTipoObrigatórioDescrição
onDatestringSimData da exceção, no formato YYYY-MM-DD.
tourResourceTypeIdnumberNãoID do tipo de recurso afetado (deve existir na instância).
isClosedbooleanNãotrue fecha o dia inteiro; false aplica o horário especial abaixo.
startTimestringNãoAbertura no horário especial, no formato HH:mm.
endTimestringNãoFechamento no horário especial, no formato HH:mm.
reasonstringNãoMotivo da exceção (máx. 255 caracteres), ex.: Fechado no Natal.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/calendar-exceptions" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "onDate": "2026-12-25",
    "tourResourceTypeId": 1,
    "isClosed": true,
    "reason": "Fechado no Natal"
  }'

Respostas ​

201 Created

Retorna o ID da exceção criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o payload é inválido ou o tipo de recurso informado não existe na instância.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão settings.manage (code: FORBIDDEN).

Obter Exceção por ID ​

Recupera os detalhes de uma exceção de calendário.

http
GET /v1/tours/user/calendar-exceptions/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da exceção.

Respostas ​

200 OK

Retorna a exceção com o tipo de recurso relacionado.

json
{
  "id": 4,
  "tourId": 1,
  "tourResourceTypeId": 1,
  "onDate": "2026-12-25",
  "isClosed": true,
  "startTime": null,
  "endTime": null,
  "reason": "Fechado no Natal",
  "createdAt": "2026-10-07T15:10:39.255-03:00",
  "updatedAt": "2026-10-07T15:10:39.255-03:00",
  "toursResourceType": {
    "id": 1,
    "code": "SJZSKZ",
    "name": "Frozen Marble Chair"
  }
}

404 Not Found

Ocorre quando a exceção não existe na instância.

Atualizar Exceção ​

Atualiza data, tipo, horários ou motivo de uma exceção. Exige a permissão settings.manage.

http
PUT /v1/tours/user/calendar-exceptions/:id

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais — envie apenas o que deve mudar.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/calendar-exceptions/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "onDate": "2026-12-25",
    "tourResourceTypeId": 1,
    "isClosed": true,
    "reason": "Fechado no Natal (editado)"
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão settings.manage (code: FORBIDDEN).

Remover Exceção ​

Remove uma exceção via soft delete — o dia volta a seguir a grade semanal normal. Exige a permissão settings.manage.

http
DELETE /v1/tours/user/calendar-exceptions/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão settings.manage (code: FORBIDDEN).