Basis

Appearance

Recursos Reserváveis ​

Tudo que pode ser reservado no estabelecimento — quarto, cama balinesa, lancha, prancha, massagem — é modelado com o mesmo par de conceitos:

  • Tipo de recurso (resource type): o que se vende. Define a natureza do produto (kind), a granularidade da reserva (granularity), duração e antecedência mínimas/máximas, buffers de turnaround, limites de ocupação e overbooking. Exemplo: "Quarto Duplo Vista Mar".
  • Recurso (resource): a unidade física que entra na agenda. Herda as regras do tipo e carrega código, zona, estado de governança e quantidade de unidades. Exemplo: "Quarto 201".

Os recursos com units = 1 são exclusivos: uma única reserva ocupa a unidade inteira (o quarto 201). Recursos com units > 1 são compartilhados: cada reserva consome uma ou mais unidades da mesma agenda — os 20 assentos da lancha (units = 20) aceitam várias reservas até esgotar a capacidade.

As zonas (resource zones) organizam os recursos fisicamente e formam uma hierarquia via parentTourResourceZoneId — ex.: "Área da Piscina" dentro de "Área Externa".

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) dos três recursos desta página exigem a permissão settings.manage. A consulta é livre para qualquer usuário staff autenticado.

Zonas de Recursos (Resource Zones) ​

Listar Zonas ​

Lista as zonas da instância, com paginação, busca e filtro por zona pai.

http
GET /v1/tours/user/resource-zones

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).
searchstringNãoBusca por código ou nome (máx. 150 caracteres).
parentTourResourceZoneIdnumberNãoFiltra pelas zonas filhas de uma zona pai.
orderByenumNãoid, code, name ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/resource-zones?search=piscina" \
  -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 zonas no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "parentTourResourceZoneId": null,
      "code": "YWEDB8",
      "name": "Shoes",
      "createdAt": "2026-10-07T11:56:13.862-03:00",
      "updatedAt": "2026-10-07T11:56:13.862-03:00"
    }
  ]
}

Criar Zona ​

Cadastra uma zona, opcionalmente dentro de outra (hierarquia). Exige a permissão settings.manage.

http
POST /v1/tours/user/resource-zones

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo único da zona (máx. 50 caracteres).
namestringSimNome da zona (máx. 150 caracteres).
parentTourResourceZoneIdnumberNãoID da zona pai — cria a hierarquia (deve existir na instância).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/resource-zones" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-ZONE-01",
    "name": "Zona Doc",
    "parentTourResourceZoneId": 1
  }'

Respostas ​

201 Created

Retorna o ID da zona criada.

json
{
  "id": 4
}

422 Unprocessable Entity

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

403 Forbidden

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

Listar Zonas para Dropdown ​

Retorna as zonas em formato simplificado (value/label), ideal para selects.

http
GET /v1/tours/user/resource-zones/list

Aceita search e limit (1 a 500) como parâmetros opcionais de query.

Exemplo de Requisição ​

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

Respostas ​

200 OK

Retorna um array com as zonas.

json
[
  {
    "value": 1,
    "label": "Shoes"
  },
  {
    "value": 4,
    "label": "Zona Doc"
  }
]

Obter Zona por ID ​

Recupera os detalhes de uma zona, incluindo a zona pai.

http
GET /v1/tours/user/resource-zones/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da zona.

Respostas ​

200 OK

Retorna a zona com a zona pai relacionada.

json
{
  "id": 4,
  "tourId": 1,
  "parentTourResourceZoneId": 1,
  "code": "DOC-ZONE-01",
  "name": "Zona Doc",
  "createdAt": "2026-10-07T15:11:04.881-03:00",
  "updatedAt": "2026-10-07T15:11:04.881-03:00",
  "parentTourResourceZone": {
    "id": 1,
    "code": "YWEDB8",
    "name": "Shoes"
  }
}

404 Not Found

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

Atualizar Zona ​

Atualiza código, nome ou zona pai. Exige a permissão settings.manage.

