Basis

Appearance

Financeiro ​

O financeiro do módulo de Tours organiza a conta do cliente em três camadas: o folio é o extrato que acumula tudo que o hóspede (ou a mesa) consumiu; os lançamentos (folio charges) são as linhas desse extrato — diárias, consumos do POS, taxas de serviço e ajustes — cada um com seus impostos congelados; e as contas (bills) fecham o folio para pagamento, com suporte a split (divisão) por item, por cota ou por assento. Os pagamentos registram cada recebimento manual e os estornos.

Tudo que entra no extrato congela valores e impostos no momento do lançamento: a tabela de preços e as alíquotas podem mudar, a conta já emitida continua auditável. Pagamentos e lançamentos são livros-razão — não usam soft delete; correções são feitas por void/estorno, nunca por edição silenciosa.

Headers obrigatórios

Todas as requisições devem incluir o header X-Tour-Id (UUID) com o tokenHeader da instância e Authorization: Bearer {token} com o token de um usuário staff (guard toursUser). Mutações exigem permissão — bill.issue (folios, lançamentos e contas), bill.split (linhas da conta) ou payment.record (pagamentos). A API responde 403 com code: FORBIDDEN quando a permissão falta.

Folios ​

O folio é o extrato do cliente: aberto no check-in ou na primeira comanda, acumula os lançamentos e é fechado (closed) ou anulado (void) na saída. Pode ser vinculado a uma reserva (tourReservationId), a um cliente do CRM (tourCustomerId) ou a ambos. O status é open, closed ou void, e quem fecha/anula é registrado em closedByTourUserId (injetado com o usuário autenticado).

Listar Folios ​

http
GET /v1/tours/user/folios

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 termo no código do folio (máx. 150 caracteres).
statusenumNãoopen, closed ou void.
tourReservationIdnumberNãoFiltra por reserva vinculada.
tourCustomerIdnumberNãoFiltra por cliente vinculado.
orderByenumNãoid, code, openedAt, closedAt ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/folios?status=open" \
  -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 folios no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourReservationId": 1,
      "tourCustomerId": 1,
      "closedByTourUserId": null,
      "code": "IZTYL5BY",
      "status": "open",
      "openedAt": "2026-10-07T11:56:15.217-03:00",
      "closedAt": null,
      "notes": null,
      "createdAt": "2026-10-07T11:56:15.217-03:00",
      "updatedAt": "2026-10-07T11:56:15.217-03:00"
    }
  ]
}

Abrir Folio ​

Abre um novo folio (exige a permissão bill.issue). Se já nascer closed ou void, o closedByTourUserId é injetado com o usuário autenticado.

http
POST /v1/tours/user/folios

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo do folio (máx. 30 caracteres).
tourReservationIdnumberNãoReserva vinculada.
tourCustomerIdnumberNãoCliente vinculado.
statusenumNãoopen, closed ou void (padrão: open).
openedAtstringNãoData/hora de abertura em ISO 8601 (padrão: agora).
closedAtstringNãoData/hora de fechamento em ISO 8601.
notesstringNãoObservações do folio.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/folios" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-FOL-01",
    "tourReservationId": 1,
    "tourCustomerId": 1,
    "status": "open",
    "openedAt": "2026-10-20T14:00:00.000-03:00",
    "notes": "Folio doc"
  }'

Respostas ​

201 Created

Retorna o ID do folio aberto.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o payload é inválido ou a reserva/cliente informado não existe na instância.

403 Forbidden

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

Listar Folios para Dropdown ​

Retorna os folios em formato simplificado (value/label com o código), ideal para selects.

http
GET /v1/tours/user/folios/list

Aceita search, status e limit (1 a 1000) como parâmetros opcionais de query.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/folios/list?status=open" \
  -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 folios.

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

Obter Folio por ID ​

Recupera os detalhes de um folio, incluindo reserva, cliente, lançamentos e quem fechou.

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

Respostas ​

200 OK

Retorna o folio com os relacionamentos.

json
{
  "id": 4,
  "tourId": 1,
  "tourReservationId": 1,
  "tourCustomerId": 1,
  "closedByTourUserId": null,
  "code": "DOC-FOL-01",
  "status": "open",
  "openedAt": "2026-10-20T14:00:00.000-03:00",
  "closedAt": null,
  "notes": "Folio doc",
  "createdAt": "2026-10-07T15:10:46.550-03:00",
  "updatedAt": "2026-10-07T15:10:46.550-03:00",
  "toursCustomer": {
    "id": 1,
    "fullName": "Mr. Rogelio Cummerata III"
  },
  "closedByTourUser": null,
  "toursFolioCharges": [],
  "toursReservation": {
    "id": 1,
    "code": "YB73C5BU2G"
  }
}

