Basis

Appearance

Estoque ​

O estoque controla os insumos (stock_items) consumidos pelas vendas do POS — via revenda direta ou ficha técnica — em um ou mais locais (stock_locations). O saldo de cada item em cada local fica em stock_levels, e toda variação passa pelo livro-razão (stock_movements), que registra compras, consumos, transferências, ajustes, perdas e produções com custo e rastreabilidade.

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).

Permissões de escrita

As mutações de insumos, saldos e movimentações exigem a permissão stock.adjust. As mutações de locais de estoque exigem settings.manage. Sem a permissão, a API responde 403 com code: FORBIDDEN. As consultas (GET) não exigem permissão adicional.

Insumos (Stock Items) ​

O que se compra, armazena e consome: garrafa de rum, pão de hambúrguer, toalha de praia. Cada insumo tem unidade de medida própria (ver Catálogo), fornecedor padrão e níveis de reposição — minQuantity (ponto de alerta) e parQuantity (nível ideal).

Os campos averageCost (custo médio ponderado) e lastCost (custo da última compra) são calculados pela API a partir das movimentações de entrada — não são editáveis.

Listar Insumos ​

http
GET /v1/tours/user/stock-items

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.
tourSupplierIdnumberNãoFiltra por fornecedor padrão.
isActivebooleanNãoFiltra por insumos ativos/inativos.
orderByenumNãoid, code, name ou createdAt (padrão: id).
orderDirectionenumNãoasc ou desc (padrão: desc).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/stock-items?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 insumos no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourMeasurementUnitId": 1,
      "tourSupplierId": 1,
      "code": "RLSRFO50",
      "name": "Bespoke Wooden Bike",
      "averageCost": "0.00",
      "lastCost": "0.00",
      "minQuantity": "0.0000",
      "parQuantity": null,
      "isActive": true,
      "createdAt": "2026-10-07T11:56:15.031-03:00",
      "updatedAt": "2026-10-07T11:56:15.031-03:00"
    }
  ]
}

Criar Insumo ​

http
POST /v1/tours/user/stock-items

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo único na instância (máx. 50 caracteres).
namestringSimNome do insumo (máx. 150 caracteres).
tourMeasurementUnitIdnumberSimUnidade de medida do insumo.
tourSupplierIdnumberNãoFornecedor padrão usado nas compras.
minQuantitynumberNãoEstoque mínimo — ponto de alerta de reposição (mínimo: 0).
parQuantitynumberNãoNível ideal de estoque (mínimo: 0).
isActivebooleanNãoIndica se já nasce ativo (padrão: true).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/stock-items" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DOC-ITEM-1",
    "name": "Insumo Doc",
    "tourMeasurementUnitId": 1,
    "tourSupplierId": 1,
    "minQuantity": 5,
    "parQuantity": 20,
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID do insumo criado.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o code já existe na instância ou a unidade de medida/fornecedor não existe.

Listar para Dropdown ​

http
GET /v1/tours/user/stock-items/list

Aceita search, isActive e limit como filtros opcionais de query.

Respostas ​

200 OK

json
[
  {
    "value": 1,
    "label": "Bespoke Wooden Bike"
  },
  {
    "value": 4,
    "label": "Insumo Doc"
  }
]

Obter Insumo por ID ​

http
GET /v1/tours/user/stock-items/:id

Respostas ​

200 OK

Retorna o insumo com unidade de medida e fornecedor padrão resolvidos.

json
{
  "id": 4,
  "tourId": 1,
  "tourMeasurementUnitId": 1,
  "tourSupplierId": 1,
  "code": "DOC-ITEM-1",
  "name": "Insumo Doc",
  "averageCost": "0.00",
  "lastCost": "0.00",
  "minQuantity": "5.0000",
  "parQuantity": "20.0000",
  "isActive": true,
  "createdAt": "2026-10-07T15:11:10.134-03:00",
  "updatedAt": "2026-10-07T15:11:10.134-03:00",
  "toursMeasurementUnit": {
    "id": 1,
    "code": "IFH2PUIH",
    "name": "Bronze"
  },
  "toursSupplier": {
    "id": 1,
    "name": "Ward - Pouros"
  }
}