http
PUT /v1/tours/user/resource-zones/: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/resource-zones/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-ZONE-01",
    "name": "Zona Doc Editada",
    "parentTourResourceZoneId": 1
  }'

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 Zona ​

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

http
DELETE /v1/tours/user/resource-zones/: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).

Tipos de Recurso (Resource Types) ​

O tipo concentra as regras comerciais e operacionais compartilhadas por todas as unidades físicas:

  • kind — a natureza do que se vende: accommodation (quartos), space (camas de praia, mesas), activity (passeios), equipment (pranchas, bikes) ou service (massagens).
  • granularity — a unidade de tempo da reserva: minute, hour, night, day ou slot (janela fixa definida pela agenda de disponibilidade).
  • Duração e antecedência — minDurationMinutes/maxDurationMinutes limitam o tamanho da reserva; minLeadTimeMinutes/maxLeadTimeMinutes limitam com quanta antecedência ela pode ser feita.
  • Buffers de turnaround — bufferBeforeMinutes/bufferAfterMinutes bloqueiam a agenda antes/depois de cada ocupação (limpeza do quarto, preparação do barco). O buffer compete pela mesma agenda das reservas — nenhuma reserva colide com ele.
  • Ocupação e overbooking — defaultOccupancy (hóspedes inclusos), maxOccupancy (capacidade máxima) e overbookingLimit (quantas unidades além da capacidade física podem ser vendidas — 0 desliga).
  • requiresAssignment — quando true, a reserva precisa de um recurso físico atribuído (ver Reservas & Alocações); quando false, vende-se o tipo sem alocar unidade.

Listar Tipos ​

Lista os tipos de recurso da instância, com paginação, busca e filtros.

http
GET /v1/tours/user/resource-types

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).
searchstringNãoBusca por código ou nome (máx. 150 caracteres).
kindenumNãoaccommodation, space, activity, equipment ou service.
granularityenumNãominute, hour, night, day ou slot.
isActivebooleanNãoFiltra por tipos ativos/inativos.
orderByenumNãoid, code, name, kind ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/resource-types?kind=accommodation" \
  -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 tipos no formato meta/data.

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

Criar Tipo ​

Cadastra um tipo de recurso com suas regras. Exige a permissão settings.manage.

http
POST /v1/tours/user/resource-types

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo único do tipo (máx. 50 caracteres).
kindenumSimaccommodation, space, activity, equipment ou service.
namestringSimNome comercial do tipo (máx. 150 caracteres).
granularityenumSimminute, hour, night, day ou slot.
tourTaxGroupIdnumberNãoGrupo de impostos aplicável (deve existir na instância).
descriptionstringNãoDescrição curta (máx. 255 caracteres).
minDurationMinutesnumberNãoDuração mínima da reserva, em minutos (mín. 0).
maxDurationMinutesnumberNãoDuração máxima da reserva, em minutos (mín. 0).
minLeadTimeMinutesnumberNãoAntecedência mínima para reservar, em minutos (mín. 0).
maxLeadTimeMinutesnumberNãoAntecedência máxima para reservar, em minutos (mín. 0).
bufferBeforeMinutesnumberNãoBuffer de turnaround antes da ocupação, em minutos (padrão: 0).
bufferAfterMinutesnumberNãoBuffer de turnaround após a ocupação, em minutos (padrão: 0).
defaultOccupancynumberNãoOcupação padrão inclusa no preço (mín. 0).
maxOccupancynumberNãoOcupação máxima permitida (mín. 0).
overbookingLimitnumberNãoUnidades vendáveis além da capacidade física (padrão: 0 — desligado).
requiresAssignmentbooleanNãoSe a reserva exige atribuição de um recurso físico (padrão: false).
attributesobjectNãoAtributos livres em JSON (ex.: comodidades do quarto).
isActivebooleanNãoIndica se já nasce ativo (padrão: true).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/resource-types" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-RT-01",
    "kind": "accommodation",
    "name": "Tipo Doc",
    "granularity": "night",
    "tourTaxGroupId": 1,
    "description": "Tipo de recurso para documentação",
    "defaultOccupancy": 2,
    "maxOccupancy": 4,
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID do tipo criado.