404 Not Found

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

Atualizar Folio ​

Atualiza vínculos, status e observações de um folio (exige a permissão bill.issue). Ao mudar o status para closed ou void, o closedByTourUserId é injetado. O code não pode ser alterado.

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

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

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

Remover Folio ​

Remove um folio via soft delete (exige a permissão bill.issue).

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

Respostas ​

204 No Content

Remoção concluída com sucesso.

Lançamentos (Folio Charges) ​

Cada lançamento é uma linha do extrato. A source indica a origem: reservation_item (diária/item da reserva), order_item (consumo do POS), service_charge (taxa de serviço), gratuity (gorjeta), manual (lançamento manual na recepção) ou adjustment (ajuste). Lançamentos de reserva e de POS carregam o vínculo de origem (tourReservationItemId / tourOrderItemId).

O businessDate é o dia operacional do lançamento: respeita a virada de dia configurada na instância — um consumo de 2h da manhã ainda pertence ao dia operacional anterior. Quem lançou é registrado em postedByTourUserId (injetado). Para anular, envie voidedAt + voidReason — o voidedByTourUserId é injetado. Valores monetários são retornados como strings decimais.

Listar Lançamentos ​

http
GET /v1/tours/user/folio-charges

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 termo na descrição (máx. 255 caracteres).
tourFolioIdnumberNãoFiltra por folio.
sourceenumNãoreservation_item, order_item, service_charge, gratuity, manual ou adjustment.
fromstringNãoInício do período por businessDate (YYYY-MM-DD).
tostringNãoFim do período por businessDate (YYYY-MM-DD).
voidedbooleanNãoFiltra lançamentos anulados/vigentes.
orderByenumNãoid, businessDate, postedAt, totalAmount ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/folio-charges?tourFolioId=1&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 lançamentos no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourFolioId": 1,
      "tourReservationItemId": null,
      "tourOrderItemId": 1,
      "source": "manual",
      "description": "Elegant Marble Mouse",
      "quantity": "1.0000",
      "unitAmount": "150.00",
      "discountAmount": "0.00",
      "netAmount": "150.00",
      "taxAmount": "0.00",
      "totalAmount": "150.00",
      "businessDate": "2026-10-07",
      "postedAt": "2026-10-07T11:56:15.421-03:00",
      "voidedAt": null,
      "createdAt": "2026-10-07T11:56:15.421-03:00"
    }
  ]
}

Criar Lançamento ​

Lança uma linha no folio (exige a permissão bill.issue). O postedByTourUserId é injetado com o usuário autenticado; ao enviar voidedAt, o voidedByTourUserId também é injetado.

http
POST /v1/tours/user/folio-charges

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourFolioIdnumberSimFolio que recebe o lançamento.
sourceenumSimreservation_item, order_item, service_charge, gratuity, manual ou adjustment.
descriptionstringSimDescrição exibida no extrato (máx. 255 caracteres).
businessDatestringSimDia operacional do lançamento (YYYY-MM-DD).
tourReservationItemIdnumberNãoItem de reserva de origem (quando source é reservation_item).
tourOrderItemIdnumberNãoItem de pedido de origem (quando source é order_item).
quantitynumberNãoQuantidade.
unitAmountnumberNãoValor unitário.
discountAmountnumberNãoDesconto aplicado.
netAmountnumberNãoValor líquido (sem impostos).
taxAmountnumberNãoTotal de impostos.
totalAmountnumberNãoTotal do lançamento.
postedAtstringNãoData/hora do lançamento em ISO 8601 (padrão: agora).
voidedAtstringNãoMarca a anulação — voidedByTourUserId é injetado.
voidReasonstringNãoMotivo da anulação.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/folio-charges" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourFolioId": 1,
    "source": "manual",
    "description": "Taxa de limpeza",
    "quantity": 1,
    "unitAmount": 80,
    "netAmount": 80,
    "totalAmount": 80,
    "businessDate": "2026-10-07"
  }'

Respostas ​

201 Created

