Basis

Appearance

Impostos & Taxas ​

O módulo trata tributos como configuração paramétrica do estabelecimento — nenhum imposto é hardcoded. Quatro recursos compõem a camada fiscal:

  • Impostos (taxes): o tributo em si — percentual ou valor fixo por unidade, com jurisdição, vigência, prioridade e flags de inclusão no preço e composição (imposto sobre imposto).
  • Grupos de impostos (tax groups): conjuntos nomeados de impostos (N:N), para aplicar vários tributos de uma vez a produtos e tarifas.
  • Regras de isenção (tax exemption rules): condições livres que zeram ou reduzem a alíquota de um imposto — como isenção para longa estadia.
  • Taxas de serviço (service charge rules): couvert, gorjeta sugerida ou taxa de serviço — percentual ou valor fixo, obrigatória ou opcional, tributável ou não.

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.

Impostos (Taxes) ​

Listar Impostos ​

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

http
GET /v1/tours/user/taxes

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).
jurisdictionstringNãoFiltra por jurisdição (máx. 100 caracteres).
computationenumNãoFiltra por cálculo: percent ou fixed_per_unit.
isActivebooleanNãoFiltra por impostos ativos/inativos.
orderByenumNãoid, code, 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/taxes?computation=percent&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 impostos no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "code": "WMC2M1",
      "name": "Elegant Cotton Salad",
      "jurisdiction": null,
      "computation": "percent",
      "rate": "10.000000",
      "fixedAmount": null,
      "isInclusive": false,
      "isCompound": false,
      "priority": 100,
      "validFrom": null,
      "validUntil": null,
      "isActive": true,
      "createdAt": "2026-10-07T11:56:13.928-03:00",
      "updatedAt": "2026-10-07T11:56:13.928-03:00"
    }
  ]
}

Criar Imposto ​

Cadastra um novo imposto (permissão settings.manage).

http
POST /v1/tours/user/taxes

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo único na instância (máx. 50 caracteres).
namestringSimNome do imposto (máx. 150 caracteres).
computationenumSimCálculo: percent (percentual sobre o valor) ou fixed_per_unit (valor fixo por unidade).
jurisdictionstringNãoJurisdição fiscal (ex.: BR-SP, máx. 100 caracteres).
ratenumberNãoAlíquota percentual, quando computation é percent.
fixedAmountnumberNãoValor fixo por unidade, quando computation é fixed_per_unit.
isInclusivebooleanNãoIndica se o imposto já está embutido no preço.
isCompoundbooleanNãoIndica se incide sobre a base já tributada (imposto sobre imposto).
prioritynumberNãoOrdem de aplicação entre impostos.
validFromdateNãoInício da vigência (YYYY-MM-DD).
validUntildateNãoFim da vigência (YYYY-MM-DD).
isActivebooleanNãoIndica se já nasce ativo.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/taxes" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-TAX-01",
    "name": "Imposto Doc",
    "computation": "percent",
    "rate": 10,
    "jurisdiction": "BR-SP",
    "isInclusive": false,
    "isCompound": false,
    "priority": 1,
    "validFrom": "2026-01-01",
    "validUntil": "2026-12-31",
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID do imposto 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 settings.manage (code: FORBIDDEN).

Listar para Dropdown ​

Retorna os impostos em formato simplificado (value/label), ideal para selects — como a montagem de um grupo de impostos.

http
GET /v1/tours/user/taxes/list

Aceita search e isActive como filtros opcionais de query.

Exemplo de Requisição ​

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

json
[
  {
    "value": 1,
    "label": "Elegant Cotton Salad"
  },
  {
    "value": 4,
    "label": "Imposto Doc"
  }
]

Obter Imposto por ID ​

Recupera os detalhes de um imposto.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID do imposto.

Respostas ​

200 OK

Retorna o imposto.

json
{
  "id": 4,
  "tourId": 1,
  "code": "DOC-TAX-01",
  "name": "Imposto Doc",
  "jurisdiction": "BR-SP",
  "computation": "percent",
  "rate": "10.000000",
  "fixedAmount": null,
  "isInclusive": false,
  "isCompound": false,
  "priority": 1,
  "validFrom": "2026-01-01",
  "validUntil": "2026-12-31",
  "isActive": true,
  "createdAt": "2026-10-07T15:11:17.807-03:00",
  "updatedAt": "2026-10-07T15:11:17.807-03:00"
}

404 Not Found

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

Atualizar Imposto ​