404 Not Found

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

Atualizar Insumo ​

http
PUT /v1/tours/user/stock-items/:id

Aceita os mesmos campos da criação, todos opcionais. averageCost e lastCost não são editáveis.

Respostas ​

204 No Content

Atualização concluída com sucesso.

Remover Insumo ​

http
DELETE /v1/tours/user/stock-items/:id

Respostas ​

204 No Content

Remoção concluída via soft delete.

Locais de Estoque ​

Os pontos físicos onde o insumo fica: depósito, cozinha, bar, quiosque. O local com isDefault: true é usado como origem padrão nas baixas automáticas de venda.

Listar Locais de Estoque ​

http
GET /v1/tours/user/stock-locations

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.
isDefaultbooleanNãoFiltra pelo local padrão.
isActivebooleanNãoFiltra por locais ativos/inativos.
orderByenumNãoid, code, name ou createdAt (padrão: id).
orderDirectionenumNãoasc ou desc (padrão: desc).

Respostas ​

200 OK

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "code": "TI3KEITS",
      "name": "4224 Rempel Keys",
      "isDefault": false,
      "isActive": true,
      "createdAt": "2026-10-07T11:56:15.004-03:00",
      "updatedAt": "2026-10-07T11:56:15.004-03:00"
    }
  ]
}

Criar Local de Estoque ​

http
POST /v1/tours/user/stock-locations

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringSimCódigo único na instância (máx. 50 caracteres).
namestringSimNome do local (máx. 150 caracteres).
isDefaultbooleanNãoMarca o local como padrão das baixas de venda.
isActivebooleanNãoIndica se já nasce ativo (padrão: true).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/stock-locations" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "doc-cozinha",
    "name": "Cozinha Doc",
    "isDefault": false,
    "isActive": true
  }'

Respostas ​

201 Created

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o code já existe na instância.

Listar para Dropdown ​

http
GET /v1/tours/user/stock-locations/list

Aceita search, isActive e limit como filtros opcionais de query.

Respostas ​

200 OK

json
[
  {
    "value": 1,
    "label": "4224 Rempel Keys"
  },
  {
    "value": 4,
    "label": "Cozinha Doc"
  }
]

Obter Local de Estoque por ID ​

http
GET /v1/tours/user/stock-locations/:id

Respostas ​

200 OK

json
{
  "id": 4,
  "tourId": 1,
  "code": "doc-cozinha",
  "name": "Cozinha Doc",
  "isDefault": false,
  "isActive": true,
  "createdAt": "2026-10-07T15:11:12.182-03:00",
  "updatedAt": "2026-10-07T15:11:12.182-03:00"
}

404 Not Found

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

Atualizar Local de Estoque ​

http
PUT /v1/tours/user/stock-locations/:id

Aceita os mesmos campos da criação, todos opcionais.

Respostas ​

204 No Content

Atualização concluída com sucesso.

Remover Local de Estoque ​

http
DELETE /v1/tours/user/stock-locations/:id

Respostas ​

204 No Content

Remoção concluída via soft delete.

Saldos (Stock Levels) ​

O saldo de cada insumo em cada local — a grade item × local. quantity é o estoque físico; reservedQuantity é a parcela reservada (por exemplo, para eventos confirmados) e não fica disponível para venda. Os saldos são atualizados automaticamente pelas movimentações; o cadastro manual serve para a carga inicial e acertos de inventário.

Listar Saldos ​

http
GET /v1/tours/user/stock-levels

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).
tourStockItemIdnumberNãoFiltra por insumo.
tourStockLocationIdnumberNãoFiltra por local de estoque.
orderByenumNãoid, quantity ou updatedAt (padrão: id).
orderDirectionenumNãoasc ou desc (padrão: desc).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/stock-levels?tourStockItemId=1" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourStockItemId": 1,
      "tourStockLocationId": 1,
      "quantity": "10.0000",
      "reservedQuantity": "0.0000",
      "updatedAt": "2026-10-07T11:56:15.164-03:00"
    }
  ]
}