Retorna o ID do lançamento criado.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o folio não existe na instância ou o payload é inválido.

403 Forbidden

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

Obter Lançamento por ID ​

Recupera os detalhes de um lançamento, incluindo quem lançou e os impostos congelados.

http
GET /v1/tours/user/folio-charges/:id

Respostas ​

200 OK

Retorna o lançamento com postedByTourUser e toursFolioChargeTaxes.

json
{
  "id": 4,
  "tourId": 1,
  "tourFolioId": 1,
  "tourReservationItemId": null,
  "tourOrderItemId": null,
  "postedByTourUserId": 1,
  "voidedByTourUserId": null,
  "source": "manual",
  "description": "Taxa de limpeza",
  "quantity": "1.0000",
  "unitAmount": "80.00",
  "discountAmount": "0.00",
  "netAmount": "80.00",
  "taxAmount": "0.00",
  "totalAmount": "80.00",
  "businessDate": "2026-10-07",
  "postedAt": "2026-10-07T15:10:45.769-03:00",
  "voidedAt": null,
  "voidReason": null,
  "createdAt": "2026-10-07T15:10:45.770-03:00",
  "updatedAt": "2026-10-07T15:10:45.770-03:00",
  "postedByTourUser": {
    "id": 1,
    "displayName": "Bruno Demo"
  },
  "toursFolioChargeTaxes": []
}

404 Not Found

Ocorre quando o lançamento não existe na instância.

Atualizar Lançamento ​

Atualiza valores, descrição ou anula um lançamento (exige a permissão bill.issue). Aceita os mesmos campos da criação, todos opcionais. Para anular, envie voidedAt + voidReason — o voidedByTourUserId é injetado com o usuário autenticado.

http
PUT /v1/tours/user/folio-charges/:id

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando o lançamento não existe na instância.

Remover Lançamento ​

Remove o registro do lançamento (exige a permissão bill.issue). A tabela de lançamentos é um livro-razão e não usa soft delete — prefira anular (voidedAt + voidReason) para manter a trilha de auditoria.

http
DELETE /v1/tours/user/folio-charges/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

Impostos do Lançamento (somente leitura) ​

Cada lançamento grava seus impostos congelados: código, nome, forma de cálculo (computation), alíquota (rateSnapshot), base (taxableAmount) e valor — inclusive se o imposto é incluso no preço (isInclusive) e se compõe sobre outro (isCompound), na ordem de aplicação (sequence). Alíquotas podem mudar no cadastro de impostos; o que já foi lançado permanece como foi calculado.

Listar Impostos de um Lançamento ​

http
GET /v1/tours/user/folio-charge-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).
tourFolioChargeIdnumberSimLançamento dono dos impostos.
orderByenumNãoid ou sequence.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/folio-charge-taxes?tourFolioChargeId=1" \
  -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,
      "tourFolioChargeId": 1,
      "tourTaxId": 1,
      "taxCode": "ISS",
      "taxName": "Imposto sobre serviços",
      "computation": "percent",
      "rateSnapshot": "5.000000",
      "taxableAmount": "150.00",
      "taxAmount": "7.50",
      "isInclusive": false,
      "isCompound": false,
      "sequence": 1
    }
  ]
}

422 Unprocessable Entity

Ocorre quando tourFolioChargeId não é informado ou o lançamento não existe na instância.

Obter Imposto por ID ​

http
GET /v1/tours/user/folio-charge-taxes/:id

Respostas ​

200 OK

Retorna o imposto congelado com o imposto de origem (toursTax).

json
{
  "id": 1,
  "tourId": 1,
  "tourFolioChargeId": 1,
  "tourTaxId": 1,
  "taxCode": "ISS",
  "taxName": "Imposto sobre serviços",
  "computation": "percent",
  "rateSnapshot": "5.000000",
  "taxableAmount": "150.00",
  "taxAmount": "7.50",
  "isInclusive": false,
  "isCompound": false,
  "sequence": 1,
  "toursTax": {
    "id": 1,
    "code": "WMC2M1",
    "name": "Elegant Cotton Salad"
  }
}

404 Not Found

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

Contas (Bills) ​

A conta fecha um folio (ou parte dele) para pagamento. O splitMethod define como o consumo é dividido: full (conta única), by_item (cada conta leva seus itens), by_share (divisão por cota — shareNumerator/shareDenominator, ex.: 1/2) ou by_seat (cada assento paga o que consumiu). O pagador é identificado por tourCustomerId (cliente do CRM) e/ou payerName (nome livre).

