Documentação de Reserva de Produto

Visão Geral

O módulo de Reserva de Produto permite garantir a disponibilidade de estoque para um cliente específico sem a necessidade de um pedido imediato.

Ao criar uma reserva, a quantidade reservada é imediatamente debitada do estoque disponível para venda, impedindo que o mesmo item seja vendido para outros clientes enquanto a reserva estiver ativa.

Existem dois tipos de reserva, identificados pelo campo type:

manual: criada diretamente via API ou painel administrativo. Pode ser gerenciada livremente enquanto estiver com status open.

order: criada automaticamente pelo sistema quando um pedido é realizado na loja. Não pode ser modificada manualmente.

Cada reserva pode estar em um dos três status possíveis, identificados pelo campo status:

open: reserva ativa — estoque está retido e os itens podem ser adicionados ou removidos.

completed: reserva finalizada/cumprida, geralmente vinculada a um pedido. O estoque foi consumido.

canceled: reserva cancelada — todo o estoque anteriormente reservado foi devolvido ao disponível.

O acesso ao módulo exige que o usuário autenticado possua o escopo de permissão RESERVE_READ para operações de leitura.

Para operações de escrita (criação, atualização, cancelamento e remoção de itens), o escopo RESERVE_WRITE também é obrigatório.

Entidades Envolvidas

Reserve: entidade principal que representa a reserva de estoque, contendo tipo, status, motivo, vínculos com cliente e usuário responsável, e os itens reservados.

ReserveItem: representa uma linha individual da reserva, associando um produto (productId) a um armazém específico (productStorageId) e a quantidade reservada (amount).

Customer: o cliente beneficiário da reserva, identificado pelo customerId. Deve ser um cliente válido e ativo na plataforma.

Storage: o armazém do qual o estoque é debitado no momento da reserva. Cada item da reserva especifica seu próprio armazém de origem.

Notas e Considerações

Somente reservas com status open aceitam adição ou remoção de itens.

Ao cancelar uma reserva, todo o estoque de todos os itens é devolvido ao estoque disponível imediatamente.

Reservas do tipo order (criadas automaticamente por pedidos) não podem ser modificadas manualmente via este módulo.

Se a criação de um ou mais itens falhar (por exemplo, por insuficiência de estoque), toda a operação de criação da reserva é revertida automaticamente.

Os campos reserveUserId, reserveUserName e reserveUserEmail são opcionais, mas interdependentes: se qualquer um deles for informado, os outros dois também são obrigatórios.

Listagem de Reservas

GET /products/reservations

Retorna a listagem de reservas de estoque com suporte a filtros e paginação.

Descrição

Este endpoint é destinado à consulta paginada das reservas de estoque criadas na plataforma.

As reservas de estoque podem ser de dois tipos:

Manual (manual): Criadas diretamente via painel ou API de reservas.
Pedido (order): Criadas automaticamente quando um pedido é realizado na loja.

A listagem suporta o padrão de busca avançada da plataforma, com filtros por status, tipo de reserva, cliente, usuário responsável e até por produto ou armazém em nível de item.

É possível combinar múltiplas condições para refinar os resultados conforme a necessidade.

Por padrão, a resposta não inclui os itens da reserva (items).

Para cada registro retornado, o array items estará ausente — os itens só estão disponíveis nos endpoints de detalhe, criação, atualização e cancelamento.

O campo reserveCustomer também não é retornado por padrão; para obtê-lo, solicite o field customer (veja a seção de campos disponíveis).

Dados sensíveis e mascaramento

Quando o field customer é solicitado, o objeto reserveCustomer é retornado com masked: true.

Isso significa que campos sensíveis do cliente — como e-mail, telefone e nome/razão social — são parcialmente ocultados para proteger os dados pessoais na listagem.

O acesso a este endpoint requer que o usuário autenticado possua o escopo de permissão RESERVE_READ.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

Campos Disponíveis (fields)

Os campos abaixo são opcionais e só são retornados quando explicitamente solicitados via fields. Por padrão, nenhum deles é incluído na resposta.

Campo	Descrição
`items`	Retorna os itens da reserva.
`customer`	Retorna as informações do cliente vinculado à reserva.

Campos de Condição Disponíveis