Criar Saldo ​

Registra o saldo inicial de um insumo em um local (carga inicial).

http
POST /v1/tours/user/stock-levels

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourStockItemIdnumberSimInsumo.
tourStockLocationIdnumberSimLocal de estoque.
quantitynumberNãoSaldo físico inicial (padrão: 0).
reservedQuantitynumberNãoQuantidade reservada inicial (padrão: 0).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/stock-levels" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourStockItemId": 1,
    "tourStockLocationId": 1,
    "quantity": 100,
    "reservedQuantity": 0
  }'

Respostas ​

201 Created

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o insumo ou o local não existe na instância.

Obter Saldo por ID ​

http
GET /v1/tours/user/stock-levels/:id

Respostas ​

200 OK

Retorna o saldo com insumo e local resolvidos.

json
{
  "id": 4,
  "tourId": 1,
  "tourStockItemId": 1,
  "tourStockLocationId": 1,
  "quantity": "100.0000",
  "reservedQuantity": "0.0000",
  "updatedAt": "2026-10-07T15:11:11.025-03:00",
  "toursStockLocation": {
    "id": 1,
    "code": "TI3KEITS",
    "name": "4224 Rempel Keys"
  },
  "toursStockItem": {
    "id": 1,
    "code": "RLSRFO50",
    "name": "Bespoke Wooden Bike"
  }
}

404 Not Found

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

Atualizar Saldo ​

Ajuste direto de inventário sobre um par item × local já cadastrado.

http
PUT /v1/tours/user/stock-levels/:id

Payload (Body) ​

AtributoTipoObrigatórioDescrição
quantitynumberNãoNovo saldo físico.
reservedQuantitynumberNãoNova quantidade reservada.

Respostas ​

204 No Content

Atualização concluída com sucesso.

Ajuste vs. movimentação

Para acertos com rastreabilidade (quem, quando e por quê), prefira registrar uma movimentação do tipo adjustment em vez de editar o saldo diretamente.

Remover Saldo ​

http
DELETE /v1/tours/user/stock-levels/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

Movimentações de Estoque ​

O livro-razão do estoque: toda entrada e saída de insumo vira um registro imutável de movimentação, alimentando os saldos e os custos (averageCost/lastCost) do insumo. Como todo livro-razão do módulo, correções são feitas por estorno (nova movimentação com sinal oposto), nunca por edição de valores.

Regras do registro:

  • quantityDelta positivo = entrada, negativo = saída. Uma compra de 50 unidades é 50; o consumo de 2 é -2.
  • createdByTourUserId é injetado pela API com o usuário staff autenticado — não é aceito no payload.
  • Rastreabilidade opcional: tourOrderItemId vincula o consumo ao item de pedido do POS que o originou; tourSupplierId identifica o fornecedor de uma compra.
  • Se occurredAt for omitido, a API usa o momento do registro.

Tipos de movimentação (kind):

KindSentido típicoUso
purchaseentradaCompra de insumos de fornecedor.
consumptionsaídaBaixa por venda (revenda direta ou ficha técnica).
transfer_inentradaRecebimento de transferência entre locais.
transfer_outsaídaEnvio de transferência entre locais.
adjustmentambosAcerto de inventário (contagem física).
wastesaídaPerda, quebra ou validade vencida.
productionentradaEntrada de produção interna (pré-preparo).
returnsaídaDevolução de insumo ao fornecedor.

Listar Movimentações ​

