Entrar
Documentação

Desenvolvedores

Estoque

Consulte, some, troque e apague linhas de estoque.

Todas as rotas desta página exigem a permissão PROMISSE_INVENTORY.

As mesmas quatro operações existem para produto e para variante:

Alvo Caminho
Produto /product/stock/:id
Variante /product/variant/stock/:id

O id do corpo precisa ser igual ao da URL. Se for diferente, a resposta é 400 id_mismatch.

Consultar#

Texto
GET /product/stock/:id?page=1&limit=500

limit vai até 1000, com padrão 500. Cada leitura fica registrada na auditoria da loja, porque o estoque é o conteúdo que você vende.

Terminal
curl "https://api.promisse.store/api/v1/product/stock/UUID_DO_PRODUTO?limit=100" \
  -H "x-api-key: $PROMISSE_KEY"

No produto, cada item traz id e estoque. Na variante, vem a linha completa.

JSON
{
  "estoque": [{ "id": "uuid", "estoque": "CHAVE-001" }],
  "total": 1,
  "page": 1,
  "limit": 100
}

Somar#

Texto
POST /product/stock/:id

Aceita até 5000 itens por chamada.

Terminal
curl -X POST "https://api.promisse.store/api/v1/product/stock/UUID_DO_PRODUTO" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{ "id": "UUID_DO_PRODUTO", "stock": ["CHAVE-003", "CHAVE-004"] }'
JSON
{ "estoques": [], "total": 12, "added": 2, "duplicated": 0 }

total é o estoque livre depois de somar. A linha completa traz id, produto, tipo (só em variante, com o valor "variante"), estoque, pos, createdAt e updatedAt.

Substituir#

Texto
PUT /product/stock/:id

Troca só as linhas livres pela lista enviada. A resposta traz estoques, added, duplicated e removed.

Lista vazia é recusada com 400. Para zerar o estoque, use o DELETE.

Apagar#

Texto
DELETE /product/stock/:id

Aceita até 1000 IDs por chamada.

Terminal
curl -X DELETE "https://api.promisse.store/api/v1/product/stock/UUID_DO_PRODUTO" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{ "id": "UUID_DO_PRODUTO", "stockIds": ["UUID_DA_LINHA"] }'
JSON
{ "message": "Itens de estoque removidos", "total": 1 }

Se nenhuma linha livre tiver esses IDs, a resposta é 404.

Regras do estoque#

  • Linha reservada ou vendida nunca é apagada.
  • Chave que já existiu no produto, mesmo vendida, não entra de novo. Ela conta em duplicated.
  • Repetidos na mesma chamada também são ignorados.