Políticas de Cancelamento

As políticas de cancelamento definem o que acontece quando uma reserva é cancelada. Cada política é um conjunto nomeado de regras escalonadas por antecedência: quanto mais perto do início da reserva, maior a penalidade. Uma regra define o limite em horas (hoursBefore) e a penalidade aplicada — percentual do valor, valor fixo ou override total.

A política se vincula ao plano de tarifa (tourCancellationPolicyId): planos reembolsáveis e não reembolsáveis podem apontar para políticas diferentes.

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 settings.manage.

Políticas de Cancelamento

Listar Políticas

Lista as políticas de cancelamento da instância, com paginação e busca.

http

GET /v1/tours/user/cancellation-policies

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page`	`number`	Não	O número da página (mínimo: 1).
`perPage`	`number`	Não	Itens por página (entre 1 e 100).
`search`	`string`	Não	Busca por código ou nome (máx. 150 caracteres).
`orderBy`	`enum`	Não	`id`, `code`, `name` ou `createdAt`.
`orderDirection`	`enum`	Não	`asc` ou `desc`.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/cancellation-policies?search=padrão" \
  -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 políticas no formato meta/data.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "code": "RTMSTTYQ",
      "name": "Elegant Rubber Bacon",
      "description": "Adversus cometes versus subiungo solitudo veniam.",
      "createdAt": "2026-10-07T11:56:14.287-03:00",
      "updatedAt": "2026-10-07T11:56:14.287-03:00"
    }
  ]
}

Criar Política

Cadastra uma nova política de cancelamento (permissão settings.manage).

http

POST /v1/tours/user/cancellation-policies

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`code`	`string`	Sim	Código único na instância (máx. 50 caracteres).
`name`	`string`	Sim	Nome da política (máx. 150 caracteres).
`description`	`string`	Não	Descrição livre da política.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/cancellation-policies" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-CP-01",
    "name": "Política Doc Padrão",
    "description": "Política de cancelamento de documentação"
  }'

Respostas

201 Created

Retorna o ID da política criada.

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 settings.manage (code: FORBIDDEN).

Retorna as políticas em formato simplificado (value/label), ideal para selects — como o vínculo de política a um plano de tarifa.

http

GET /v1/tours/user/cancellation-policies/list

Aceita search 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/cancellation-policies/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 políticas.

json

[
  {
    "value": 1,
    "label": "Elegant Rubber Bacon"
  },
  {
    "value": 4,
    "label": "Política Doc Padrão"
  }
]

Obter Política por ID

Recupera os detalhes de uma política, incluindo suas regras de cancelamento.

http

GET /v1/tours/user/cancellation-policies/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID da política.

Respostas

200 OK

Retorna a política com a relação toursCancellationRules.

json

{
  "id": 4,
  "tourId": 1,
  "code": "DOC-CP-01",
  "name": "Política Doc Padrão",
  "description": "Política de cancelamento de documentação",
  "createdAt": "2026-10-07T15:10:40.130-03:00",
  "updatedAt": "2026-10-07T15:10:40.130-03:00",
  "toursCancellationRules": []
}

404 Not Found

Ocorre quando a política não existe na instância.

Atualizar Política

Atualiza os dados de uma política (permissão settings.manage). Aceita os mesmos campos da criação, todos opcionais.

http

PUT /v1/tours/user/cancellation-policies/:id

Respostas

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o código informado já pertence a outra política da instância.

403 Forbidden

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

Remover Política

Remove uma política via soft delete (permissão settings.manage).

http

DELETE /v1/tours/user/cancellation-policies/:id

Respostas

204 No Content

Remoção concluída com sucesso.

403 Forbidden

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

Regras de Cancelamento

As regras compõem a política e são escalonadas por antecedência: hoursBefore define a partir de quantas horas antes do início da reserva a penalidade se aplica. O penaltyType define como a penalidade é calculada:

Tipo	Efeito
`percent`	Percentual do valor da reserva (ex.: `50` = 50% de multa).
`delta`	Valor fixo de multa.
`override`	Substitui o valor reembolsável/cobrável pelo valor informado.

Listar Regras

Lista as regras de cancelamento da instância, com paginação e filtro por política.

http

GET /v1/tours/user/cancellation-rules

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page`	`number`	Não	O número da página (mínimo: 1).
`perPage`	`number`	Não	Itens por página (entre 1 e 100).
`tourCancellationPolicyId`	`number`	Não	Filtra por política de cancelamento.
`orderBy`	`enum`	Não	`id`, `hoursBefore` ou `createdAt`.
`orderDirection`	`enum`	Não	`asc` ou `desc`.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/cancellation-rules?tourCancellationPolicyId=1&orderBy=hoursBefore&orderDirection=desc" \
  -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.

