Basis

Appearance

Governança & Manutenção ​

Esta área cobre a operação que mantém os recursos prontos para vender: as tarefas de governança (housekeeping) organizam a limpeza e a inspeção de quartos, camas e espaços; as ordens de manutenção registram defeitos e reparos, com opção de tirar o recurso de circulação; e os eventos de status do recurso guardam a trilha imutável de cada mudança no estado de limpeza.

Cada conclusão de tarefa ou mudança de estado reflete no housekeepingState do recurso (dirty → cleaning → clean → inspected, ou out_of_service), e cada transição gera um evento auditável — é essa trilha que a recepção consulta antes de liberar um check-in.

Headers obrigatórios

Todas as requisições devem incluir o header X-Tour-Id (UUID) com o tokenHeader da instância e Authorization: Bearer {token} com o token de um usuário staff (guard toursUser). Mutações exigem permissão — housekeeping.update (tarefas) ou maintenance.manage (ordens de manutenção). A API responde 403 com code: FORBIDDEN quando a permissão falta.

Tarefas de Governança ​

A tarefa de housekeeping é a unidade de trabalho da camareira/governança sobre um recurso. O taskType define o escopo: daily (arrumação diária), checkout (limpeza completa pós-saída), deep (limpeza pesada programada), turndown (preparo noturno) ou inspection (vistoria). A priority ordena a fila de trabalho (menor = mais urgente), e o checklist é um array livre de itens verificáveis.

O ciclo de vida: pending → in_progress → done → inspected (ou skipped), com os marcos dueAt, startedAt, completedAt e inspectedAt. A atribuição fica em assignedToTourUserId e a inspeção em inspectedByTourUserId.

Listar Tarefas ​

http
GET /v1/tours/user/housekeeping-tasks

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).
tourResourceIdnumberNãoFiltra por recurso.
assignedToTourUserIdnumberNãoFiltra por responsável.
statusenumNãopending, in_progress, done, inspected ou skipped.
taskTypeenumNãodaily, checkout, deep, turndown ou inspection.
fromstringNãoInício do período (ISO 8601).
tostringNãoFim do período (ISO 8601).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/housekeeping-tasks?status=pending&taskType=checkout" \
  -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 tarefas no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourResourceId": 1,
      "assignedToTourUserId": 1,
      "inspectedByTourUserId": null,
      "taskType": "daily",
      "priority": 100,
      "dueAt": "2026-10-07T15:56:15.659-03:00",
      "startedAt": null,
      "completedAt": null,
      "inspectedAt": null,
      "status": "pending",
      "checklist": [],
      "notes": "Tres arca in summisse vehemens turba.",
      "createdAt": "2026-10-07T11:56:15.659-03:00",
      "updatedAt": "2026-10-07T11:56:15.659-03:00"
    }
  ]
}

Criar Tarefa ​

Cria uma tarefa de governança para um recurso (exige a permissão housekeeping.update).

http
POST /v1/tours/user/housekeeping-tasks

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourResourceIdnumberSimRecurso a ser limpo/inspecionado.
assignedToTourUserIdnumberNãoUsuário staff responsável.
inspectedByTourUserIdnumberNãoUsuário staff que inspecionou.
taskTypeenumNãodaily, checkout, deep, turndown ou inspection.
prioritynumberNãoPrioridade na fila (menor = mais urgente).
dueAtstringNãoPrazo de conclusão (ISO 8601).
startedAtstringNãoInício da execução (ISO 8601).
completedAtstringNãoConclusão (ISO 8601).
inspectedAtstringNãoInspeção (ISO 8601).
statusenumNãopending, in_progress, done, inspected ou skipped.
checklistarrayNãoItens verificáveis — array de objetos (ex.: { "item", "done" }).
notesstringNãoObservações da tarefa.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/housekeeping-tasks" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourResourceId": 1,
    "taskType": "checkout",
    "assignedToTourUserId": 1,
    "priority": 2,
    "dueAt": "2026-10-20T14:00:00.000-03:00",
    "status": "pending",
    "checklist": [
      {
        "item": "Trocar roupa de cama",
        "done": false
      }
    ],
    "notes": "Quarto liberado pelo hóspede às 11h"
  }'

Respostas ​

201 Created

Retorna o ID da tarefa criada.

json
{
  "id": 2
}

422 Unprocessable Entity

Ocorre quando o recurso ou o responsável não existem na instância, ou o payload é inválido.

403 Forbidden

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

Obter Tarefa por ID ​

Recupera os detalhes de uma tarefa, incluindo recurso, responsável e inspetor.

http
GET /v1/tours/user/housekeeping-tasks/:id

Respostas ​