http
GET /v1/tours/user/stock-movements

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).
tourStockItemIdnumberNãoFiltra por insumo.
tourStockLocationIdnumberNãoFiltra por local de estoque.
kindenumNãoFiltra por tipo de movimentação (ver tabela acima).
fromdateNãoInício do período, em ISO 8601 (occurredAt).
todateNãoFim do período, em ISO 8601 (occurredAt).
orderByenumNãoid, occurredAt ou createdAt (padrão: id).
orderDirectionenumNãoasc ou desc (padrão: desc).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/stock-movements?kind=purchase&from=2026-10-01" \
  -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 movimentações com o insumo resolvido em toursStockItem.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "tourStockItemId": 1,
      "tourStockLocationId": 1,
      "kind": "purchase",
      "quantityDelta": "5.0000",
      "unitCost": "10.00",
      "totalCost": "50.00",
      "occurredAt": "2026-10-07T11:56:15.388-03:00",
      "createdAt": "2026-10-07T11:56:15.388-03:00",
      "toursStockItem": {
        "id": 1,
        "code": "RLSRFO50",
        "name": "Bespoke Wooden Bike"
      }
    }
  ]
}

Registrar Movimentação ​

Lança uma entrada ou saída manual — compra, ajuste de inventário, perda, transferência. A movimentação atualiza o saldo do par item × local e, nas entradas com custo, recalcula lastCost e averageCost do insumo.

http
POST /v1/tours/user/stock-movements

Payload (Body) ​

AtributoTipoObrigatórioDescrição
tourStockItemIdnumberSimInsumo movimentado.
tourStockLocationIdnumberSimLocal da movimentação.
kindenumSimTipo da movimentação (ver tabela acima).
quantityDeltanumberSimVariação de quantidade — positivo = entrada, negativo = saída.
unitCostnumberNãoCusto unitário da entrada, na moeda da instância.
totalCostnumberNãoCusto total da movimentação, na moeda da instância.
tourOrderItemIdnumberNãoItem de pedido do POS que originou o consumo (rastreabilidade).
tourSupplierIdnumberNãoFornecedor da compra (rastreabilidade).
reasonstringNãoMotivo/observação do lançamento.
occurredAtdateNãoData/hora do fato, em ISO 8601 (padrão: momento do registro).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/stock-movements" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tourStockItemId": 1,
    "tourStockLocationId": 1,
    "kind": "purchase",
    "quantityDelta": 50,
    "unitCost": 12.5,
    "reason": "Compra doc",
    "occurredAt": "2026-10-20T14:00:00.000-03:00"
  }'

Respostas ​

201 Created

Retorna o ID da movimentação registrada.

json
{
  "id": 4
}

422 Unprocessable Entity

Ocorre quando o insumo, o local, o item de pedido ou o fornecedor não existe na instância.

Obter Movimentação por ID ​

http
GET /v1/tours/user/stock-movements/:id

Respostas ​

200 OK

Retorna a movimentação completa, incluindo createdByTourUserId (injetado pela API) e os vínculos de rastreabilidade.

json
{
  "id": 4,
  "tourId": 1,
  "tourStockItemId": 1,
  "tourStockLocationId": 1,
  "tourOrderItemId": null,
  "tourSupplierId": null,
  "createdByTourUserId": 1,
  "kind": "purchase",
  "quantityDelta": "50.0000",
  "unitCost": "12.50",
  "totalCost": "0.00",
  "reason": "Compra doc",
  "occurredAt": "2026-10-20T14:00:00.000-03:00",
  "createdAt": "2026-10-07T15:11:13.283-03:00",
  "toursStockItem": {
    "id": 1,
    "code": "RLSRFO50",
    "name": "Bespoke Wooden Bike"
  }
}

404 Not Found

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

Atualizar Movimentação ​

Somente o campo reason pode ser corrigido — quantidades, custos e vínculos são imutáveis. Para corrigir valores, lance um estorno.

http
PUT /v1/tours/user/stock-movements/:id

Payload (Body) ​

AtributoTipoObrigatórioDescrição
reasonstringNãoNovo motivo/observação do lançamento.

Respostas ​

204 No Content

Atualização concluída com sucesso.

Remover Movimentação ​

http
DELETE /v1/tours/user/stock-movements/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

Prefira o estorno

Livros-razão existem para auditoria: remover um lançamento apaga o rastro do fato. A correção recomendada é registrar uma nova movimentação com quantityDelta de sinal oposto (estorno), preservando o histórico completo.