A conta nasce draft, é emitida (issued — com issuedByTourUserId injetado e issuedAt), quitada (settled, com settledAt) ou anulada (void). Os totais incluem serviceChargeAmount (taxa de serviço), gratuityAmount (gorjeta) e roundingAmount (arredondamento de fechamento). A composição item a item fica nas linhas da conta.

Listar Contas ​

http
GET /v1/tours/user/bills

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 termo no código da conta (máx. 150 caracteres).
tourFolioIdnumberNãoFiltra por folio.
statusenumNãodraft, issued, settled ou void.
splitMethodenumNãofull, by_item, by_share ou by_seat.
tourCustomerIdnumberNãoFiltra por cliente pagador.
orderByenumNãoid, code, totalAmount, issuedAt ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/bills?tourFolioId=1&status=draft" \
  -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 contas no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourFolioId": 1,
      "tourCustomerId": 1,
      "code": "EXKL89YTAP",
      "splitMethod": "full",
      "payerName": null,
      "netAmount": "100.00",
      "taxAmount": "0.00",
      "serviceChargeAmount": "0.00",
      "gratuityAmount": "0.00",
      "roundingAmount": "0.00",
      "totalAmount": "100.00",
      "status": "draft",
      "issuedAt": null,
      "settledAt": null,
      "createdAt": "2026-10-07T11:56:15.513-03:00"
    }
  ]
}

Criar Conta ​

Cria uma conta sobre um folio (exige a permissão bill.issue). Se já nascer com status: "issued", o issuedByTourUserId é injetado com o usuário autenticado.

http
POST /v1/tours/user/bills

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourFolioIdnumberSimFolio fechado por esta conta.
codestringSimCódigo da conta (máx. 30 caracteres).
splitMethodenumNãofull, by_item, by_share ou by_seat (padrão: full).
shareNumeratornumberNãoNumerador da cota (inteiro) — split by_share.
shareDenominatornumberNãoDenominador da cota (inteiro) — split by_share.
seatNumbernumberNãoAssento (inteiro) — split by_seat.
tourCustomerIdnumberNãoCliente pagador.
payerNamestringNãoNome do pagador, em texto livre (máx. 150 caracteres).
netAmountnumberNãoValor líquido.
taxAmountnumberNãoTotal de impostos.
serviceChargeAmountnumberNãoTaxa de serviço.
gratuityAmountnumberNãoGorjeta.
roundingAmountnumberNãoArredondamento de fechamento.
totalAmountnumberNãoTotal da conta.
statusenumNãodraft, issued, settled ou void (padrão: draft).
issuedAtstringNãoData/hora de emissão em ISO 8601.
settledAtstringNãoData/hora de quitação em ISO 8601.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/bills" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourFolioId": 1,
    "code": "DOC-BILL-01",
    "splitMethod": "full",
    "netAmount": 380,
    "totalAmount": 380
  }'

Respostas ​

201 Created

Retorna o ID da conta criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o folio não existe na instância ou o payload é inválido.

403 Forbidden

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

Listar Contas para Dropdown ​

Retorna as contas em formato simplificado (value/label com o código), ideal para selects — como o vínculo de conta ao registrar um pagamento.

http
GET /v1/tours/user/bills/list

Aceita search, status e limit (1 a 1000) como parâmetros opcionais de query.

Exemplo de Requisição ​

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

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

Obter Conta por ID ​

Recupera os detalhes de uma conta, incluindo folio, pagador, linhas e pagamentos.

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

Respostas ​

200 OK

Retorna a conta com toursBillLines e toursPayments.

json
{
  "id": 4,
  "tourId": 1,
  "tourFolioId": 1,
  "tourCustomerId": null,
  "issuedByTourUserId": null,
  "code": "DOC-BILL-01",
  "splitMethod": "full",
  "shareNumerator": null,
  "shareDenominator": null,
  "seatNumber": null,
  "payerName": null,
  "netAmount": "380.00",
  "taxAmount": "0.00",
  "serviceChargeAmount": "0.00",
  "gratuityAmount": "0.00",
  "roundingAmount": "0.00",
  "totalAmount": "380.00",
  "status": "draft",
  "issuedAt": null,
  "settledAt": null,
  "createdAt": "2026-10-07T15:10:38.226-03:00",
  "updatedAt": "2026-10-07T15:10:38.226-03:00",
  "toursFolio": {
    "id": 1,
    "code": "IZTYL5BY"
  },
  "issuedByTourUser": null,
  "toursCustomer": null,
  "toursBillLines": [],
  "toursPayments": []
}

