A API pública cuida de catálogo, estoque, vendas, entrega, bots e tags. Ela responde em JSON, e tudo é escopado pela chave: nenhuma rota aceita ID de loja, e um ID de outra loja responde 404, como se não existisse.

Endereço#

Texto

https://api.promisse.store/api/v1

Datas vêm em ISO 8601, em UTC. Os IDs são UUID em todo lugar.

Autenticação#

Envie a chave de API no cabeçalho x-api-key:

Terminal

curl "https://api.promisse.store/api/v1/product/catalog?type=products&limit=5" \
  -H "x-api-key: $PROMISSE_KEY"

Permissões#

Cada rota exige uma permissão, indicada nas páginas de referência. PROMISSE_ADMIN dá acesso a todas.

Página	Permissão
Catálogo	`PROMISSE_CATALOG`
Estoque	`PROMISSE_INVENTORY`
Vendas	`PROMISSE_SALES`
Entrega	`PROMISSE_INVENTORY`
Bots de suporte	`PROMISSE_BOT`
Tags	`PROMISSE_TAGS`

Limites#

Os limites são contados por chave, não por IP. Trocar de IP não libera nada, e várias chaves atrás do mesmo IP não disputam a mesma cota.

Rotas	Limite
`POST` e `PUT /delivery/stock`, somadas	1 requisição a cada 2 segundos
Todas as demais, somadas	60 por minuto

As respostas trazem os cabeçalhos x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset. Ao passar do limite, a resposta é 429 com retry-after em segundos.

Quem erra a chave repetidamente é limitado por IP, em 30 tentativas por minuto.

Valores#

A API usa reais em decimal, nunca centavos.

Tipo	Regra
Dinheiro	Número ou texto, como `19.99` ou `"19.99"`. Até 2 casas e no máximo `100000000.00`.
Recusado	Mais de 2 casas (`0.001`), negativo, notação científica fora do teto (`1e9`), `null`, booleano e lista respondem `400 invalid_amount`.
`affiliate_fee`	Porcentagem de 0 a 100, com até 2 casas, como `12.5`. Fora disso responde `400 invalid_percent`.
Limpar um campo	`compare_price: null` e `affiliate_fee: null` limpam o valor.
Estoque ilimitado	`quantity: null` significa sem limite.

Erros#

Todo erro tem uma mensagem pronta para mostrar e um código estável para o seu sistema comparar:

JSON

{ "error": "Mensagem pronta para o usuário", "code": "codigo_estavel" }

Status	Quando
`400`	Dado inválido. Falha de formato vem com `code: "validation"` e `details`. Campo não declarado também é recusado.
`401`	Sem chave, chave inválida, revogada ou vencida, ou loja suspensa.
`403`	A chave não tem a permissão da rota.
`404`	Não existe, ou é de outra loja. As duas situações respondem igual.
`409`	Conflito de estado. Cada rota lista os códigos.
`429`	Limite de requisições, com `code: "rate_limited"`.

Referência#

Catálogo Consulta, categorias, produtos e variantes.
Estoque Consultar, somar, trocar e apagar linhas.
Vendas e entrega Consultar pedidos e entregar conteúdo.
Bots de suporte Criar bots e responder nos chats.
Tags Marcar produtos, variantes e categorias.