Basis

Appearance

Reservas & Alocações ​

A reserva é o contrato com o hóspede: nasce como quote (cotação), pode virar held (pré-reserva com prazo) e segue o ciclo confirmed → checked_in → checked_out, com os desfechos cancelled e no_show. Ela carrega o canal de venda (channel: direct, OTA, etc.), o tamanho do grupo (partySize), o período agregado da estadia (stayStartsAt/stayEndsAt) e os totais congelados — a tabela de preços pode mudar amanhã, a conta desta reserva não. O usuário staff que criou a reserva é registrado automaticamente (createdByTourUserId, injetado pelo servidor).

Cada reserva tem itens (reservation-items) — um quarto por noite, um passeio, uma cama balinesa — com período, quantidade, ocupantes (adults/children), preço congelado no momento da venda e priceBreakdown, a memória do cálculo (como o preço foi composto: diárias, regras, impostos). Os itens ocupam recursos físicos através das alocações (allocations), o motor anti double-booking: tudo que ocupa recurso — reserva, manutenção, limpeza, bloqueio do proprietário e hold de checkout — compete pela mesma agenda, e um recurso jamais é vendido duas vezes no mesmo horário.

Toda mudança de status gera um evento (reservation-status-events, somente leitura) — a trilha auditável de quem mudou o quê e quando. Quando não há disponibilidade, o cliente entra na fila de espera (waitlist-entries) com prioridade, flexibilidade de datas e prazo de resposta.

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

Permissões

Mutações de reservas, itens e fila de espera exigem reservation.write; mutações de alocações exigem resource.assign. Sem a permissão, a API responde 403 com code: FORBIDDEN.

Reservas ​

Listar Reservas ​

Lista as reservas do estabelecimento, com paginação, busca e filtros de período.

http
GET /v1/tours/user/reservations

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 da reserva (máx. 150 caracteres).
statusenumNãoquote, held, confirmed, checked_in, checked_out, cancelled ou no_show.
channelstringNãoFiltra por canal de venda (máx. 20 caracteres).
tourCustomerIdnumberNãoFiltra por cliente.
fromdateNãoInício do período (YYYY-MM-DD).
todateNãoFim do período (YYYY-MM-DD).
orderByenumNãoid, code, stayStartsAt ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/reservations?status=confirmed&from=2026-11-01&to=2026-11-30" \
  -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 reservas no formato meta/data, com o cliente resumido.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourCustomerId": 1,
      "tourCancellationPolicyId": 1,
      "code": "YB73C5BU2G",
      "status": "confirmed",
      "channel": "direct",
      "subtotalAmount": "150.00",
      "discountAmount": "0.00",
      "taxAmount": "15.00",
      "totalAmount": "165.00",
      "partySize": 2,
      "stayStartsAt": "2026-10-14T11:56:14.651-03:00",
      "stayEndsAt": "2026-10-16T11:56:14.652-03:00",
      "createdAt": "2026-10-07T11:56:14.652-03:00",
      "updatedAt": "2026-10-07T11:56:14.652-03:00",
      "toursCustomer": {
        "id": 1,
        "fullName": "Mr. Rogelio Cummerata III"
      }
    }
  ]
}

Criar Reserva ​

Cria uma reserva. Exige reservation.write. O usuário autenticado é gravado em createdByTourUserId — não envie esse campo.