404 Not Found

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

Atualizar Conta ​

Atualiza valores, split e status de uma conta (exige a permissão bill.issue). Aceita os mesmos campos da criação, todos opcionais. Ao mudar o status para issued, o issuedByTourUserId é injetado com o usuário autenticado.

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

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/bills/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourFolioId": 1,
    "code": "DOC-BILL-01",
    "splitMethod": "full",
    "netAmount": 380,
    "totalAmount": 380,
    "status": "issued",
    "issuedAt": "2026-10-07T14:00:00.000-03:00"
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

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

Remover Conta ​

Remove uma conta via soft delete (exige a permissão bill.issue).

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

Respostas ​

204 No Content

Remoção concluída com sucesso.

Linhas da Conta (Bill Lines) ​

A linha da conta conecta um lançamento do folio a uma conta — é o mecanismo do split: no by_item, cada lançamento entra inteiro na conta de alguém; com portion menor que 1, um mesmo lançamento é dividido entre contas (ex.: a garrafa de vinho dividida meio a meio). A soma das portion de um lançamento entre todas as contas deve fechar em 1.

Listar Linhas ​

http
GET /v1/tours/user/bill-lines

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).
tourBillIdnumberSimConta dona das linhas.
orderByenumNãoid.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/bill-lines?tourBillId=1" \
  -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 linhas no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourBillId": 1,
      "tourFolioChargeId": 1,
      "portion": "1.000000",
      "netAmount": "100.00",
      "taxAmount": "0.00",
      "totalAmount": "100.00"
    }
  ]
}

422 Unprocessable Entity

Ocorre quando tourBillId não é informado.

Adicionar Linha ​

Vincula um lançamento (ou uma porção dele) a uma conta (exige a permissão bill.split).

http
POST /v1/tours/user/bill-lines

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourBillIdnumberSimConta que recebe a linha.
tourFolioChargeIdnumberSimLançamento do folio vinculado.
portionnumberNãoFração do lançamento nesta conta (padrão: 1 = integral).
netAmountnumberNãoValor líquido da porção.
taxAmountnumberNãoImpostos da porção.
totalAmountnumberNãoTotal da porção.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/bill-lines" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourBillId": 1,
    "tourFolioChargeId": 1,
    "portion": 1,
    "netAmount": 80,
    "totalAmount": 80
  }'

Respostas ​

201 Created

Retorna o ID da linha criada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando a conta ou o lançamento não existem na instância.

403 Forbidden

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

Obter Linha por ID ​

http
GET /v1/tours/user/bill-lines/:id

Respostas ​

200 OK

Retorna a linha com o lançamento de origem (toursFolioCharge).

json
{
  "id": 4,
  "tourId": 1,
  "tourBillId": 1,
  "tourFolioChargeId": 1,
  "portion": "1.000000",
  "netAmount": "80.00",
  "taxAmount": "0.00",
  "totalAmount": "80.00",
  "toursFolioCharge": {
    "id": 1,
    "description": "Elegant Marble Mouse",
    "totalAmount": "150.00",
    "businessDate": "2026-10-07"
  }
}

404 Not Found

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

Atualizar Linha ​

Reajusta a porção de uma linha (exige a permissão bill.split). Apenas portion pode ser alterado — os valores da porção são recalculados a partir dela.

http
PUT /v1/tours/user/bill-lines/:id

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/bill-lines/4" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "portion": 0.5 }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

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

Remover Linha ​

Desfaz o vínculo de um lançamento com a conta (exige a permissão bill.split).

http
DELETE /v1/tours/user/bill-lines/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

Pagamentos ​

O pagamento é o registro manual de um recebimento sobre uma conta: dinheiro, cartão presente, transferência, voucher ou conta interna. Para dinheiro, tenderedAmount (valor entregue) e changeAmount (troco) fecham a conferência do caixa. O reference guarda o comprovante/NSU, e o tourCashSessionId vincula o recebimento à sessão de caixa aberta.