200 OK

Retorna a tarefa com os relacionamentos.

json
{
  "id": 2,
  "tourId": 1,
  "tourResourceId": 1,
  "assignedToTourUserId": 1,
  "inspectedByTourUserId": null,
  "taskType": "checkout",
  "priority": 2,
  "dueAt": "2026-10-20T14:00:00.000-03:00",
  "startedAt": null,
  "completedAt": null,
  "inspectedAt": null,
  "status": "pending",
  "checklist": [
    {
      "done": false,
      "item": "Trocar roupa de cama"
    }
  ],
  "notes": "Quarto liberado pelo hóspede às 11h",
  "createdAt": "2026-10-07T15:10:47.367-03:00",
  "updatedAt": "2026-10-07T15:10:47.367-03:00",
  "inspectedByTourUser": null,
  "assignedToTourUser": {
    "id": 1,
    "displayName": "Bruno Demo"
  },
  "toursResource": {
    "id": 1,
    "code": "PGOXAM"
  }
}

404 Not Found

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

Atualizar Tarefa ​

Atualiza status, checklist, atribuição e marcos de uma tarefa (exige a permissão housekeeping.update). Aceita os mesmos campos da criação, todos opcionais.

http
PUT /v1/tours/user/housekeeping-tasks/:id

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/housekeeping-tasks/2" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "priority": 1,
    "checklist": [
      {
        "item": "Trocar roupa de cama",
        "done": true
      }
    ],
    "notes": "Limpeza iniciada pela camareira"
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

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

Remover Tarefa ​

Remove uma tarefa via soft delete (exige a permissão housekeeping.update).

http
DELETE /v1/tours/user/housekeeping-tasks/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

Ordens de Manutenção ​

A ordem de manutenção registra um defeito ou reparo — no recurso (tourResourceId), na zona (tourResourceZoneId) ou no estabelecimento em geral. A severity (low, normal, high, critical) orienta a triagem, e o status segue open → in_progress → resolved (ou cancelled), com openedAt, resolvedAt e o costAmount do reparo.

Quando blocksAvailability é true, a ordem pode ser vinculada a uma alocação de manutenção (tourAllocationId) que bloqueia a agenda do recurso — uma manutenção jamais colide com uma reserva, porque tudo que ocupa recurso compete pela mesma agenda. Quem reportou é registrado em reportedByTourUserId (injetado com o usuário autenticado).

Listar Ordens ​

http
GET /v1/tours/user/maintenance-orders

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 termo no título (máx. 150 caracteres).
statusenumNãoopen, in_progress, resolved ou cancelled.
severityenumNãolow, normal, high ou critical.
tourResourceIdnumberNãoFiltra por recurso.
assignedToTourUserIdnumberNãoFiltra por responsável.
blocksAvailabilitybooleanNãoFiltra ordens que bloqueiam a disponibilidade.
orderByenumNãoid, openedAt ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/maintenance-orders?status=open&severity=high" \
  -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 ordens no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourResourceId": 1,
      "tourResourceZoneId": 1,
      "tourAllocationId": null,
      "reportedByTourUserId": 1,
      "assignedToTourUserId": null,
      "title": "Volva civis aliqua.",
      "description": "Tego animadverto conforto. Claustrum tibi aspicio aqua vacuus texo.",
      "severity": "normal",
      "status": "open",
      "blocksAvailability": false,
      "openedAt": "2026-10-07T11:56:15.692-03:00",
      "resolvedAt": null,
      "costAmount": null,
      "createdAt": "2026-10-07T11:56:15.692-03:00",
      "updatedAt": "2026-10-07T11:56:15.692-03:00"
    }
  ]
}

Abrir Ordem de Manutenção ​

Abre uma nova ordem (exige a permissão maintenance.manage). O reportedByTourUserId é injetado com o usuário autenticado.

http
POST /v1/tours/user/maintenance-orders

Payload (Body) ​

AtributoTipoObrigatórioDescrição
titlestringSimTítulo da ordem (máx. 200 caracteres).
tourResourceIdnumberNãoRecurso com defeito.
tourResourceZoneIdnumberNãoZona com defeito (alternativa ao recurso).
tourAllocationIdnumberNãoAlocação de manutenção que bloqueia a agenda do recurso.
assignedToTourUserIdnumberNãoUsuário staff responsável pelo reparo.
descriptionstringNãoDescrição do problema.
severityenumNãolow, normal, high ou critical.
statusenumNãoopen, in_progress, resolved ou cancelled.
blocksAvailabilitybooleanNãoIndica que o recurso fica indisponível para reservas.
openedAtstringNãoData/hora de abertura em ISO 8601 (padrão: agora).
resolvedAtstringNãoData/hora de resolução em ISO 8601.
costAmountnumberNãoCusto do reparo.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/maintenance-orders" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Vazamento no chuveiro",
    "tourResourceId": 1,
    "assignedToTourUserId": 1,
    "description": "Chuveiro do banheiro pingando constantemente",
    "severity": "high",
    "status": "open",
    "blocksAvailability": true,
    "openedAt": "2026-10-20T09:30:00.000-03:00"
  }'