http
POST /v1/tours/user/reservations

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo da reserva (máx. 30 caracteres).
statusenumNãoquote, held, confirmed, checked_in, checked_out, cancelled ou no_show.
channelstringNãoCanal de venda (máx. 20 caracteres, ex.: direct).
tourCustomerIdnumberNãoID do cliente (deve existir no estabelecimento).
tourCancellationPolicyIdnumberNãoPolítica de cancelamento aplicada.
subtotalAmountnumberNãoSubtotal congelado (decimal, 2 casas).
discountAmountnumberNãoDesconto congelado.
taxAmountnumberNãoImpostos congelados.
totalAmountnumberNãoTotal congelado.
cancellationFeeAmountnumberNãoMulta de cancelamento.
partySizenumberNãoTamanho do grupo (mínimo: 1).
stayStartsAtdateNãoInício agregado da estadia (ISO 8601).
stayEndsAtdateNãoFim agregado da estadia (ISO 8601).
expectedArrivaldateNãoChegada prevista (ISO 8601).
actualArrivaldateNãoCheck-in efetivo (ISO 8601).
actualDeparturedateNãoCheck-out efetivo (ISO 8601).
cancelledAtdateNãoData/hora do cancelamento (ISO 8601).
cancellationReasonstringNãoMotivo do cancelamento.
guestNotesstringNãoObservações do hóspede.
internalNotesstringNãoObservações internas da equipe.
sourceobjectNãoMetadados de origem (OTA, motor de reservas), propriedades livres.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/reservations" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-RES-01",
    "status": "confirmed",
    "channel": "direct",
    "tourCustomerId": 1,
    "subtotalAmount": 500,
    "discountAmount": 0,
    "taxAmount": 50,
    "totalAmount": 550,
    "partySize": 2,
    "stayStartsAt": "2026-11-01T14:00:00.000-03:00",
    "stayEndsAt": "2026-11-05T12:00:00.000-03:00",
    "guestNotes": "Reserva criada pela documentação"
  }'

Respostas ​

201 Created

Retorna o ID da reserva criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o payload é inválido (status fora do enum, cliente inexistente, datas mal formatadas).

403 Forbidden

Ocorre quando o usuário não possui a permissão reservation.write (code: FORBIDDEN).

Listar para Dropdown ​

Retorna as reservas em formato simplificado (value/label com o código), ideal para selects — como o vínculo de reserva a uma conta (folio).

http
GET /v1/tours/user/reservations/list

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

Respostas ​

200 OK

Retorna um array value/label.

json
[
  {
    "value": 4,
    "label": "DOC-RES-01"
  },
  {
    "value": 1,
    "label": "YB73C5BU2G"
  }
]

Obter Reserva por ID ​

Recupera a reserva completa, com política de cancelamento, cliente, trilha de status e itens.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da reserva.

Respostas ​

200 OK

Retorna a reserva com toursCustomer, toursCancellationPolicy, toursReservationStatusEvents e toursReservationItems.

json
{
  "id": 4,
  "tourId": 1,
  "tourCustomerId": 1,
  "tourCancellationPolicyId": null,
  "createdByTourUserId": 1,
  "code": "DOC-RES-01",
  "status": "confirmed",
  "channel": "direct",
  "subtotalAmount": "500.00",
  "discountAmount": "0.00",
  "taxAmount": "50.00",
  "totalAmount": "550.00",
  "partySize": 2,
  "stayStartsAt": "2026-11-01T14:00:00.000-03:00",
  "stayEndsAt": "2026-11-05T12:00:00.000-03:00",
  "expectedArrival": null,
  "actualArrival": null,
  "actualDeparture": null,
  "cancelledAt": null,
  "cancellationReason": null,
  "cancellationFeeAmount": null,
  "guestNotes": "Reserva criada pela documentação",
  "internalNotes": null,
  "source": {},
  "createdAt": "2026-10-07T15:11:02.844-03:00",
  "updatedAt": "2026-10-07T15:11:02.844-03:00",
  "toursCancellationPolicy": null,
  "toursCustomer": {
    "id": 1,
    "fullName": "Mr. Rogelio Cummerata III",
    "email": "Vada.Corkery93@yahoo.com",
    "phoneE164": null
  },
  "toursReservationStatusEvents": [],
  "toursReservationItems": []
}

404 Not Found

Ocorre quando a reserva não existe no estabelecimento.

Atualizar Reserva ​

Atualiza dados, status e totais da reserva. Exige reservation.write. Toda mudança de status gera um evento na trilha (ver Eventos de Status).

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

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais (exceto code, que não é editável).

Respostas ​

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o payload é inválido.

Remover Reserva ​

Remove uma reserva via soft delete. Exige reservation.write.

http
DELETE /v1/tours/user/reservations/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando a reserva não existe no estabelecimento.

Itens da Reserva ​

Cada item representa uma unidade vendável dentro da reserva: um tipo de recurso (quarto standard, passeio de lancha) por um período, com quantidade, ocupantes e preço congelado. O priceBreakdown guarda a memória do cálculo — como o totalAmount foi composto (diária a diária, regras aplicadas, impostos) — para auditoria futura, mesmo que a tarifa mude. O tourResourceId (a unidade física) pode ficar vazio até a alocação efetiva.

