Basis

Appearance

Tarifas & Precificação ​

O motor de precificação trabalha em três camadas, da mais geral para a mais específica:

  1. Plano de tarifa (rate plan): o preço base de venda — define como se cobra (por unidade, por pessoa, por intervalo), o preço base, o adicional por pessoa extra, a janela de validade e a política de cancelamento associada.
  2. Regras de preço (price rules): ajustes dinâmicos aplicados sobre o plano quando as condições batem — sazonalidade, dia da semana, horário de pico, antecedência da reserva (lead time), ocupação e tamanho do grupo.
  3. Calendário de tarifas (rate calendar entries): overrides manuais por data — preço fechado para um feriado, mínimo de noites no réveillon ou bloqueio de chegada/saída.

O plano se vincula aos tipos de recurso (N:N): um mesmo plano "Diária Standard" pode tarifar vários tipos de quarto. Como sempre no módulo, o preço combinado é congelado no momento da venda — mudar a tabela depois não altera reservas já vendidas.

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). Mutações exigem a permissão rate.write.

Planos de Tarifa (Rate Plans) ​

Listar Planos de Tarifa ​

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

http
GET /v1/tours/user/rate-plans

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).
pricingUnitenumNãoFiltra por unidade de cobrança: per_unit, per_unit_per_interval, per_person ou per_person_per_interval.
isRefundablebooleanNãoFiltra por planos reembolsáveis/não reembolsáveis.
isActivebooleanNãoFiltra por planos ativos/inativos.
orderByenumNãoid, code, name, priority, basePrice ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/rate-plans?pricingUnit=per_unit&isActive=true" \
  -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 planos no formato meta/data.

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

Criar Plano de Tarifa ​

Cadastra um novo plano de tarifa (permissão rate.write).

http
POST /v1/tours/user/rate-plans

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo único na instância (máx. 50 caracteres).
namestringSimNome do plano (máx. 150 caracteres).
pricingUnitenumSimUnidade de cobrança: per_unit (por unidade), per_unit_per_interval (por unidade por intervalo), per_person (por pessoa) ou per_person_per_interval (por pessoa por intervalo).
basePricenumberSimPreço base na moeda da instância (mínimo: 0).
extraPersonPricenumberNãoAdicional por pessoa extra (mínimo: 0).
minUnitsnumberNãoQuantidade mínima de unidades (ex.: noites mínimas).
maxUnitsnumberNãoQuantidade máxima de unidades.
isRefundablebooleanNãoIndica se o plano é reembolsável.
tourCancellationPolicyIdnumberNãoPolítica de cancelamento associada (ver Políticas de Cancelamento).
validFromdateNãoInício da vigência (YYYY-MM-DD).
validUntildateNãoFim da vigência (YYYY-MM-DD).
prioritynumberNãoPrioridade do plano na precificação (menor = mais prioritário).
isActivebooleanNãoIndica se já nasce ativo.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/rate-plans" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-RP-01",
    "name": "Plano Doc",
    "pricingUnit": "per_unit",
    "basePrice": 250,
    "isRefundable": true,
    "tourCancellationPolicyId": 1,
    "validFrom": "2026-10-07",
    "validUntil": "2027-10-07",
    "priority": 1,
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID do plano criado.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o código já existe na instância ou o payload é inválido.

json
{
  "errors": [
    {
      "message": "The code has already been taken",
      "rule": "database.unique",
      "field": "code"
    }
  ]
}

403 Forbidden

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

Listar para Dropdown ​

Retorna os planos em formato simplificado (value/label), ideal para selects — como o vínculo de plano a uma regra de preço.

http
GET /v1/tours/user/rate-plans/list

Aceita search, isActive e limit (entre 1 e 500) como filtros opcionais de query.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/rate-plans/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 os planos.

json
[
  {
    "value": 1,
    "label": "Electronic Bronze Salad"
  },
  {
    "value": 4,
    "label": "Plano Doc"
  }
]

Obter Plano de Tarifa por ID ​