Campo	Tipo	Descrição
`id`	integer	ID único da reserva de estoque.
`status`	string	Status atual da reserva.
`type`	string	Tipo da reserva (`manual` ou `order`).
`customerId`	integer	ID único do cliente.
`customerName`	string	Nome ou Razão Social do cliente.
`customerEmail`	string	E-mail do cliente vinculado.
`orderId`	integer	ID do pedido que gerou a reserva (caso seja do tipo pedido).
`userId`	integer	ID do usuário administrativo que realizou a reserva.
`userName`	string	Nome do usuário administrativo.
`userEmail`	string	E-mail do usuário administrativo.
`productId`	integer	ID do produto presente nos itens da reserva.
`productStorageId`	integer	ID do estoque do produto presente nos itens da reserva.
`productName`	string	Nome do produto presente nos itens da reserva. Use com o operador `like` para busca parcial. Se o item for uma variação, também busca pelo nome do produto pai.

Ao filtrar por produto (productId, productStorageId ou productName), cada reserva aparece uma única vez, mesmo que vários itens dela atendam à condição.

Exemplo de condição buscando reservas com produtos cujo nome contém "camiseta":

1{
2  "field": "productName",
3  "value": "camiseta",
4  "operator": "like"
5}
{
  "field": "productName",
  "value": "camiseta",
  "operator": "like"
}

Campos de Ordenação Disponíveis

Campo	Descrição
`id`	ID da reserva.
`reason`	Motivo/Observação da reserva.
`userName`	Nome do usuário administrativo.
`userEmail`	E-mail do usuário administrativo.

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/reservations \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "items",
7      "customer"
8    ],
9    "conditions": {
10      "type": "AND",
11      "conditions": [
12        {
13          "field": "status",
14          "value": "open"
15        }
16      ]
17    },
18    "order": [
19      {
20        "field": "id",
21        "order": "desc"
22      }
23    ],
24    "limit": 10,
25    "offset": 0
26  }'
curl --request GET \
  --url {{MAIN_URL}}/products/reservations \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "fields": [
      "items",
      "customer"
    ],
    "conditions": {
      "type": "AND",
      "conditions": [
        {
          "field": "status",
          "value": "open"
        }
      ]
    },
    "order": [
      {
        "field": "id",
        "order": "desc"
      }
    ],
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 823,
7        "customerId": 4,
8        "orderId": null,
9        "type": "manual",
10        "status": "canceled",
11        "reason": "Reserva de teste",
12        "reserveCustomer": {
13          "id": 4,
14          "tradePolicyId": 3,
15          "email": "cli<strong></strong>@ex<strong></strong>",
16          "nameCorporateName": "Cli<strong></strong>plo",
17          "tradeName": "",
18          "phone": "+2798<strong></strong><em>-</em>*55",
19          "active": true,
20          "masked": true
21        },
22        "items": [
23          {
24            "id": 1329,
25            "productId": 3763,
26            "productStorageId": 1,
27            "amount": 2,
28            "saleWithoutStock": false
29          }
30        ],
31        "userId": 2,
32        "userName": "User",
33        "userEmail": "user@example.com",
34        "reserveUserId": null,
35        "reserveUserName": null,
36        "reserveUserEmail": null,
37        "cancelUserId": 2,
38        "cancelUserName": "User",
39        "cancelUserEmail": "user@example.com",
40        "createdAt": "2026-06-12 19:30:19",
41        "completedAt": null,
42        "canceledAt": "2026-06-12 16:32:55"
43      }
44    ],
45    "pagination": {
46      "limit": 10,
47      "offset": 0,
48      "pages": 1,
49      "registers": 1
50    }
51  }
52}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 823,
        "customerId": 4,
        "orderId": null,
        "type": "manual",
        "status": "canceled",
        "reason": "Reserva de teste",
        "reserveCustomer": {
          "id": 4,
          "tradePolicyId": 3,
          "email": "cli<strong></strong>@ex<strong></strong>",
          "nameCorporateName": "Cli<strong></strong>plo",
          "tradeName": "",
          "phone": "+2798<strong></strong><em>-</em>*55",
          "active": true,
          "masked": true
        },
        "items": [
          {
            "id": 1329,
            "productId": 3763,
            "productStorageId": 1,
            "amount": 2,
            "saleWithoutStock": false
          }
        ],
        "userId": 2,
        "userName": "User",
        "userEmail": "user@example.com",
        "reserveUserId": null,
        "reserveUserName": null,
        "reserveUserEmail": null,
        "cancelUserId": 2,
        "cancelUserName": "User",
        "cancelUserEmail": "user@example.com",
        "createdAt": "2026-06-12 19:30:19",
        "completedAt": null,
        "canceledAt": "2026-06-12 16:32:55"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 1
    }
  }
}