json
{
  "id": 4
}

422 Unprocessable Entity

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

403 Forbidden

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

Listar Tipos para Dropdown ​

Retorna os tipos em formato simplificado (value/label), ideal para selects.

http
GET /v1/tours/user/resource-types/list

Aceita search, kind, isActive e limit (1 a 500) como parâmetros opcionais de query.

Exemplo de Requisição ​

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

Respostas ​

200 OK

Retorna um array com os tipos.

json
[
  {
    "value": 1,
    "label": "Frozen Marble Chair"
  },
  {
    "value": 4,
    "label": "Tipo Doc"
  }
]

Obter Tipo por ID ​

Recupera todos os detalhes e regras de um tipo de recurso.

http
GET /v1/tours/user/resource-types/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID do tipo.

Respostas ​

200 OK

Retorna o tipo com o grupo de impostos relacionado.

json
{
  "id": 4,
  "tourId": 1,
  "tourTaxGroupId": 1,
  "code": "DOC-RT-01",
  "kind": "accommodation",
  "name": "Tipo Doc",
  "description": "Tipo de recurso para documentação",
  "granularity": "night",
  "minDurationMinutes": null,
  "maxDurationMinutes": null,
  "minLeadTimeMinutes": null,
  "maxLeadTimeMinutes": null,
  "bufferBeforeMinutes": 0,
  "bufferAfterMinutes": 0,
  "defaultOccupancy": 2,
  "maxOccupancy": 4,
  "overbookingLimit": 0,
  "requiresAssignment": false,
  "attributes": {},
  "isActive": true,
  "createdAt": "2026-10-07T15:11:04.082-03:00",
  "updatedAt": "2026-10-07T15:11:04.082-03:00",
  "toursTaxGroup": {
    "id": 1,
    "code": "WMGCLJKQ",
    "name": "Electronics"
  }
}

404 Not Found

Ocorre quando o tipo não existe na instância.

Atualizar Tipo ​

Atualiza as regras de um tipo de recurso. Exige a permissão settings.manage.

http
PUT /v1/tours/user/resource-types/: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/resource-types/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-RT-01",
    "kind": "accommodation",
    "name": "Tipo Doc Editado",
    "granularity": "night",
    "tourTaxGroupId": 1,
    "description": "Tipo de recurso para documentação (editado)",
    "defaultOccupancy": 2,
    "maxOccupancy": 5,
    "isActive": true
  }'

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 Tipo ​

Remove um tipo via soft delete. Exige a permissão settings.manage.

http
DELETE /v1/tours/user/resource-types/: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).

Recursos (Resources) ​

O recurso é a unidade física que entra na agenda. Além do vínculo com tipo e zona, ele carrega:

  • units — quantidade de unidades vendáveis na mesma agenda: 1 para recursos exclusivos (o quarto inteiro), N para compartilhados (assentos da lancha, vagas do passeio).
  • maxOccupancy — sobrescreve a ocupação máxima do tipo para esta unidade específica (um quarto com cama extra).
  • housekeepingState — o estado de governança da unidade: dirty, cleaning, clean, inspected ou out_of_service (ver Governança & Manutenção).

Listar Recursos ​

Lista os recursos da instância, com paginação e filtros por tipo, zona e estado de governança.

http
GET /v1/tours/user/resources

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).
searchstringNãoBusca por código ou label (máx. 150 caracteres).
tourResourceTypeIdnumberNãoFiltra por tipo de recurso.
tourResourceZoneIdnumberNãoFiltra por zona.
housekeepingStateenumNãodirty, cleaning, clean, inspected ou out_of_service.
isActivebooleanNãoFiltra por recursos ativos/inativos.
orderByenumNãoid, code ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

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

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourResourceTypeId": 1,
      "tourResourceZoneId": 1,
      "code": "PGOXAM",
      "label": "Sleek Plastic Hat",
      "units": 1,
      "maxOccupancy": null,
      "housekeepingState": "clean",
      "isActive": true,
      "createdAt": "2026-10-07T11:56:14.123-03:00",
      "updatedAt": "2026-10-07T11:56:14.123-03:00"
    }
  ]
}