Listar Itens ​

http
GET /v1/tours/user/reservation-items

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).
tourReservationIdnumberNãoFiltra por reserva.
tourResourceTypeIdnumberNãoFiltra por tipo de recurso.
tourResourceIdnumberNãoFiltra por recurso físico.
statusenumNãoquote, held, confirmed, checked_in, checked_out, cancelled ou no_show.
fromdateNãoInício do período (ISO 8601).
todateNãoFim do período (ISO 8601).
orderByenumNãoid, startsAt ou createdAt.
orderDirectionenumNãoasc ou desc.

Respostas ​

200 OK

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

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourReservationId": 1,
      "tourResourceTypeId": 1,
      "tourResourceId": 1,
      "tourRatePlanId": 1,
      "startsAt": "2026-10-14T11:56:14.709-03:00",
      "endsAt": "2026-10-16T11:56:14.709-03:00",
      "quantity": 1,
      "adults": 2,
      "children": 0,
      "unitPriceAmount": "150.00",
      "discountAmount": "0.00",
      "subtotalAmount": "150.00",
      "taxAmount": "15.00",
      "totalAmount": "165.00",
      "priceBreakdown": {},
      "status": "confirmed",
      "notes": null,
      "createdAt": "2026-10-07T11:56:14.709-03:00",
      "updatedAt": "2026-10-07T11:56:14.709-03:00"
    }
  ]
}

Criar Item ​

Exige reservation.write.

http
POST /v1/tours/user/reservation-items

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourReservationIdnumberSimID da reserva (deve existir no estabelecimento).
tourResourceTypeIdnumberSimTipo de recurso vendido (deve existir).
tourResourceIdnumberNãoUnidade física — pode ser definida depois, na alocação.
tourRatePlanIdnumberNãoPlano de tarifa aplicado.
startsAtdateSimInício do período do item (ISO 8601).
endsAtdateSimFim do período do item (ISO 8601).
quantitynumberNãoQuantidade (mínimo: 1).
adultsnumberNãoAdultos (mínimo: 0).
childrennumberNãoCrianças (mínimo: 0).
unitPriceAmountnumberNãoPreço unitário congelado.
discountAmountnumberNãoDesconto congelado.
subtotalAmountnumberNãoSubtotal congelado.
taxAmountnumberNãoImpostos congelados.
totalAmountnumberNãoTotal congelado.
priceBreakdownobject[]NãoMemória do cálculo (linhas livres: diária, regra, imposto).
statusenumNãoMesmo enum de status da reserva.
notesstringNãoObservações do item.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/reservation-items" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourReservationId": 1,
    "tourResourceTypeId": 1,
    "startsAt": "2026-11-01T14:00:00.000-03:00",
    "endsAt": "2026-11-02T12:00:00.000-03:00",
    "quantity": 1,
    "adults": 2,
    "children": 0,
    "unitPriceAmount": 250,
    "subtotalAmount": 250,
    "taxAmount": 25,
    "totalAmount": 275,
    "status": "confirmed"
  }'

Respostas ​

201 Created

Retorna o ID do item criado.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando a reserva ou o tipo de recurso não existe no estabelecimento, ou o payload é inválido.

Obter Item por ID ​

http
GET /v1/tours/user/reservation-items/:id

Respostas ​

200 OK

Retorna o item com tipo de recurso, recurso físico e plano de tarifa relacionados.

json
{
  "id": 4,
  "tourId": 1,
  "tourReservationId": 1,
  "tourResourceTypeId": 1,
  "tourResourceId": null,
  "tourRatePlanId": null,
  "startsAt": "2026-11-01T14:00:00.000-03:00",
  "endsAt": "2026-11-02T12:00:00.000-03:00",
  "quantity": 1,
  "adults": 2,
  "children": 0,
  "unitPriceAmount": "250.00",
  "discountAmount": "0.00",
  "subtotalAmount": "250.00",
  "taxAmount": "25.00",
  "totalAmount": "275.00",
  "priceBreakdown": [],
  "status": "confirmed",
  "notes": null,
  "createdAt": "2026-10-07T15:11:02.031-03:00",
  "updatedAt": "2026-10-07T15:11:02.031-03:00",
  "toursResourceType": {
    "id": 1,
    "code": "SJZSKZ",
    "name": "Frozen Marble Chair"
  },
  "toursRatePlan": null,
  "toursResource": null
}