Atualiza os dados de um imposto (permissão settings.manage). Aceita os mesmos campos da criação, todos opcionais.

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

Respostas ​

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

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

403 Forbidden

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

Remover Imposto ​

Remove um imposto via soft delete (permissão settings.manage).

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

Grupos de Impostos (Tax Groups) ​

Conjuntos nomeados de impostos. O vínculo é N:N e feito por sincronização completa: o array enviado passa a ser exatamente o conjunto de impostos do grupo.

Listar Grupos ​

Lista os grupos de impostos da instância, com paginação e busca.

http
GET /v1/tours/user/tax-groups

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).
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/tax-groups?search=hospedagem" \
  -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 grupos no formato meta/data.

Criar Grupo ​

Cadastra um novo grupo de impostos (permissão settings.manage).

http
POST /v1/tours/user/tax-groups

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo único na instância (máx. 50 caracteres).
namestringSimNome do grupo (máx. 150 caracteres).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/tax-groups" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-TG-01",
    "name": "Grupo de Impostos Doc"
  }'

Respostas ​

201 Created

Retorna o ID do grupo criado.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o código já 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).

Listar para Dropdown ​

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

http
GET /v1/tours/user/tax-groups/list

Aceita search como filtro opcional de query.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/tax-groups/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 grupos.

json
[
  {
    "value": 1,
    "label": "Electronics"
  },
  {
    "value": 4,
    "label": "Grupo de Impostos Doc"
  }
]

Obter Grupo por ID ​

Recupera os detalhes de um grupo de impostos.

http
GET /v1/tours/user/tax-groups/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID do grupo.

Respostas ​

200 OK

Retorna o grupo.

json
{
  "id": 4,
  "tourId": 1,
  "code": "DOC-TG-01",
  "name": "Grupo de Impostos Doc",
  "createdAt": "2026-10-07T15:11:16.911-03:00",
  "updatedAt": "2026-10-07T15:11:16.911-03:00"
}

404 Not Found

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

Atualizar Grupo ​

Atualiza os dados de um grupo (permissão settings.manage). Aceita os mesmos campos da criação, todos opcionais.

http
PUT /v1/tours/user/tax-groups/: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).

Sincronizar Impostos do Grupo ​

Substitui o conjunto de impostos do grupo — sincronização N:N completa (permissão settings.manage).

http
PUT /v1/tours/user/tax-groups/:id/taxes

Payload (Body) ​

AtributoTipoObrigatórioDescrição
taxIdsnumber[]SimIDs dos impostos da instância a vincular ao grupo.

Exemplo de Requisição ​

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

Respostas ​

204 No Content

Vínculos sincronizados com sucesso.

422 Unprocessable Entity

Ocorre quando algum imposto informado não existe na instância.

Remover Grupo ​

Remove um grupo via soft delete (permissão settings.manage).

http
DELETE /v1/tours/user/tax-groups/: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 Isenção (Tax Exemption Rules) ​

Regras que zeram ou reduzem a alíquota de um imposto quando as condições batem. O campo conditions é um objeto livre — as chaves dependem do contexto da venda (ex.: min_nights para isenção de longa estadia). overrideRate define a alíquota substituta: 0 significa isenção total.

Listar Regras de Isenção ​

Lista as regras de isenção da instância, com paginação e filtro por imposto.

http
GET /v1/tours/user/tax-exemption-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).
tourTaxIdnumberNãoFiltra por imposto.
isActivebooleanNãoFiltra por regras ativas/inativas.
orderByenumNãoid, name ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/tax-exemption-rules?tourTaxId=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.

Criar Regra de Isenção ​

Cadastra uma nova regra de isenção para um imposto (permissão settings.manage).

http
POST /v1/tours/user/tax-exemption-rules

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourTaxIdnumberSimImposto ao qual a regra se aplica.
namestringSimNome da regra (máx. 150 caracteres).
conditionsobjectSimCondições de aplicação (objeto livre, ex.: { "min_nights": 30 }).
overrideRatenumberNãoAlíquota substituta quando as condições batem (0 = isenção total).
isActivebooleanNãoIndica se já nasce ativa.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/tax-exemption-rules" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourTaxId": 1,
    "name": "Isenção Doc Longa Estadia",
    "conditions": {
      "min_nights": 30
    },
    "overrideRate": 0,
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID da regra criada.

json
{
  "id": 4
}

422 Unprocessable Entity

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

Obter Regra de Isenção por ID ​

