Entrar
Documentação

Desenvolvedores

Catálogo

Consulte e mantenha categorias, produtos e variantes.

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

Texto
GET /product/catalog
Parâmetro Valores Padrão
type all, category, products, variants all
category UUID da categoria, incluindo as subcategorias
search Busca pelo nome
page A partir de 1 1
limit Até 100 50
Terminal
curl "https://api.promisse.store/api/v1/product/catalog?type=products&search=curso&limit=20" \
  -H "x-api-key: $PROMISSE_KEY"

O formato da resposta depende de type:

type Resposta Paginação
all categories, uncategorized, pagination Por produto. A árvore de categorias vem inteira em toda página, e cada nó traz os produtos daquela página. Com search, categorias sem resultado saem da árvore.
category categories, pagination Por categoria raiz, sem os produtos.
products categories: [], products, pagination Por produto.
variants categories: [], variants, pagination Por variante.

pagination traz page, limit, total e total_pages.

Objetos#

Categoria:

JSON
{
  "id": "uuid", "name": "Cursos", "slug": "cursos", "icon": null, "banner": null, "position": 1,
  "parent_category": null, "is_private": false, "created_at": "...", "updated_at": "...",
  "products": [], "subcategories": []
}

Produto no catálogo:

JSON
{
  "id": "uuid", "name": "Curso", "slug": "curso", "description": "<p>html</p>", "price": 49.9, "compare_price": null,
  "image": null, "featured": false, "status": true, "automatic": true, "stock": 10, "in_stock": true,
  "has_variants": false, "min_price": null, "max_price": null, "created_at": "...", "updated_at": "...",
  "variants": [], "categoria_id": "uuid"
}

stock: null significa ilimitado. Em produto com variantes, stock é a soma das variantes, e null se alguma delas for ilimitada.

Variante:

JSON
{
  "id": "uuid", "product_id": "uuid", "name": "Mensal", "description": "", "price": 10, "compare_price": null, "image": null,
  "stock": 5, "in_stock": true, "status": true, "automatic": true, "affiliate_fee": null, "created_at": "...", "updated_at": "..."
}

Categorias#

Rota Corpo Resposta
POST /categories name obrigatório. Opcionais: slug, pos, icon, banner, parent_category, is_private 201, categoria sem products e subcategories
PATCH /categories/:categoryId Os mesmos, todos opcionais 200, categoria
DELETE /categories/:categoryId 204. Os produtos ficam sem categoria e as subcategorias sobem de nível.
Terminal
curl -X POST "https://api.promisse.store/api/v1/categories" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "Cursos", "is_private": false }'

Subcategoria não pode ter subcategoria, e a tentativa responde 400 invalid_parent.

Produtos#

Rota Resposta
GET /product/:productId 200, produto completo
POST /product 201, produto completo
PATCH /product/:productId 200, produto completo
DELETE /product/:productId 204

No POST são obrigatórios name, price, description, category_id, type e min. No PATCH, tudo é opcional.

Campo Tipo Observação
name Texto, até 200
price, compare_price Decimal compare_price precisa ser maior que price, senão responde invalid_compare.
description HTML, até 200 mil caracteres Sanitizado antes de salvar.
category_id UUID Categoria de outra loja responde 404.
type series ou texto series é estoque em linhas. texto entrega sempre o mesmo conteúdo.
min, max Inteiro max: 0 é sem limite.
stock Lista de textos Em series, cada item vira uma linha, repetidos são ignorados e o PATCH só soma. Em texto, os itens viram o texto de entrega, até 20 mil caracteres.
automatic Booleano false é entrega manual.
quantity Inteiro ou null Estoque numérico de produto texto ou manual.
status, featured, open_chat, hide_when_out_of_stock, hide_sold_count Booleano
slug Texto Gerado a partir do nome, se vazio.
youtube URL ou null
images Lista de URLs, até 12
instructions Texto, até 20 mil caracteres
affiliate_fee Porcentagem ou null
Terminal
curl -X POST "https://api.promisse.store/api/v1/product" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Curso de edição",
    "price": 49.9,
    "compare_price": 79.9,
    "description": "<p>Acesso vitalício.</p>",
    "category_id": "UUID_DA_CATEGORIA",
    "type": "series",
    "min": 1,
    "stock": ["CHAVE-001", "CHAVE-002"]
  }'

O produto completo traz os campos do produto no catálogo, com category_id no lugar de categoria_id, mais type, min, max, quantity, images, youtube, open_chat, instructions, affiliate_fee, hide_when_out_of_stock, hide_sold_count e sold.

Variantes#

Rota Corpo Resposta
GET /products/:productId/variants { "variants": [...] }
POST /products/:productId/variants name e price obrigatórios. Opcionais: description, compare_price, status, automatic, affiliate_fee, image 201, variante
PATCH /products/:productId/variants/:variantId Os mesmos, todos opcionais 200, variante
DELETE /products/:productId/variants/:variantId 204
Terminal
curl -X POST "https://api.promisse.store/api/v1/products/UUID_DO_PRODUTO/variants" \
  -H "x-api-key: $PROMISSE_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "Mensal", "price": "10.00" }'