404 Not Found

Ocorre quando o item não existe no estabelecimento.

Atualizar Item ​

http
PUT /v1/tours/user/reservation-items/:id

Aceita os mesmos campos da criação, todos opcionais. Exige reservation.write. Responde 204 No Content.

Remover Item ​

http
DELETE /v1/tours/user/reservation-items/:id

Remove via soft delete. Exige reservation.write. Responde 204 No Content.

Alocações ​

A alocação é o motor anti double-booking: tudo que ocupa recurso vive aqui e compete pela mesma agenda. Os tipos (kind) são:

KindSignificado
holdReserva temporária de checkout — expira em holdExpiresAt.
reservationOcupação por uma reserva (vinculada a tourReservationItemId).
maintenanceRecurso em manutenção.
housekeepingRecurso em limpeza/governança.
owner_blockBloqueio do proprietário.

isExclusive indica que a alocação toma o recurso inteiro (um quarto); sem ela, a quantity consome capacidade compartilhada (os 20 assentos da lancha). Para liberar o recurso sem apagar o histórico, atualize isActive para false — holds expirados também deixam de competir automaticamente. O usuário autenticado é gravado em createdByTourUserId.

Listar Alocações ​

http
GET /v1/tours/user/allocations

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.
kindenumNãohold, reservation, maintenance, housekeeping ou owner_block.
isActivebooleanNãoFiltra por alocações ativas/inativas.
tourReservationItemIdnumberNãoFiltra por item de reserva.
overlap[from]dateNãoCom overlap[to]: só alocações que colidem com o período (ISO 8601).
overlap[to]dateNãoFim da janela de sobreposição (ISO 8601).
orderByenumNãoid, startsAt, endsAt ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/allocations?tourResourceId=1&isActive=true&overlap%5Bfrom%5D=2026-10-20T00:00:00.000-03:00&overlap%5Bto%5D=2026-10-21T00:00:00.000-03:00" \
  -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 alocações no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourResourceTypeId": 1,
      "tourResourceId": 1,
      "tourReservationItemId": 1,
      "createdByTourUserId": 1,
      "kind": "reservation",
      "quantity": 1,
      "startsAt": "2026-10-14T11:56:14.780-03:00",
      "endsAt": "2026-10-16T11:56:14.780-03:00",
      "isExclusive": true,
      "isActive": true,
      "holdExpiresAt": null,
      "note": null,
      "createdAt": "2026-10-07T11:56:14.780-03:00",
      "updatedAt": "2026-10-07T11:56:14.780-03:00"
    }
  ]
}

Criar Alocação ​

Exige resource.assign.

http
POST /v1/tours/user/allocations

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourResourceTypeIdnumberSimTipo de recurso (deve existir no estabelecimento).
tourResourceIdnumberNãoUnidade física alocada.
tourReservationItemIdnumberNãoItem de reserva vinculado (quando kind = reservation).
kindenumSimhold, reservation, maintenance, housekeeping ou owner_block.
quantitynumberNãoQuantidade de capacidade consumida (mínimo: 1).
startsAtdateSimInício da ocupação (ISO 8601).
endsAtdateSimFim da ocupação (ISO 8601).
isExclusivebooleanNãoToma o recurso inteiro (padrão: exclusivo por recurso).
isActivebooleanNãoIndica se compete pela agenda (padrão: true).
holdExpiresAtdateNãoExpiração do hold (ISO 8601) — após ela, o recurso é liberado.
notestringNãoObservação.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/allocations" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourResourceTypeId": 1,
    "tourResourceId": 1,
    "kind": "reservation",
    "quantity": 1,
    "startsAt": "2026-10-20T14:00:00.000-03:00",
    "endsAt": "2026-10-20T18:00:00.000-03:00",
    "isActive": true,
    "note": "Alocação Doc"
  }'

Respostas ​

201 Created

Retorna o ID da alocação criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o tipo/recurso não existe no estabelecimento ou o payload é inválido.

403 Forbidden