Recupera os detalhes de uma regra de isenção.

http
GET /v1/tours/user/tax-exemption-rules/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da regra.

Respostas ​

200 OK

Retorna a regra.

json
{
  "id": 4,
  "tourId": 1,
  "tourTaxId": 1,
  "name": "Isenção Doc Longa Estadia",
  "conditions": {
    "min_nights": 30
  },
  "overrideRate": "0.000000",
  "isActive": true,
  "createdAt": "2026-10-07T15:11:16.168-03:00",
  "updatedAt": "2026-10-07T15:11:16.168-03:00"
}

404 Not Found

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

Atualizar Regra de Isenção ​

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

http
PUT /v1/tours/user/tax-exemption-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 de Isenção ​

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

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

Taxas de Serviço (Service Charge Rules) ​

Taxas adicionais sobre a conta — serviço, couvert ou gorjeta sugerida. Diferente dos impostos, a taxa de serviço é do estabelecimento: pode ser obrigatória (isMandatory) ou opcional, e pode compor a base de cálculo dos impostos (isTaxable). O campo scope é um objeto livre que restringe onde a regra se aplica (ex.: por categoria de produto).

Listar Taxas de Serviço ​

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

http
GET /v1/tours/user/service-charge-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 código ou nome (máx. 150 caracteres).
computationenumNãoFiltra por cálculo: percent ou fixed_per_unit.
isMandatorybooleanNãoFiltra por taxas obrigatórias/opcionais.
isActivebooleanNãoFiltra por taxas ativas/inativas.
orderByenumNãoid, name, code ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/service-charge-rules?isMandatory=true&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 taxas no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "code": "2W2SCLRQQT",
      "name": "Awesome Rubber Hat",
      "computation": "percent",
      "rate": "10.000000",
      "fixedAmount": null,
      "isMandatory": false,
      "isTaxable": false,
      "scope": {},
      "isActive": true,
      "createdAt": "2026-10-07T11:56:15.484-03:00",
      "updatedAt": "2026-10-07T11:56:15.484-03:00"
    }
  ]
}

Criar Taxa de Serviço ​

Cadastra uma nova taxa de serviço (permissão settings.manage).

http
POST /v1/tours/user/service-charge-rules

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo único na instância (máx. 50 caracteres).
namestringSimNome da taxa (máx. 150 caracteres).
computationenumNãoCálculo: percent (percentual sobre o valor) ou fixed_per_unit (valor fixo por unidade).
ratenumberNãoPercentual, quando computation é percent.
fixedAmountnumberNãoValor fixo por unidade, quando computation é fixed_per_unit.
isMandatorybooleanNãoIndica se a taxa é obrigatória (não removível pelo cliente).
isTaxablebooleanNãoIndica se a taxa compõe a base de cálculo dos impostos.
scopeobjectNãoEscopo de aplicação (objeto livre).
isActivebooleanNãoIndica se já nasce ativa.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/service-charge-rules" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-SCR-01",
    "name": "Taxa de serviço doc",
    "computation": "percent",
    "rate": 10,
    "isMandatory": false,
    "scope": {},
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID da taxa criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o código já 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).

Listar para Dropdown ​

Retorna as taxas de serviço em formato simplificado (value/label), ideal para selects.

http
GET /v1/tours/user/service-charge-rules/list

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

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/service-charge-rules/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 taxas.

json
[
  {
    "value": 1,
    "label": "Awesome Rubber Hat"
  },
  {
    "value": 4,
    "label": "Taxa de serviço doc"
  }
]

Obter Taxa de Serviço por ID ​

Recupera os detalhes de uma taxa de serviço.

http
GET /v1/tours/user/service-charge-rules/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da taxa de serviço.

Respostas ​

200 OK

Retorna a taxa.

json
{
  "id": 4,
  "tourId": 1,
  "code": "DOC-SCR-01",
  "name": "Taxa de serviço doc",
  "computation": "percent",
  "rate": "10.000000",
  "fixedAmount": null,
  "isMandatory": false,
  "isTaxable": false,
  "scope": {},
  "isActive": true,
  "createdAt": "2026-10-07T15:11:08.648-03:00",
  "updatedAt": "2026-10-07T15:11:08.648-03:00"
}

404 Not Found

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

Atualizar Taxa de Serviço ​

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

http
PUT /v1/tours/user/service-charge-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 Taxa de Serviço ​

Remove uma taxa de serviço via soft delete (permissão settings.manage).

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