Recupera os detalhes de um plano, incluindo a política de cancelamento e os tipos de recurso vinculados.

http
GET /v1/tours/user/rate-plans/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID do plano de tarifa.

Respostas ​

200 OK

Retorna o plano com as relações toursCancellationPolicy e toursResourceTypes.

json
{
  "id": 4,
  "tourId": 1,
  "tourCancellationPolicyId": 1,
  "code": "DOC-RP-01",
  "name": "Plano Doc",
  "pricingUnit": "per_unit",
  "basePrice": "250.00",
  "extraPersonPrice": "0.00",
  "minUnits": null,
  "maxUnits": null,
  "isRefundable": true,
  "validFrom": "2026-10-07",
  "validUntil": "2027-10-07",
  "priority": 1,
  "isActive": true,
  "createdAt": "2026-10-07T15:11:00.185-03:00",
  "updatedAt": "2026-10-07T15:11:00.185-03:00",
  "toursCancellationPolicy": {
    "id": 1,
    "code": "RTMSTTYQ",
    "name": "Elegant Rubber Bacon"
  },
  "toursResourceTypes": []
}

404 Not Found

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

Atualizar Plano de Tarifa ​

Atualiza os dados de um plano (permissão rate.write). Aceita os mesmos campos da criação, todos opcionais — envie apenas o que deseja alterar.

http
PUT /v1/tours/user/rate-plans/:id

Respostas ​

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o código informado já pertence a outro plano da instância.

403 Forbidden

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

Sincronizar Tipos de Recurso ​

Substitui o conjunto de tipos de recurso vinculados ao plano — sincronização N:N completa (permissão rate.write). Os tipos enviados passam a ser os únicos tarifados por este plano.

http
PUT /v1/tours/user/rate-plans/:id/resource-types

Payload (Body) ​

AtributoTipoObrigatórioDescrição
resourceTypeIdsnumber[]SimIDs dos tipos de recurso da instância a vincular (ver Recursos Reserváveis).

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/rate-plans/4/resource-types" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceTypeIds": [1]
  }'

Respostas ​

204 No Content

Vínculos sincronizados com sucesso.

422 Unprocessable Entity

Ocorre quando algum tipo de recurso informado não existe na instância.

Remover Plano de Tarifa ​

Remove um plano via soft delete (permissão rate.write).

http
DELETE /v1/tours/user/rate-plans/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

403 Forbidden

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

Regras de Preço (Price Rules) ​

Ajustes dinâmicos aplicados sobre o preço base de um plano quando as condições configuradas batem no momento da cotação. O adjustmentType define como o ajuste é aplicado:

TipoEfeito
percentPercentual sobre o preço (ex.: 15 = +15% no fim de semana).
deltaValor fixo somado (ou subtraído, se negativo) ao preço.
overrideSubstitui o preço calculado pelo valor informado.

As condições são opcionais e combináveis: período (dateFrom/dateUntil), dias da semana (weekdays), janela de horário (timeFrom/timeTo), antecedência da reserva em minutos (minLeadTimeMinutes/maxLeadTimeMinutes), ocupação (occupancyMin/occupancyMax), quantidade de unidades (unitsMin/unitsMax) e tamanho do grupo (partySizeMin/partySizeMax). Regra sem condições vale sempre.

Listar Regras de Preço ​

Lista as regras de preço da instância, com paginação, busca e filtros.

http
GET /v1/tours/user/price-rules

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 nome (máx. 150 caracteres).
tourRatePlanIdnumberNãoFiltra por plano de tarifa.
adjustmentTypeenumNãoFiltra por tipo de ajuste: percent, delta ou override.
isActivebooleanNãoFiltra por regras ativas/inativas.
orderByenumNãoid, name, priority ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/price-rules?tourRatePlanId=1&isActive=true" \
  -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 regras no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourRatePlanId": 1,
      "name": "Oriental Concrete Sausages",
      "priority": 0,
      "adjustmentType": "percent",
      "adjustmentValue": "10.0000",
      "dateFrom": null,
      "dateUntil": null,
      "timeFrom": null,
      "timeTo": null,
      "minLeadTimeMinutes": null,
      "maxLeadTimeMinutes": null,
      "occupancyMin": null,
      "occupancyMax": null,
      "unitsMin": null,
      "unitsMax": null,
      "partySizeMin": null,
      "partySizeMax": null,
      "isActive": true,
      "createdAt": "2026-10-07T11:56:14.413-03:00",
      "updatedAt": "2026-10-07T11:56:14.414-03:00"
    }
  ]
}

Criar Regra de Preço ​

Cadastra uma nova regra de ajuste sobre um plano (permissão rate.write). Quando weekdays é informado, os dias são sincronizados na criação.

http
POST /v1/tours/user/price-rules

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourRatePlanIdnumberSimPlano de tarifa ao qual a regra se aplica.
namestringSimNome da regra (máx. 150 caracteres).
adjustmentTypeenumSimTipo de ajuste: percent, delta ou override.
adjustmentValuenumberSimValor do ajuste (percentual, valor fixo ou preço final, conforme o tipo).
prioritynumberNãoPrioridade da regra quando mais de uma se aplica.
dateFromdateNãoInício do período de vigência (YYYY-MM-DD) — sazonalidade.
dateUntildateNãoFim do período de vigência (YYYY-MM-DD).
timeFromstringNãoInício da janela de horário (HH:mm) — horário de pico.
timeTostringNãoFim da janela de horário (HH:mm).
minLeadTimeMinutesnumberNãoAntecedência mínima da reserva, em minutos (mínimo: 0).
maxLeadTimeMinutesnumberNãoAntecedência máxima da reserva, em minutos.
occupancyMinnumberNãoOcupação mínima para a regra valer (mínimo: 0).
occupancyMaxnumberNãoOcupação máxima para a regra valer.
unitsMinnumberNãoQuantidade mínima de unidades (mínimo: 0).
unitsMaxnumberNãoQuantidade máxima de unidades.
partySizeMinnumberNãoTamanho mínimo do grupo (mínimo: 0).
partySizeMaxnumberNãoTamanho máximo do grupo.
isActivebooleanNãoIndica se já nasce ativa.
weekdaysnumber[]NãoDias da semana em que a regra vale (0 = domingo … 6 = sábado).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/price-rules" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourRatePlanId": 1,
    "name": "Regra Doc Fim de Semana",
    "adjustmentType": "percent",
    "adjustmentValue": 15,
    "priority": 10,
    "dateFrom": "2026-12-01",
    "dateUntil": "2026-12-31",
    "weekdays": [0, 6],
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID da regra criada.

json
{
  "id": 4
}

422 Unprocessable Entity

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

403 Forbidden

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

Obter Regra de Preço por ID ​

Recupera os detalhes de uma regra, incluindo os dias da semana configurados.

http
GET /v1/tours/user/price-rules/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da regra de preço.

Respostas ​

200 OK

Retorna a regra com a relação toursPriceRuleWeekdays.

json
{
  "id": 4,
  "tourId": 1,
  "tourRatePlanId": 1,
  "name": "Regra Doc Fim de Semana",
  "priority": 10,
  "adjustmentType": "percent",
  "adjustmentValue": "15.0000",
  "dateFrom": "2026-12-01",
  "dateUntil": "2026-12-31",
  "timeFrom": null,
  "timeTo": null,
  "minLeadTimeMinutes": null,
  "maxLeadTimeMinutes": null,
  "occupancyMin": null,
  "occupancyMax": null,
  "unitsMin": null,
  "unitsMax": null,
  "partySizeMin": null,
  "partySizeMax": null,
  "isActive": true,
  "createdAt": "2026-10-07T15:10:56.959-03:00",
  "updatedAt": "2026-10-07T15:10:56.959-03:00",
  "toursPriceRuleWeekdays": [
    {
      "id": 9,
      "tourPriceRuleId": 4,
      "dayOfWeek": 0
    },
    {
      "id": 10,
      "tourPriceRuleId": 4,
      "dayOfWeek": 6
    }
  ]
}

404 Not Found

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

Atualizar Regra de Preço ​

Atualiza uma regra (permissão rate.write). Aceita os mesmos campos da criação, todos opcionais. Quando weekdays é enviado, os dias da semana são ressincronizados (substituição completa).

http
PUT /v1/tours/user/price-rules/:id

Respostas ​

204 No Content

Atualização concluída com sucesso.

403 Forbidden

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

Remover Regra de Preço ​

Remove uma regra via soft delete (permissão rate.write).

http
DELETE /v1/tours/user/price-rules/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

403 Forbidden

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

Calendário de Tarifas (Rate Calendar Entries) ​

Overrides manuais por data sobre um plano de tarifa — a camada mais específica da precificação. Use para fixar o preço de um feriado (priceOverride), exigir mínimo de noites em datas concorridas (minUnits) ou fechar a data para chegadas (closedToArrival), saídas (closedToDeparture) ou completamente (isClosed).

Listar Entradas do Calendário ​

Lista as entradas do calendário de tarifas, com paginação e filtros por período.

http
GET /v1/tours/user/rate-calendar-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).
tourRatePlanIdnumberNãoFiltra por plano de tarifa.
fromstringNãoInício do período (YYYY-MM-DD).
tostringNãoFim do período (YYYY-MM-DD).
isClosedbooleanNãoFiltra datas totalmente fechadas.
closedToArrivalbooleanNãoFiltra datas fechadas para chegada.
closedToDeparturebooleanNãoFiltra datas fechadas para saída.
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/rate-calendar-entries?tourRatePlanId=1&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 entradas no formato meta/data.

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

Criar Entrada no Calendário ​

Registra um override manual para uma data (permissão rate.write).

http
POST /v1/tours/user/rate-calendar-entries

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourRatePlanIdnumberSimPlano de tarifa ao qual a entrada se aplica.
onDatedateSimA data do override (YYYY-MM-DD).
priceOverridenumberNãoPreço fixo para a data, substituindo o cálculo normal (mínimo: 0).
minUnitsnumberNãoQuantidade mínima de unidades na data (ex.: noites mínimas).
isClosedbooleanNãoFecha a data completamente.
closedToArrivalbooleanNãoImpede chegadas (check-in) na data.
closedToDeparturebooleanNãoImpede saídas (check-out) na data.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/rate-calendar-entries" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourRatePlanId": 1,
    "onDate": "2026-12-31",
    "priceOverride": 500,
    "minUnits": 2,
    "isClosed": false,
    "closedToArrival": false,
    "closedToDeparture": false
  }'

Respostas ​

201 Created

Retorna o ID da entrada criada.

json
{
  "id": 4
}

422 Unprocessable Entity

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

403 Forbidden

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

Obter Entrada por ID ​

Recupera os detalhes de uma entrada do calendário.

http
GET /v1/tours/user/rate-calendar-entries/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da entrada do calendário.

Respostas ​

200 OK

Retorna a entrada.

json
{
  "id": 4,
  "tourId": 1,
  "tourRatePlanId": 1,
  "onDate": "2026-12-31",
  "priceOverride": "500.00",
  "minUnits": 2,
  "isClosed": false,
  "closedToArrival": false,
  "closedToDeparture": false,
  "createdAt": "2026-10-07T15:10:59.514-03:00",
  "updatedAt": "2026-10-07T15:10:59.514-03:00"
}

404 Not Found

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

Atualizar Entrada do Calendário ​

Atualiza um override manual (permissão rate.write). Aceita os mesmos campos da criação, todos opcionais. Envie priceOverride: null para remover o override de preço mantendo a entrada.

http
PUT /v1/tours/user/rate-calendar-entries/:id

Respostas ​

204 No Content

Atualização concluída com sucesso.

403 Forbidden

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

Remover Entrada do Calendário ​

Remove uma entrada via soft delete (permissão rate.write) — a data volta a seguir o cálculo normal do plano.

http
DELETE /v1/tours/user/rate-calendar-entries/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

403 Forbidden

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