Respostas ​

201 Created

Retorna o ID da ordem aberta.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o recurso, a zona ou o responsável não existem na instância, ou o payload é inválido.

403 Forbidden

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

Obter Ordem por ID ​

Recupera os detalhes de uma ordem, incluindo recurso, zona, alocação de bloqueio e responsáveis.

http
GET /v1/tours/user/maintenance-orders/:id

Respostas ​

200 OK

Retorna a ordem com os relacionamentos.

json
{
  "id": 4,
  "tourId": 1,
  "tourResourceId": 1,
  "tourResourceZoneId": null,
  "tourAllocationId": null,
  "reportedByTourUserId": 1,
  "assignedToTourUserId": 1,
  "title": "Vazamento no chuveiro",
  "description": "Chuveiro do banheiro pingando constantemente",
  "severity": "high",
  "status": "open",
  "blocksAvailability": true,
  "openedAt": "2026-10-20T09:30:00.000-03:00",
  "resolvedAt": null,
  "costAmount": null,
  "createdAt": "2026-10-07T15:10:49.759-03:00",
  "updatedAt": "2026-10-07T15:10:49.759-03:00",
  "toursAllocation": null,
  "toursResource": {
    "id": 1,
    "code": "PGOXAM"
  },
  "reportedByTourUser": {
    "id": 1,
    "displayName": "Bruno Demo"
  },
  "assignedToTourUser": {
    "id": 1,
    "displayName": "Bruno Demo"
  },
  "toursResourceZone": null
}

404 Not Found

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

Atualizar Ordem ​

Atualiza severidade, status, responsável e custo de uma ordem (exige a permissão maintenance.manage). Aceita os mesmos campos da abertura, todos opcionais.

http
PUT /v1/tours/user/maintenance-orders/:id

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/maintenance-orders/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Vazamento no chuveiro",
    "severity": "normal",
    "status": "resolved",
    "blocksAvailability": false,
    "resolvedAt": "2026-10-21T11:00:00.000-03:00",
    "costAmount": 150.5
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

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

Remover Ordem ​

Remove uma ordem de manutenção via soft delete (exige a permissão maintenance.manage).

http
DELETE /v1/tours/user/maintenance-orders/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

Eventos de Status do Recurso (somente leitura) ​

Cada mudança no estado de limpeza de um recurso grava um evento imutável: de qual status veio (fromStatus), para qual foi (toStatus), quem mudou e quando — com note opcional. Os status seguem o housekeepingState do recurso: dirty, cleaning, clean, inspected ou out_of_service. É a trilha auditável que responde "quem liberou o quarto 204?".

Listar Eventos ​

http
GET /v1/tours/user/resource-status-events

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).
tourResourceIdnumberSimRecurso dono dos eventos.
fromStatusenumNãodirty, cleaning, clean, inspected ou out_of_service.
toStatusenumNãodirty, cleaning, clean, inspected ou out_of_service.
orderByenumNãoid ou occurredAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/resource-status-events?tourResourceId=1&toStatus=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 eventos no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourResourceId": 1,
      "changedByTourUserId": 1,
      "fromStatus": "dirty",
      "toStatus": "clean",
      "note": "Depromo sollicito sufficio corpus cotidie coniecto tero vester.",
      "occurredAt": "2026-10-07T11:56:15.634-03:00",
      "changedByTourUser": {
        "id": 1,
        "displayName": "Bruno Demo"
      }
    }
  ]
}

422 Unprocessable Entity

Ocorre quando tourResourceId não é informado ou o recurso não existe na instância.

Obter Evento por ID ​

http
GET /v1/tours/user/resource-status-events/:id

Respostas ​

200 OK

Retorna o evento com o usuário que realizou a mudança.

json
{
  "id": 1,
  "tourId": 1,
  "tourResourceId": 1,
  "changedByTourUserId": 1,
  "fromStatus": "dirty",
  "toStatus": "clean",
  "note": "Depromo sollicito sufficio corpus cotidie coniecto tero vester.",
  "occurredAt": "2026-10-07T11:56:15.634-03:00",
  "changedByTourUser": {
    "id": 1,
    "displayName": "Bruno Demo"
  }
}

404 Not Found

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