Basis

Appearance

Instâncias & Setup ​

Uma instância Tours é o estabelecimento do seu negócio dentro da plataforma: a pousada, o beach club, a operadora de passeios. Recursos reserváveis, tarifas, reservas, POS, estoque e financeiro vivem dentro dela. Antes de usar qualquer endpoint do Tours (/v1/tours/...), você precisa provisionar uma instância — e é isso que estes endpoints fazem.

A criação é mais do que um simples INSERT: em uma única transação, a plataforma cria a instância com sua configuração operacional (fuso, moeda, virada do dia, horários de check-in/check-out), semeia as 29 permissões do módulo, cria o papel owner com todas elas e o primeiro usuário staff, devolvendo as credenciais de acesso e o tokenHeader que identifica a instância em todas as chamadas seguintes.

Headers obrigatórios

Estes endpoints pertencem à área do dono da conta na plataforma. Todas as requisições exigem Authorization: Bearer {token} (autenticação da plataforma, guard user) e o parâmetro de query workspaceId com o ID do projeto. O header X-Tour-Id não é usado aqui — ele é o tokenHeader gerado na criação da instância. Limite de 100 requisições por minuto (429 ao exceder).

Estrutura de Dados Principal ​

Uma instância Tours contém as seguintes informações principais:

CampoTipoDescrição
nameStringNome do estabelecimento (máx. 150 caracteres).
slugStringSlug gerado automaticamente a partir do nome, único por workspace. Imutável após a criação.
tokenHeaderStringUUID que identifica a instância — usado como X-Tour-Id nas APIs /v1/tours/**.
legalNameStringRazão social (máx. 200 caracteres, opcional).
timezoneStringFuso horário do estabelecimento (padrão: UTC) — rege a apresentação de datas e horários.
currencyStringMoeda da instância, código ISO de 3 letras (padrão: BRL).
localeStringLocalidade padrão (máx. 10 caracteres, padrão: pt-BR).
businessDayStartStringHora de virada do dia operacional, no formato HH:mm (padrão: 00:00).
defaultCheckIn / defaultCheckOutStringHorários padrão de check-in e check-out, no formato HH:mm (opcionais).
addressStreet … addressCountryStringEndereço completo do estabelecimento (todos opcionais; país com 2 letras, ex.: BR).
geoLat / geoLngNumberCoordenadas geográficas (latitude -90 a 90, longitude -180 a 180).
isActiveBooleanIndica se a instância está ativa.
workspaceStorageIdNumberProvedor de armazenamento do projeto (nulo se não vinculado).
workspaceMailIdNumberProvedor de e-mail do projeto (nulo se não vinculado).

Dia operacional

O businessDayStart define quando o dia operacional vira — útil para beach clubs e baladas que fecham depois da meia-noite: com 02:00, a venda de 01:30 ainda pertence ao dia anterior. Os defaultCheckIn/defaultCheckOut servem de padrão para as reservas de hospedagem.

Setup Inicial ​

O POST /user/tours executa todo o provisionamento em uma única transação — se qualquer etapa falhar, nada é persistido:

  1. Instância: criada com nome, slug único no workspace (com sufixo incremental -2, -3… em caso de colisão), tokenHeader (UUID) e configuração operacional.
  2. Domínios: os workspaceDomains informados são vinculados à instância — sem eles, as APIs /v1/tours/** recusam requisições (401 por origem não autorizada).
  3. Permissões: as 29 permissões do módulo são semeadas no catálogo global (ver Papéis & Permissões).
  4. Papel owner: criado com code: owner, nome Proprietário, isSystem: true e todas as permissões.
  5. Primeiro usuário staff: criado com o nome e o e-mail do usuário autenticado na plataforma, PIN aleatório de 6 dígitos e o papel owner.
  6. Resposta 201: inclui email, pin (exibido uma única vez) e tokenHeader.

Guarde o PIN e o tokenHeader imediatamente — eles não podem ser recuperados depois (o token pode ser regerado, o PIN não; o usuário pode trocá-lo em Trocar PIN).

Endpoints ​

Listar Instâncias ​

Lista as instâncias Tours do projeto, com paginação e busca por nome.

http
GET /user/tours

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
workspaceIdnumberSimID do projeto (workspace) ao qual a instância pertence.
pagenumberNãoO número da página (mínimo: 1).
perPagenumberNãoItens por página (entre 1 e 100, padrão: 25).
searchstringNãoBusca por termo no nome da instância (máx. 150 caracteres).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/user/tours?workspaceId=1&page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna um objeto de paginação contendo a lista de instâncias, ordenadas da mais recente para a mais antiga.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "2",
      "name": "Pousada Mar Azul - Anexo",
      "slug": "pousada-mar-azul-2",
      "tokenHeader": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

403 Forbidden

Ocorre quando o workspaceId não é informado ou o projeto pertence a outro usuário.

json
{
  "notice": "O projeto precisa ser informado",
  "field": "workspaceId"
}

Criar Instância ​

Provisiona uma nova instância Tours, executando o setup inicial completo em transação.

http
POST /user/tours

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tour.namestringSimNome do estabelecimento (máx. 150 caracteres).
tour.legalNamestringNãoRazão social (máx. 200 caracteres).
tour.timezonestringNãoFuso horário (máx. 64 caracteres, padrão: UTC).
tour.currencystringNãoMoeda, código ISO de 3 letras maiúsculas (padrão: BRL).
tour.localestringNãoLocalidade (máx. 10 caracteres, padrão: pt-BR).
tour.businessDayStartstringNãoVirada do dia operacional, HH:mm (padrão: 00:00).
tour.defaultCheckInstringNãoHorário padrão de check-in, HH:mm.
tour.defaultCheckOutstringNãoHorário padrão de check-out, HH:mm.
tour.addressStreetstringNãoLogradouro (máx. 200 caracteres).
tour.addressNumberstringNãoNúmero (máx. 20 caracteres).
tour.addressComplementstringNãoComplemento (máx. 100 caracteres).
tour.addressDistrictstringNãoBairro (máx. 100 caracteres).
tour.addressCitystringNãoCidade (máx. 100 caracteres).
tour.addressStatestringNãoEstado (máx. 100 caracteres).
tour.addressZipCodestringNãoCEP (máx. 20 caracteres).
tour.addressCountrystringNãoPaís, código de 2 letras maiúsculas (ex.: BR).
tour.geoLatnumberNãoLatitude (-90 a 90).
tour.geoLngnumberNãoLongitude (-180 a 180).
tour.workspaceStorageIdnumberNãoID do provedor de armazenamento do projeto (deve existir e estar ativo).
tour.workspaceMailIdnumberNãoID do provedor de e-mail do projeto (deve existir e estar ativo).
tour.isActivebooleanNãoIndica se a instância já nasce ativa (padrão: true).
workspaceDomainsnumber[]SimIDs dos domínios do projeto vinculados à instância (pode ser um array vazio).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/user/tours?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tour": {
      "name": "Pousada Mar Azul",
      "timezone": "America/Sao_Paulo",
      "currency": "BRL",
      "locale": "pt-BR",
      "businessDayStart": "03:00",
      "defaultCheckIn": "14:00",
      "defaultCheckOut": "12:00",
      "workspaceStorageId": null,
      "workspaceMailId": null
    },
    "workspaceDomains": [3]
  }'

Respostas ​

201 Created

Retorna as credenciais do primeiro usuário staff e o token da instância. O PIN é exibido uma única vez.

json
{
  "email": "maria@pousadamarazul.com",
  "pin": "483920",
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json
{
  "errors": [
    {
      "message": "Nome é obrigatório",
      "rule": "required",
      "field": "tour.name"
    }
  ]
}

Obter Instância por ID ​

Recupera os detalhes de uma instância, incluindo os domínios, o provedor de armazenamento e o provedor de e-mail vinculados.

http
GET /user/tours/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da instância.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/user/tours/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna a instância com workspaceDomains, workspaceStorage e workspaceMail.

json
{
  "id": "1",
  "workspaceId": "1",
  "workspaceMailId": null,
  "workspaceStorageId": null,
  "name": "Pousada Mar Azul",
  "slug": "pousada-mar-azul",
  "legalName": "Pousada Mar Azul LTDA",
  "timezone": "America/Sao_Paulo",
  "currency": "BRL",
  "locale": "pt-BR",
  "businessDayStart": "03:00",
  "defaultCheckIn": "14:00",
  "defaultCheckOut": "12:00",
  "addressStreet": "Av. Beira Mar",
  "addressNumber": "1200",
  "addressComplement": null,
  "addressDistrict": "Centro",
  "addressCity": "Florianópolis",
  "addressState": "Santa Catarina",
  "addressZipCode": "88010000",
  "addressCountry": "BR",
  "geoLat": "-27.5954",
  "geoLng": "-48.5480",
  "settings": {},
  "isActive": true,
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAt": "2026-09-01T10:05:33.000+00:00",
  "updatedAt": "2026-09-01T10:05:33.000+00:00",
  "deletedAt": null,
  "workspaceDomains": [
    {
      "id": "3",
      "uri": "pousada.local"
    }
  ],
  "workspaceStorage": null,
  "workspaceMail": null
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Atualizar Instância ​

Atualiza as configurações de uma instância e sincroniza os domínios vinculados. O slug e o tokenHeader não mudam, e o usuário owner não é recriado.

http
PUT /user/tours/:id

Payload (Body) ​

Aceita os mesmos campos da criação: o objeto tour (todos opcionais aqui) e o array workspaceDomains (que, quando enviado, substitui os vínculos atuais).

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/user/tours/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tour": {
      "name": "Pousada Mar Azul",
      "defaultCheckOut": "11:00",
      "businessDayStart": "04:00",
      "workspaceStorageId": null,
      "workspaceMailId": null
    },
    "workspaceDomains": [3]
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Remover Instância ​

Remove uma instância via soft delete — o registro deixa de aparecer em qualquer consulta, mas não é apagado fisicamente.

http
DELETE /user/tours/:id

Exemplo de Requisição ​

bash
curl -X DELETE "https://api.us.basis.tavares.in/user/tours/1?workspaceId=1" \
  -H "Authorization: Bearer {token}"

Respostas ​

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Listar para Dropdown ​

Retorna as instâncias em formato simplificado (value/label), ideal para selects no frontend.

http
GET /user/tours/list

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
workspaceIdnumberSimID do projeto (workspace).
searchstringNãoBusca por termo no nome da instância (máx. 150 caracteres).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/user/tours/list?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna um array com as instâncias ordenadas por nome.

json
[
  {
    "value": 1,
    "label": "Pousada Mar Azul"
  },
  {
    "value": 2,
    "label": "Pousada Mar Azul - Anexo"
  }
]

Regerar Token da Instância ​

Gera um novo tokenHeader (UUID) para a instância. O token anterior deixa de ser válido imediatamente — todas as integrações que usam o header X-Tour-Id precisam ser atualizadas.

http
PATCH /user/tours/:id/change-token

Exemplo de Requisição ​

bash
curl -X PATCH "https://api.us.basis.tavares.in/user/tours/1/change-token?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna o novo token da instância.

json
{
  "tokenHeader": "9b2f7c1e-4d3a-4e5f-8a6b-1c2d3e4f5a6b"
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.