Ocorre quando o usuário não possui a permissão resource.assign (code: FORBIDDEN).

Obter Alocação por ID ​

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

Respostas ​

200 OK

Retorna a alocação com recurso e tipo de recurso relacionados.

json
{
  "id": 4,
  "tourId": 1,
  "tourResourceTypeId": 1,
  "tourResourceId": 1,
  "tourReservationItemId": null,
  "createdByTourUserId": 1,
  "kind": "reservation",
  "quantity": 1,
  "startsAt": "2026-10-20T14:00:00.000-03:00",
  "endsAt": "2026-10-20T18:00:00.000-03:00",
  "isExclusive": true,
  "isActive": true,
  "holdExpiresAt": null,
  "note": "Alocação Doc",
  "createdAt": "2026-10-07T15:10:35.400-03:00",
  "updatedAt": "2026-10-07T15:10:35.400-03:00",
  "toursResource": {
    "id": 1,
    "code": "PGOXAM"
  },
  "toursResourceType": {
    "id": 1,
    "code": "SJZSKZ",
    "name": "Frozen Marble Chair"
  }
}

404 Not Found

Ocorre quando a alocação não existe no estabelecimento.

Atualizar Alocação ​

Atualiza período, recurso ou libera a alocação (isActive: false). Exige resource.assign.

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

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais.

Respostas ​

204 No Content

Atualização concluída com sucesso.

Remover Alocação ​

Remove uma alocação via soft delete. Exige resource.assign. Para liberar o recurso mantendo o histórico, prefira PUT com isActive: false.

http
DELETE /v1/tours/user/allocations/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

Eventos de Status da Reserva ​

A trilha auditável de mudanças de status — quem mudou, de qual status para qual, quando e por quê. Recurso somente leitura: os eventos são gravados automaticamente pelo motor de reservas; não existem endpoints de criação, edição ou remoção.

Listar Eventos ​

http
GET /v1/tours/user/reservation-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).
tourReservationIdnumberSimID da reserva (deve existir).
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/reservation-status-events?tourReservationId=1" \
  -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, com o usuário que fez a mudança.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourReservationId": 1,
      "changedByTourUserId": 1,
      "fromStatus": "quote",
      "toStatus": "confirmed",
      "reason": "Inventore vacuus crux bos coerceo tempore cunae id.",
      "occurredAt": "2026-10-07T11:56:14.815-03:00",
      "changedByTourUser": {
        "id": 1,
        "displayName": "Bruno Demo"
      }
    }
  ]
}

Obter Evento por ID ​

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

Respostas ​

200 OK

Retorna o evento.

json
{
  "id": 1,
  "tourId": 1,
  "tourReservationId": 1,
  "changedByTourUserId": 1,
  "fromStatus": "quote",
  "toStatus": "confirmed",
  "reason": "Inventore vacuus crux bos coerceo tempore cunae id.",
  "occurredAt": "2026-10-07T11:56:14.815-03:00"
}

404 Not Found

Ocorre quando o evento não existe no estabelecimento.

Fila de Espera ​

Quando não há disponibilidade, o interessado entra na fila (waiting) com o período desejado, prioridade (maior primeiro) e flexibilidade de datas (isFlexible). Ao surgir vaga, a entrada é notificada (notified, com notifiedAt) e ganha um prazo de resposta (responseDeadline): sem resposta, expira (expired); com aceite, é convertida em reserva (converted, vinculada a tourReservationId). A entrada também pode ser cancelada (cancelled).

Listar Entradas da Fila ​

http
GET /v1/tours/user/waitlist-entries

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).
statusenumNãowaiting, notified, converted, expired ou cancelled.
tourResourceTypeIdnumberNãoFiltra por tipo de recurso.
tourCustomerIdnumberNãoFiltra por cliente.
priorityMinnumberNãoPrioridade mínima.
orderByenumNãoid, priority, desiredStartsAt ou createdAt.
orderDirectionenumNãoasc ou desc.

Respostas ​

200 OK

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

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourResourceTypeId": 1,
      "tourCustomerId": 1,
      "tourReservationId": null,
      "contactName": "Mrs. Catharine Lynch-Veum",
      "contactPhone": "482.468.0399",
      "contactEmail": null,
      "desiredStartsAt": "2026-10-14T11:56:14.843-03:00",
      "desiredEndsAt": "2026-10-16T11:56:14.843-03:00",
      "isFlexible": false,
      "partySize": 2,
      "quantity": 1,
      "priority": 100,
      "status": "waiting",
      "notifiedAt": null,
      "responseDeadline": null,
      "expiresAt": null,
      "createdAt": "2026-10-07T11:56:14.844-03:00",
      "updatedAt": "2026-10-07T11:56:14.844-03:00"
    }
  ]
}

Criar Entrada na Fila ​

Exige reservation.write. O cliente (tourCustomerId) é opcional — para quem ainda não é cadastrado, use os campos de contato (contactName/contactPhone/contactEmail).

http
POST /v1/tours/user/waitlist-entries

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourResourceTypeIdnumberSimTipo de recurso desejado (deve existir).
tourCustomerIdnumberNãoID do cliente cadastrado.
contactNamestringNãoNome do contato (máx. 150 caracteres).
contactPhonestringNãoTelefone do contato (máx. 30 caracteres).
contactEmailstringNãoE-mail do contato (máx. 250 caracteres).
desiredStartsAtdateSimInício desejado (ISO 8601).
desiredEndsAtdateSimFim desejado (ISO 8601).
isFlexiblebooleanNãoAceita datas próximas às desejadas.
partySizenumberNãoTamanho do grupo (mínimo: 1).
quantitynumberNãoQuantidade (mínimo: 1).
prioritynumberNãoPrioridade na fila (maior primeiro).
statusenumNãowaiting, notified, converted, expired ou cancelled.
notifiedAtdateNãoData/hora da notificação (ISO 8601).
responseDeadlinedateNãoPrazo de resposta após a notificação (ISO 8601).
expiresAtdateNãoExpiração da entrada (ISO 8601).
tourReservationIdnumberNãoReserva criada na conversão.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/waitlist-entries" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourResourceTypeId": 1,
    "tourCustomerId": 1,
    "desiredStartsAt": "2026-10-20T19:00:00.000-03:00",
    "desiredEndsAt": "2026-10-20T22:00:00.000-03:00",
    "isFlexible": true,
    "partySize": 2,
    "quantity": 1,
    "priority": 10,
    "status": "waiting"
  }'

Respostas ​

201 Created

Retorna o ID da entrada criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o tipo de recurso ou cliente não existe no estabelecimento, ou o payload é inválido.

Obter Entrada por ID ​

http
GET /v1/tours/user/waitlist-entries/:id

Respostas ​

200 OK

Retorna a entrada com cliente e tipo de recurso relacionados.

json
{
  "id": 4,
  "tourId": 1,
  "tourResourceTypeId": 1,
  "tourCustomerId": 1,
  "tourReservationId": null,
  "contactName": null,
  "contactPhone": null,
  "contactEmail": null,
  "desiredStartsAt": "2026-10-20T19:00:00.000-03:00",
  "desiredEndsAt": "2026-10-20T22:00:00.000-03:00",
  "isFlexible": true,
  "partySize": 2,
  "quantity": 1,
  "priority": 10,
  "status": "waiting",
  "notifiedAt": null,
  "responseDeadline": null,
  "expiresAt": null,
  "createdAt": "2026-10-07T15:11:20.588-03:00",
  "updatedAt": "2026-10-07T15:11:20.588-03:00",
  "toursCustomer": {
    "id": 1,
    "fullName": "Mr. Rogelio Cummerata III",
    "phoneE164": null
  },
  "toursResourceType": {
    "id": 1,
    "code": "SJZSKZ",
    "name": "Frozen Marble Chair"
  }
}

404 Not Found

Ocorre quando a entrada não existe no estabelecimento.

Atualizar Entrada ​

Atualiza dados, prioridade ou status da entrada (ex.: marcar como notified com responseDeadline, ou converted com tourReservationId). Exige reservation.write.

http
PUT /v1/tours/user/waitlist-entries/:id

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais.

Respostas ​

204 No Content

Atualização concluída com sucesso.

Remover Entrada ​

Remove uma entrada da fila via soft delete. Exige reservation.write.

http
DELETE /v1/tours/user/waitlist-entries/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando a entrada não existe no estabelecimento.