Detalhe de Reserva

GET /products/reservations/{reserveId}

Retorna o detalhe de uma reserva de estoque pelo seu ID.

Descrição

Este endpoint retorna o detalhe de uma única reserva de estoque identificada pelo reserveId.

Os campos items e customer são opcionais e só são retornados quando explicitamente solicitados via fields.

O acesso a este endpoint requer que o usuário autenticado possua o escopo de permissão RESERVE_READ.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

Parâmetros de Rota

Parâmetro	Tipo	Descrição
`reserveId`	integer	ID da reserva de estoque.

Campos Disponíveis (fields)

Os campos abaixo são opcionais e só são retornados quando explicitamente solicitados via fields.

Campo	Descrição
`items`	Retorna os itens da reserva.
`customer`	Retorna as informações do cliente vinculado à reserva.

Exemplo de Requisição — com fields

1curl --request GET \
2  --url {{MAIN_URL}}/products/reservations/123 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "items",
7      "customer"
8    ]
9  }'
curl --request GET \
  --url {{MAIN_URL}}/products/reservations/123 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "fields": [
      "items",
      "customer"
    ]
  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 823,
5    "customerId": 4,
6    "orderId": null,
7    "type": "manual",
8    "status": "canceled",
9    "reason": "Reserva de teste",
10    "reserveCustomer": {
11      "id": 4,
12      "tradePolicyId": 3,
13      "email": "cli<strong></strong>@ex<strong></strong>",
14      "nameCorporateName": "Cli<strong></strong>plo",
15      "tradeName": "",
16      "phone": "+2798<strong></strong><em>-</em>*55",
17      "active": true,
18      "masked": true
19    },
20    "items": [
21      {
22        "id": 1329,
23        "productId": 3763,
24        "productStorageId": 1,
25        "amount": 2,
26        "saleWithoutStock": false
27      }
28    ],
29    "userId": 2,
30    "userName": "User",
31    "userEmail": "user@example.com",
32    "reserveUserId": null,
33    "reserveUserName": null,
34    "reserveUserEmail": null,
35    "cancelUserId": 2,
36    "cancelUserName": "User",
37    "cancelUserEmail": "user@example.com",
38    "createdAt": "2026-06-12 19:30:19",
39    "completedAt": null,
40    "canceledAt": "2026-06-12 16:32:55"
41  }
42}
{
  "status": true,
  "data": {
    "id": 823,
    "customerId": 4,
    "orderId": null,
    "type": "manual",
    "status": "canceled",
    "reason": "Reserva de teste",
    "reserveCustomer": {
      "id": 4,
      "tradePolicyId": 3,
      "email": "cli<strong></strong>@ex<strong></strong>",
      "nameCorporateName": "Cli<strong></strong>plo",
      "tradeName": "",
      "phone": "+2798<strong></strong><em>-</em>*55",
      "active": true,
      "masked": true
    },
    "items": [
      {
        "id": 1329,
        "productId": 3763,
        "productStorageId": 1,
        "amount": 2,
        "saleWithoutStock": false
      }
    ],
    "userId": 2,
    "userName": "User",
    "userEmail": "user@example.com",
    "reserveUserId": null,
    "reserveUserName": null,
    "reserveUserEmail": null,
    "cancelUserId": 2,
    "cancelUserName": "User",
    "cancelUserEmail": "user@example.com",
    "createdAt": "2026-06-12 19:30:19",
    "completedAt": null,
    "canceledAt": "2026-06-12 16:32:55"
  }
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_RESERVE_NOT_FOUND	404	A reserva solicitada não foi encontrada.

Cadastro de Reserva

POST /products/reservations

Cria uma nova reserva de estoque do tipo manual para um cliente.

Descrição

Este endpoint permite a criação manual de uma reserva de estoque para um cliente específico.

Ao criar uma reserva, a plataforma garante que os produtos reservados sejam debitados do estoque disponível para venda, impedindo que o mesmo item seja vendido para outros clientes enquanto a reserva estiver ativa.

A reserva criada por este endpoint terá sempre o tipo manual e o status inicial open.

O campo orderId não é um parâmetro aceito neste endpoint — ele é gerenciado exclusivamente pelo sistema, sendo preenchido apenas em reservas do tipo order, geradas automaticamente por pedidos.

Itens da reserva

Os itens são opcionais na criação: é possível criar uma reserva sem nenhum item e adicioná-los posteriormente via endpoint de adição de itens.

O estoque de cada item é debitado imediatamente do armazém correspondente. Se qualquer item falhar — por exemplo, por insuficiência de estoque — toda a operação é revertida e a reserva não é criada.

Rastreabilidade de usuário externo

Os campos reserveUserId, reserveUserName e reserveUserEmail são opcionais e servem para identificar um usuário externo ou integração responsável pela solicitação da reserva.

Esses três campos são interdependentes: se qualquer um deles for informado, os outros dois também se tornam obrigatórios.

Para realizar esta operação, o usuário autenticado deve possuir os escopos de permissão RESERVE_READ e RESERVE_WRITE.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
customerId	integer	✅	ID do cliente para quem o estoque será reservado (mín. 1)
reason	string	❌	Motivo ou observação sobre a reserva (máx. 300 caracteres)
reserveUserId	integer	❌*	ID do usuário externo responsável pela reserva
reserveUserName	string	❌*	Nome do usuário externo (mín. 1, máx. 255 caracteres)
reserveUserEmail	string	❌*	E-mail do usuário externo (máx. 255 caracteres)
items	array	❌	Lista de itens a serem reservados (mín. 1 item se informado)
items.*.productId	integer	✅	ID do produto a ser reservado (mín. 1)
items.*.productStorageId	integer	✅	ID do armazém de onde o estoque será debitado (mín. 1)
items.*.amount	integer	✅	Quantidade a ser reservada (mín. 1)

\ Se qualquer um dos campos de usuário externo for informado, os outros dois também se tornam obrigatórios.*

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/reservations \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "customerId": 456,
6    "reason": "Reserva para cliente VIP - Showroom",
7    "reserveUserId": 10,
8    "reserveUserName": "Gerente Comercial",
9    "reserveUserEmail": "gerente@parceiro.com.br",
10    "items": [
11      {
12        "productId": 99,
13        "productStorageId": 2,
14        "amount": 5
15      }
16    ]
17  }'
curl --request POST \
  --url {{MAIN_URL}}/products/reservations \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "customerId": 456,
    "reason": "Reserva para cliente VIP - Showroom",
    "reserveUserId": 10,
    "reserveUserName": "Gerente Comercial",
    "reserveUserEmail": "gerente@parceiro.com.br",
    "items": [
      {
        "productId": 99,
        "productStorageId": 2,
        "amount": 5
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "id": 123,
3  "customerId": 456,
4  "customerName": "Cliente Exemplo Ltda",
5  "orderId": null,
6  "type": "manual",
7  "status": "open",
8  "reason": "Reserva para cliente VIP - Showroom",
9  "reserveCustomer": null,
10  "items": [
11    {
12      "id": 10,
13      "productId": 99,
14      "productStorageId": 2,
15      "amount": 5
16    }
17  ],
18  "userId": 1,
19  "userName": "Admin Usuario",
20  "userEmail": "admin@loja.com.br",
21  "reserveUserId": 10,
22  "reserveUserName": "Gerente Comercial",
23  "reserveUserEmail": "gerente@parceiro.com.br",
24  "cancelUserId": null,
25  "cancelUserName": null,
26  "cancelUserEmail": null,
27  "createdAt": "2026-04-23 10:15:00",
28  "completedAt": null,
29  "canceledAt": null
30}
{
  "id": 123,
  "customerId": 456,
  "customerName": "Cliente Exemplo Ltda",
  "orderId": null,
  "type": "manual",
  "status": "open",
  "reason": "Reserva para cliente VIP - Showroom",
  "reserveCustomer": null,
  "items": [
    {
      "id": 10,
      "productId": 99,
      "productStorageId": 2,
      "amount": 5
    }
  ],
  "userId": 1,
  "userName": "Admin Usuario",
  "userEmail": "admin@loja.com.br",
  "reserveUserId": 10,
  "reserveUserName": "Gerente Comercial",
  "reserveUserEmail": "gerente@parceiro.com.br",
  "cancelUserId": null,
  "cancelUserName": null,
  "cancelUserEmail": null,
  "createdAt": "2026-04-23 10:15:00",
  "completedAt": null,
  "canceledAt": null
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_ENTITY_NOT_FOUND	404	A entidade solicitada não foi encontrada.
UAPPI_STORE_STOCK_INSUFFICIENT_RESERVED_STOCK	400	A quantidade solicitada para a operação de reserva de estoque não está disponível.
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.

Atualização de Reserva

PUT /products/reservations/{reserveId}

Atualiza os dados de uma reserva de estoque pelo seu ID.

Descrição

Este endpoint permite a atualização dos dados editáveis de uma reserva de estoque.

Atualmente, o campo passível de edição é o reason (motivo ou observação associada à reserva).

A atualização não altera o status, os itens nem o tipo da reserva.

Para gerenciar os itens reservados, utilize os endpoints específicos de adição e remoção de itens.

Para alterar o status, utilize o endpoint de cancelamento.

A resposta inclui o objeto completo da reserva atualizada com todos os seus campos e o array items com os itens vinculados. O campo reserveCustomer não é retornado neste endpoint.

Para realizar esta operação, o usuário autenticado deve possuir os escopos de permissão RESERVE_READ e RESERVE_WRITE.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
reserveId	integer	Sim	ID único da reserva a ser atualizada

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
reason	string	❌	Motivo ou observação sobre a reserva (máx. 300 caracteres)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/reservations/123 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "reason": "Reserva ajustada - cliente confirmou retirada para semana que vem"
6  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/reservations/123 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "reason": "Reserva ajustada - cliente confirmou retirada para semana que vem"
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 123,
3  "customerId": 456,
4  "customerName": "Cliente Exemplo Ltda",
5  "orderId": null,
6  "type": "manual",
7  "status": "open",
8  "reason": "Reserva ajustada - cliente confirmou retirada para semana que vem",
9  "reserveCustomer": null,
10  "items": [
11    {
12      "id": 10,
13      "productId": 99,
14      "productStorageId": 2,
15      "amount": 5
16    }
17  ],
18  "userId": 1,
19  "userName": "Admin Usuario",
20  "userEmail": "admin@loja.com.br",
21  "reserveUserId": null,
22  "reserveUserName": null,
23  "reserveUserEmail": null,
24  "cancelUserId": null,
25  "cancelUserName": null,
26  "cancelUserEmail": null,
27  "createdAt": "2026-04-23 10:00:00",
28  "completedAt": null,
29  "canceledAt": null
30}
{
  "id": 123,
  "customerId": 456,
  "customerName": "Cliente Exemplo Ltda",
  "orderId": null,
  "type": "manual",
  "status": "open",
  "reason": "Reserva ajustada - cliente confirmou retirada para semana que vem",
  "reserveCustomer": null,
  "items": [
    {
      "id": 10,
      "productId": 99,
      "productStorageId": 2,
      "amount": 5
    }
  ],
  "userId": 1,
  "userName": "Admin Usuario",
  "userEmail": "admin@loja.com.br",
  "reserveUserId": null,
  "reserveUserName": null,
  "reserveUserEmail": null,
  "cancelUserId": null,
  "cancelUserName": null,
  "cancelUserEmail": null,
  "createdAt": "2026-04-23 10:00:00",
  "completedAt": null,
  "canceledAt": null
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_RESERVE_NOT_FOUND	404	A reserva solicitada não foi encontrada.

Adição de Itens à Reserva

POST /products/reservations/{reserveId}/items

Adiciona itens a uma reserva de estoque aberta e retorna todos os itens vinculados à reserva.

Descrição

Este endpoint permite adicionar um ou mais itens a uma reserva de estoque existente.

Cada item informado representa um produto em um armazém específico (productStorageId) com uma quantidade a ser reservada (amount).

Antes de inserir os itens, o sistema valida se a reserva identificada por reserveId existe e se seu status atual é OPEN (aberta).

Reservas que já foram finalizadas ou canceladas não aceitam novos itens — qualquer tentativa resultará em erro de conflito.

Para cada item informado, o sistema executa a reserva de estoque correspondente: a quantidade solicitada é debitada do estoque disponível do armazém e alocada como estoque reservado.

Caso o estoque disponível seja insuficiente para qualquer um dos itens, toda a operação é interrompida com erro.

Após a inserção bem-sucedida, a resposta retorna todos os itens da reserva — incluindo os anteriormente cadastrados e os recém-adicionados — e não apenas os itens enviados na requisição atual.

O corpo da requisição com a chave items é opcional: se omitido, o endpoint executa sem erros e devolve os itens já existentes na reserva. Quando informado, o array deve conter ao menos um elemento.

O acesso a este recurso exige autenticação e dois escopos de permissão:

RESERVE_READ, necessário para acessar o grupo de rotas de reservas

RESERVE_WRITE, necessário para executar operações de escrita sobre a reserva.

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
reserveId	integer	Sim	ID único da reserva de estoque

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
items	array	❌	Lista de itens a adicionar à reserva (mín. 1 elemento quando presente)
items.*.productId	integer	✅	ID do produto a ser reservado (mín. 1)
items.*.productStorageId	integer	✅	ID do armazém de onde o estoque será reservado (mín. 1)
items.*.amount	integer	✅	Quantidade a reservar (mín. 1)

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/reservations/42/items \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "items": [
6      {
7        "productId": 101,
8        "productStorageId": 5,
9        "amount": 3
10      },
11      {
12        "productId": 202,
13        "productStorageId": 5,
14        "amount": 1
15      }
16    ]
17  }'
curl --request POST \
  --url {{MAIN_URL}}/products/reservations/42/items \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "items": [
      {
        "productId": 101,
        "productStorageId": 5,
        "amount": 3
      },
      {
        "productId": 202,
        "productStorageId": 5,
        "amount": 1
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1[
2  {
3    "id": 1,
4    "productId": 101,
5    "productStorageId": 5,
6    "amount": 3
7  },
8  {
9    "id": 2,
10    "productId": 202,
11    "productStorageId": 5,
12    "amount": 1
13  }
14]
[
  {
    "id": 1,
    "productId": 101,
    "productStorageId": 5,
    "amount": 3
  },
  {
    "id": 2,
    "productId": 202,
    "productStorageId": 5,
    "amount": 1
  }
]

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_RESERVE_NOT_FOUND	404	A reserva solicitada não foi encontrada.
UAPPI_STORE_RESERVE_ALREADY_FINISHED	409	Não é possível realizar a operação pois a reserva já foi finalizada.
UAPPI_STORE_STOCK_INSUFFICIENT_RESERVED_STOCK	400	A quantidade solicitada para a operação de reserva de estoque não está disponível.
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.

Remoção de Itens de Reserva

DELETE /products/reservations/{reserveId}/items

Remove um ou mais itens de uma reserva de estoque e libera as quantidades de volta ao estoque disponível.

Descrição

Este endpoint permite a remoção de itens de uma reserva de estoque.

Cada item removido tem sua quantidade reservada devolvida imediatamente ao estoque disponível para venda no armazém correspondente.

A operação só é permitida em reservas com status open.

O array items do corpo da requisição deve conter os IDs dos itens da reserva (campo id do ReserveItemDMC), e não IDs de produtos.

Se nenhum item for informado (campo items omitido), o endpoint executa com sucesso e retorna um array vazio.

A resposta contém apenas um array de inteiros representando os IDs dos itens que foram removidos, confirmando quais itens foram processados.

Após a remoção, os itens são permanentemente excluídos da reserva.

Para realizar esta operação, o usuário autenticado deve possuir os escopos de permissão RESERVE_READ e RESERVE_WRITE.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
reserveId	integer	Sim	ID único da reserva da qual os itens serão removidos

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
items	array	❌	Lista de IDs de itens da reserva a serem removidos (mín. 1 elemento se informado)
items.*	integer	✅	ID do item da reserva

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/reservations/123/items \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "items": [10, 11, 12]
6  }'
curl --request DELETE \
  --url {{MAIN_URL}}/products/reservations/123/items \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "items": [10, 11, 12]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1[10, 11, 12]
[10, 11, 12]

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_RESERVE_NOT_FOUND	404	A reserva solicitada não foi encontrada.
UAPPI_STORE_RESERVE_ALREADY_FINISHED	409	Não é possível executar a ação pois a reserva já foi finalizada.

Cancelamento de Reserva

PUT /products/reservations/{reserveId}/cancel

Cancela uma reserva de estoque e libera o estoque retido de volta ao disponível.

Descrição

Este endpoint realiza o cancelamento de uma reserva de estoque previamente criada.

Ao cancelar, o status da reserva é alterado para canceled e todo o estoque de todos os itens vinculados é devolvido ao estoque disponível para venda, de forma imediata e automática.

Somente reservas com status open podem ser canceladas. Tentativas de cancelar uma reserva que já foi finalizada ou cancelada anteriormente resultarão em erro.

Após o cancelamento, a reserva torna-se somente leitura — não é possível adicionar, remover itens ou alterar qualquer dado da reserva.

Os campos cancelUserId, cancelUserName e cancelUserEmail são preenchidos automaticamente com as informações do usuário autenticado que executou o cancelamento, garantindo a rastreabilidade da operação.

Para realizar esta operação, o usuário autenticado deve possuir os escopos de permissão RESERVE_READ e RESERVE_WRITE.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
reserveId	integer	Sim	ID único da reserva a ser cancelada

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/reservations/123/cancel \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"
curl --request PUT \
  --url {{MAIN_URL}}/products/reservations/123/cancel \
  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 123,
3  "customerId": 456,
4  "customerName": "Cliente Exemplo Ltda",
5  "orderId": null,
6  "type": "manual",
7  "status": "canceled",
8  "reason": "Reserva para evento promocional",
9  "reserveCustomer": null,
10  "items": [
11    {
12      "id": 10,
13      "productId": 99,
14      "productStorageId": 2,
15      "amount": 5
16    }
17  ],
18  "userId": 1,
19  "userName": "Admin Usuario",
20  "userEmail": "admin@loja.com.br",
21  "reserveUserId": null,
22  "reserveUserName": null,
23  "reserveUserEmail": null,
24  "cancelUserId": 1,
25  "cancelUserName": "Admin Usuario",
26  "cancelUserEmail": "admin@loja.com.br",
27  "createdAt": "2026-04-23 10:00:00",
28  "completedAt": null,
29  "canceledAt": "2026-04-25 14:30:00"
30}
{
  "id": 123,
  "customerId": 456,
  "customerName": "Cliente Exemplo Ltda",
  "orderId": null,
  "type": "manual",
  "status": "canceled",
  "reason": "Reserva para evento promocional",
  "reserveCustomer": null,
  "items": [
    {
      "id": 10,
      "productId": 99,
      "productStorageId": 2,
      "amount": 5
    }
  ],
  "userId": 1,
  "userName": "Admin Usuario",
  "userEmail": "admin@loja.com.br",
  "reserveUserId": null,
  "reserveUserName": null,
  "reserveUserEmail": null,
  "cancelUserId": 1,
  "cancelUserName": "Admin Usuario",
  "cancelUserEmail": "admin@loja.com.br",
  "createdAt": "2026-04-23 10:00:00",
  "completedAt": null,
  "canceledAt": "2026-04-25 14:30:00"
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_RESERVE_NOT_FOUND	404	A reserva solicitada não foi encontrada.
UAPPI_STORE_RESERVE_ALREADY_FINISHED	409	Não é possível executar a ação pois a reserva já foi finalizada.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Documentação de Reserva de Produto

Visão Geral

Entidades Envolvidas

Notas e Considerações

Listagem de Reservas

Descrição

Parâmetros

Headers Obrigatórios

Campos Disponíveis (fields)

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

✅ Resposta de Sucesso

Detalhe de Reserva

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros de Rota

Campos Disponíveis (fields)

Exemplo de Requisição — com fields

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Cadastro de Reserva

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros: