Basis

Appearance

Turnos & Caixa ​

Esta página cobre dois recursos operacionais do dia a dia do estabelecimento:

  • Turnos (shifts): a escala da equipe — quando cada membro do staff está programado para trabalhar (scheduledStartsAt/scheduledEndsAt) e quando efetivamente trabalhou (actualStartsAt/actualEndsAt), por departamento (recepção, bar, governança...).
  • Sessões de caixa (cash sessions): a abertura e o fechamento de cada terminal de PDV, com fundo de troco (openingFloat) e conferência manual no fechamento — valor contado (countedAmount), valor esperado (expectedAmount) e a diferença (varianceAmount).

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). Não há endpoints públicos nesta página.

Turnos (Shifts) ​

O turno liga um usuário staff a uma janela de trabalho. Os campos scheduled* guardam o planejado; os campos actual* são preenchidos conforme o funcionário inicia/encerra o trabalho — a comparação entre os dois alimenta o controle de ponto e a alocação da equipe.

Permissão

As mutações (criar, atualizar e remover) exigem a permissão staff.manage. A consulta é livre para qualquer usuário staff autenticado.

Listar Turnos ​

Lista os turnos da instância, com paginação e filtros por funcionário, departamento e período.

http
GET /v1/tours/user/shifts

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).
tourUserIdnumberNãoFiltra pelos turnos de um usuário staff.
departmentstringNãoFiltra por departamento (máx. 100 caracteres).
fromstringNãoInício do período, no formato YYYY-MM-DD.
tostringNãoFim do período, no formato YYYY-MM-DD.
orderByenumNãoid ou scheduledStartsAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/shifts?department=bar&from=2026-10-01&to=2026-10-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 turnos no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourUserId": 1,
      "scheduledStartsAt": "2026-10-11T22:00:00.000-03:00",
      "scheduledEndsAt": "2026-10-12T06:00:00.000-03:00",
      "actualStartsAt": null,
      "actualEndsAt": null,
      "department": "bar",
      "notes": null,
      "createdAt": "2026-10-07T11:56:15.600-03:00",
      "updatedAt": "2026-10-07T11:56:15.600-03:00"
    }
  ]
}

Criar Turno ​

Agenda um turno para um membro da equipe. Exige a permissão staff.manage.

http
POST /v1/tours/user/shifts

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourUserIdnumberSimID do usuário staff escalado (deve existir na instância).
scheduledStartsAtstringSimInício programado do turno, em ISO 8601.
scheduledEndsAtstringSimFim programado do turno, em ISO 8601.
actualStartsAtstringNãoInício efetivo do turno, em ISO 8601 (null enquanto não iniciado).
actualEndsAtstringNãoFim efetivo do turno, em ISO 8601 (null enquanto não encerrado).
departmentstringNãoDepartamento do turno (máx. 100 caracteres), ex.: recepcao, bar.
notesstringNãoObservações livres sobre o turno.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/shifts" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourUserId": 1,
    "scheduledStartsAt": "2026-10-20T08:00:00.000-03:00",
    "scheduledEndsAt": "2026-10-20T16:00:00.000-03:00",
    "department": "Recepção",
    "notes": "Turno de documentação"
  }'

Respostas ​

201 Created

Retorna o ID do turno criado.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o payload é inválido ou o tourUserId não pertence à instância.

403 Forbidden

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

Obter Turno por ID ​

Recupera os detalhes de um turno, incluindo um resumo do usuário escalado.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID do turno.

Respostas ​

200 OK

Retorna o turno com o usuário staff relacionado.

json
{
  "id": 4,
  "tourId": 1,
  "tourUserId": 1,
  "scheduledStartsAt": "2026-10-20T08:00:00.000-03:00",
  "scheduledEndsAt": "2026-10-20T16:00:00.000-03:00",
  "actualStartsAt": null,
  "actualEndsAt": null,
  "department": "Recepção",
  "notes": "Turno de documentação",
  "createdAt": "2026-10-07T15:11:09.314-03:00",
  "updatedAt": "2026-10-07T15:11:09.315-03:00",
  "toursUser": {
    "id": 1,
    "displayName": "Bruno Demo"
  }
}

404 Not Found

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

Atualizar Turno ​

Atualiza o planejamento ou registra os horários efetivos (actualStartsAt/actualEndsAt) de um turno. Exige a permissão staff.manage.

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

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais — envie apenas o que deve mudar.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/shifts/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourUserId": 1,
    "scheduledStartsAt": "2026-10-20T09:00:00.000-03:00",
    "scheduledEndsAt": "2026-10-20T17:00:00.000-03:00",
    "actualStartsAt": "2026-10-20T09:05:00.000-03:00",
    "department": "Recepção",
    "notes": "Turno de documentação (editado)"
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o payload é inválido ou o tourUserId não pertence à instância.

403 Forbidden

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

Remover Turno ​

Remove um turno via soft delete. Exige a permissão staff.manage.

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

Respostas ​

204 No Content

Remoção concluída com sucesso.

403 Forbidden

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

Sessões de Caixa (Cash Sessions) ​

Cada terminal de PDV trabalha dentro de uma sessão de caixa: ela abre com um fundo de troco (openingFloat) e fecha com a conferência manual — o operador conta o dinheiro na gaveta (countedAmount), o sistema informa quanto deveria haver (expectedAmount) e a diferença fica registrada em varianceAmount. Uma sessão está aberta enquanto closedAt for null — é ela que recebe os pagamentos em dinheiro lançados no terminal (ver Financeiro).

Permissão

As mutações (abrir, atualizar/fechar e remover) exigem a permissão cash.open_close. A consulta é livre para qualquer usuário staff autenticado.

Listar Sessões de Caixa ​

Lista as sessões de caixa da instância, com paginação e filtros — incluindo isOpen para ver apenas os caixas abertos no momento.

http
GET /v1/tours/user/cash-sessions

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).
terminalCodestringNãoFiltra pelo código do terminal (máx. 50 caracteres).
openedByTourUserIdnumberNãoFiltra por quem abriu a sessão.
fromstringNãoInício do período, no formato YYYY-MM-DD.
tostringNãoFim do período, no formato YYYY-MM-DD.
isOpenbooleanNãotrue para apenas sessões abertas; false para fechadas.
orderByenumNãoid, openedAt ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/cash-sessions?isOpen=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 sessões no formato meta/data. Os valores monetários são strings decimais com 2 casas.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "terminalCode": "VBXPP8",
      "openedByTourUserId": 1,
      "openedAt": "2026-10-07T11:56:15.618-03:00",
      "openingFloat": "150.00",
      "closedByTourUserId": null,
      "closedAt": null,
      "countedAmount": null,
      "expectedAmount": null,
      "varianceAmount": null,
      "notes": null,
      "createdAt": "2026-10-07T11:56:15.618-03:00",
      "updatedAt": "2026-10-07T11:56:15.618-03:00"
    }
  ]
}

Abrir Sessão de Caixa ​

Abre o caixa de um terminal com o fundo de troco inicial. Exige a permissão cash.open_close.

http
POST /v1/tours/user/cash-sessions

Payload (Body) ​

AtributoTipoObrigatórioDescrição
terminalCodestringSimCódigo do terminal de PDV (máx. 50 caracteres).
openedAtstringSimMomento da abertura, em ISO 8601.
openingFloatnumberSimFundo de troco inicial, na moeda da instância.
openedByTourUserIdnumberNãoID do usuário staff que abriu o caixa (deve existir na instância).
notesstringNãoObservações livres sobre a sessão.

O payload também aceita os campos de fechamento (closedAt, closedByTourUserId, countedAmount, expectedAmount, varianceAmount) para registrar sessões já encerradas — na prática, o fechamento é feito via atualização.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/cash-sessions" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "terminalCode": "DOC-01",
    "openedAt": "2026-10-20T08:00:00.000-03:00",
    "openingFloat": 200,
    "openedByTourUserId": 1,
    "notes": "Sessão de caixa de documentação"
  }'

Respostas ​

201 Created

Retorna o ID da sessão criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o payload é inválido ou o usuário informado não pertence à instância.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão cash.open_close (code: FORBIDDEN).

Listar para Dropdown ​

Retorna as sessões em formato simplificado (value/label com o código do terminal), ideal para selects — como escolher o caixa ao registrar um pagamento em dinheiro.

http
GET /v1/tours/user/cash-sessions/list

Aceita search e isOpen como filtros opcionais de query.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/cash-sessions/list?isOpen=true" \
  -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 sessões.

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

Obter Sessão por ID ​

Recupera os detalhes de uma sessão de caixa, incluindo quem abriu e quem fechou.

http
GET /v1/tours/user/cash-sessions/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da sessão de caixa.

Respostas ​

200 OK

Retorna a sessão com os usuários de abertura e fechamento relacionados.

json
{
  "id": 4,
  "tourId": 1,
  "terminalCode": "DOC-01",
  "openedByTourUserId": 1,
  "openedAt": "2026-10-20T08:00:00.000-03:00",
  "openingFloat": "200.00",
  "closedByTourUserId": null,
  "closedAt": null,
  "countedAmount": null,
  "expectedAmount": null,
  "varianceAmount": null,
  "notes": "Sessão de caixa de documentação",
  "createdAt": "2026-10-07T15:10:41.803-03:00",
  "updatedAt": "2026-10-07T15:10:41.803-03:00",
  "closedByTourUser": null,
  "openedByTourUser": {
    "id": 1,
    "displayName": "Bruno Demo"
  }
}

404 Not Found

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

Atualizar Sessão de Caixa ​

Atualiza os dados da sessão — é aqui que acontece o fechamento: preencha closedAt, closedByTourUserId e os valores da conferência manual. Exige a permissão cash.open_close.

http
PUT /v1/tours/user/cash-sessions/:id

Payload (Body) ​

AtributoTipoObrigatórioDescrição
terminalCodestringNãoCódigo do terminal de PDV (máx. 50 caracteres).
openedAtstringNãoMomento da abertura, em ISO 8601.
openingFloatnumberNãoFundo de troco inicial.
openedByTourUserIdnumberNãoID do usuário staff que abriu o caixa.
closedAtstringNãoMomento do fechamento, em ISO 8601 — preencher encerra a sessão.
closedByTourUserIdnumberNãoID do usuário staff que fechou o caixa.
countedAmountnumberNãoValor contado na gaveta no fechamento.
expectedAmountnumberNãoValor esperado pelo sistema (fundo + vendas em dinheiro − sangrias).
varianceAmountnumberNãoDiferença entre o contado e o esperado (quebra de caixa).
notesstringNãoObservações livres sobre a sessão.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/cash-sessions/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "closedAt": "2026-10-20T18:00:00.000-03:00",
    "closedByTourUserId": 1,
    "countedAmount": 1450,
    "expectedAmount": 1450,
    "varianceAmount": 0,
    "notes": "Fechamento sem divergência"
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o payload é inválido ou o usuário informado não pertence à instância.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão cash.open_close (code: FORBIDDEN).

Remover Sessão de Caixa ​

Remove uma sessão via soft delete — útil para corrigir uma abertura feita por engano. Exige a permissão cash.open_close.

http
DELETE /v1/tours/user/cash-sessions/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão cash.open_close (code: FORBIDDEN).