Criar Recurso ​

Cadastra uma unidade física vinculada a um tipo. Exige a permissão settings.manage.

http
POST /v1/tours/user/resources

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourResourceTypeIdnumberSimID do tipo de recurso (deve existir na instância).
codestringSimCódigo único da unidade (máx. 50 caracteres), ex.: 101, LANCHA-01.
tourResourceZoneIdnumberNãoID da zona onde a unidade fica (deve existir na instância).
labelstringNãoNome de exibição da unidade (máx. 150 caracteres).
unitsnumberNãoUnidades vendáveis na mesma agenda — 1 exclusivo, N compartilhado (padrão: 1).
maxOccupancynumberNãoOcupação máxima desta unidade — sobrescreve o tipo (mín. 0).
housekeepingStateenumNãodirty, cleaning, clean, inspected ou out_of_service (padrão: clean).
attributesobjectNãoAtributos livres em JSON (ex.: andar, vista, número de camas).
isActivebooleanNãoIndica se já nasce ativo (padrão: true).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/resources" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-01",
    "label": "Quarto Doc",
    "units": 1,
    "tourResourceTypeId": 1,
    "tourResourceZoneId": 1,
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID do recurso criado.

json
{
  "id": 5
}

422 Unprocessable Entity

Ocorre quando o payload é inválido ou o tipo/zona informados não existem na instância.

403 Forbidden

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

Listar Recursos para Dropdown ​

Retorna os recursos em formato simplificado (value/label com o código), ideal para selects — como a atribuição de unidade a uma reserva.

http
GET /v1/tours/user/resources/list

Aceita search, tourResourceTypeId, tourResourceZoneId, isActive e limit (1 a 500) como parâmetros opcionais de query.

Exemplo de Requisição ​

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

Respostas ​

200 OK

Retorna um array com os recursos.

json
[
  {
    "value": 5,
    "label": "DOC-01"
  },
  {
    "value": 1,
    "label": "PGOXAM"
  }
]

Obter Recurso por ID ​

Recupera os detalhes de uma unidade, incluindo tipo e zona relacionados.

http
GET /v1/tours/user/resources/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID do recurso.

Respostas ​

200 OK

Retorna o recurso com tipo e zona relacionados.

json
{
  "id": 5,
  "tourId": 1,
  "tourResourceTypeId": 1,
  "tourResourceZoneId": 1,
  "code": "DOC-01",
  "label": "Quarto Doc",
  "units": 1,
  "maxOccupancy": null,
  "housekeepingState": "clean",
  "attributes": {},
  "isActive": true,
  "createdAt": "2026-10-07T15:11:05.699-03:00",
  "updatedAt": "2026-10-07T15:11:05.699-03:00",
  "toursResourceZone": {
    "id": 1,
    "code": "YWEDB8",
    "name": "Shoes"
  },
  "toursResourceType": {
    "id": 1,
    "code": "SJZSKZ",
    "name": "Frozen Marble Chair",
    "kind": "activity"
  }
}

404 Not Found

Ocorre quando o recurso não existe na instância.

Atualizar Recurso ​

Atualiza os dados de uma unidade física. Exige a permissão settings.manage.

http
PUT /v1/tours/user/resources/:id

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais — envie apenas o que deve mudar. Mudanças pontuais de housekeepingState na operação diária são feitas pela governança (ver Governança & Manutenção).

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/resources/5" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-01",
    "label": "Quarto Doc Editado",
    "units": 1,
    "tourResourceTypeId": 1,
    "isActive": true
  }'

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 Recurso ​

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

http
DELETE /v1/tours/user/resources/: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).