Quem recebeu é registrado em receivedByTourUserId (injetado). Estorno: lance um novo pagamento com amount negativo e refundedTourPaymentId apontando para o pagamento original — o approvedByTourUserId é injetado com o usuário autenticado, que atua como aprovador do estorno. Pagamentos aceitam clientRef como chave de idempotência offline. Como livro-razão, o registro não é editado depois de criado: a atualização permite apenas notes.

Listar Pagamentos ​

http
GET /v1/tours/user/payments

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 termo na referência (máx. 150 caracteres).
tourBillIdnumberNãoFiltra por conta.
methodenumNãocash, card_present, bank_transfer, instant_transfer, voucher, house_account ou other.
tourCashSessionIdnumberNãoFiltra por sessão de caixa.
fromstringNãoInício do período por receivedAt (ISO 8601).
tostringNãoFim do período por receivedAt (ISO 8601).
orderByenumNãoid, receivedAt, amount ou createdAt.
orderDirectionenumNãoasc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/payments?tourBillId=1&method=cash" \
  -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 pagamentos no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourBillId": 1,
      "tourCashSessionId": null,
      "method": "cash",
      "amount": "100.00",
      "tenderedAmount": null,
      "changeAmount": null,
      "reference": null,
      "receivedAt": "2026-10-07T11:56:15.561-03:00",
      "createdAt": "2026-10-07T11:56:15.562-03:00"
    }
  ]
}

Registrar Pagamento ​

Registra um recebimento sobre uma conta (exige a permissão payment.record). O receivedByTourUserId é injetado com o usuário autenticado; para estorno (amount negativo), o approvedByTourUserId também é injetado.

http
POST /v1/tours/user/payments

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourBillIdnumberSimConta paga.
methodenumSimcash, card_present, bank_transfer, instant_transfer, voucher, house_account ou other.
amountnumberSimValor recebido. Negativo indica estorno (exige refundedTourPaymentId).
clientRefstringNãoUUID gerado no dispositivo — chave de idempotência offline.
tenderedAmountnumberNãoValor entregue pelo cliente (dinheiro).
changeAmountnumberNãoTroco devolvido.
referencestringNãoComprovante, NSU ou identificador externo (máx. 100 caracteres).
tourCashSessionIdnumberNãoSessão de caixa do recebimento.
receivedAtstringNãoData/hora do recebimento em ISO 8601 (padrão: agora).
refundedTourPaymentIdnumberNãoPagamento original estornado (quando amount é negativo).
notesstringNãoObservações do pagamento.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/payments" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourBillId": 1,
    "method": "cash",
    "amount": 380,
    "tenderedAmount": 400,
    "changeAmount": 20,
    "receivedAt": "2026-10-07T14:00:00.000-03:00"
  }'

Respostas ​

201 Created

Retorna o ID do pagamento registrado.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando a conta não existe na instância ou o payload é inválido.

403 Forbidden

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

Obter Pagamento por ID ​

Recupera os detalhes de um pagamento, incluindo conta, recebedor, aprovador e pagamento estornado.

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

Respostas ​

200 OK

Retorna o pagamento com os relacionamentos.

json
{
  "id": 4,
  "tourId": 1,
  "tourBillId": 1,
  "tourCashSessionId": null,
  "receivedByTourUserId": 1,
  "refundedTourPaymentId": null,
  "approvedByTourUserId": null,
  "clientRef": null,
  "method": "cash",
  "amount": "380.00",
  "tenderedAmount": "400.00",
  "changeAmount": "20.00",
  "reference": null,
  "receivedAt": "2026-10-07T14:00:00.000-03:00",
  "notes": null,
  "createdAt": "2026-10-07T15:10:55.528-03:00",
  "receivedByTourUser": {
    "id": 1,
    "displayName": "Bruno Demo"
  },
  "approvedByTourUser": null,
  "refundedTourPayment": null,
  "toursBill": {
    "id": 1,
    "code": "EXKL89YTAP"
  }
}

404 Not Found

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

Atualizar Pagamento ​

Apenas as notes de um pagamento podem ser alteradas (exige a permissão payment.record) — valores, método e vínculos são imutáveis no livro-razão; correções são feitas por estorno.

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

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

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

Remover Pagamento ​

Remove o registro do pagamento (exige a permissão payment.record). A tabela de pagamentos é um livro-razão e não usa soft delete — prefira o estorno (amount negativo + refundedTourPaymentId) para manter a trilha de auditoria.

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

Respostas ​

204 No Content

Remoção concluída com sucesso.