Criar Regra

Cadastra uma nova regra em uma política (permissão settings.manage).

http

POST /v1/tours/user/cancellation-rules

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`tourCancellationPolicyId`	`number`	Sim	Política à qual a regra pertence.
`hoursBefore`	`number`	Sim	Horas de antecedência a partir das quais a penalidade vale (mínimo: 0).
`penaltyType`	`enum`	Sim	Tipo de penalidade: `percent`, `delta` ou `override`.
`penaltyValue`	`number`	Sim	Valor da penalidade, conforme o tipo.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/cancellation-rules" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourCancellationPolicyId": 1,
    "hoursBefore": 48,
    "penaltyType": "percent",
    "penaltyValue": 50
  }'

Respostas

201 Created

Retorna o ID da regra criada.

json

{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando a política informada não existe na instância ou o payload é inválido.

403 Forbidden

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

Obter Regra por ID

Recupera os detalhes de uma regra de cancelamento.

http

GET /v1/tours/user/cancellation-rules/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID da regra.

Respostas

200 OK

Retorna a regra.

json

{
  "id": 4,
  "tourId": 1,
  "tourCancellationPolicyId": 1,
  "hoursBefore": 48,
  "penaltyType": "percent",
  "penaltyValue": "50.0000",
  "createdAt": "2026-10-07T15:10:41.078-03:00",
  "updatedAt": "2026-10-07T15:10:41.078-03:00"
}

404 Not Found

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

Atualizar Regra

Atualiza uma regra de cancelamento (permissão settings.manage). Aceita os mesmos campos da criação, todos opcionais.

http

PUT /v1/tours/user/cancellation-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 settings.manage (code: FORBIDDEN).

Remover Regra

Remove uma regra via soft delete (permissão settings.manage).

http

DELETE /v1/tours/user/cancellation-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 settings.manage (code: FORBIDDEN).

Políticas de Cancelamento ​

Políticas de Cancelamento ​

Listar Políticas ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Política ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Listar para Dropdown ​

Exemplo de Requisição ​

Respostas ​

Obter Política por ID ​

Parâmetros de Rota ​

Respostas ​

Atualizar Política ​

Respostas ​

Remover Política ​

Respostas ​

Regras de Cancelamento ​

Listar Regras ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Regra ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Regra por ID ​

Parâmetros de Rota ​

Respostas ​

Atualizar Regra ​

Respostas ​

Remover Regra ​

Respostas ​

Políticas de Cancelamento

Políticas de Cancelamento

Listar Políticas

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Política

Payload (Body)

Exemplo de Requisição

Respostas

Listar para Dropdown

Exemplo de Requisição

Respostas

Obter Política por ID

Parâmetros de Rota

Respostas

Atualizar Política

Respostas

Remover Política

Respostas

Regras de Cancelamento

Listar Regras

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Regra

Payload (Body)

Exemplo de Requisição

Respostas

Obter Regra por ID

Parâmetros de Rota

Respostas

Atualizar Regra

Respostas

Remover Regra

Respostas