Produtos

Visão Geral

A API de Produtos permite gerenciar todo o catálogo da sua loja. Você pode criar, listar, atualizar e remover produtos programaticamente.

Endpoints

Método	Endpoint	Descrição
`GET`	`/api/sdk/products`	Listar produtos
`POST`	`/api/sdk/products`	Criar produto
`GET`	`/api/sdk/products/:id`	Buscar produto
`PATCH`	`/api/sdk/products/:id`	Atualizar produto
`DELETE`	`/api/sdk/products/:id`	Remover produto

Listar Produtos

GET /api/sdk/products

Parâmetros de Query

Parâmetro	Tipo	Descrição
`limit`	`number`	Máximo de itens (1-100, padrão: 50)
`cursor`	`string`	Cursor para paginação
`status`	`string`	Filtrar por status: `active`, `draft`, `archived`
`search`	`string`	Buscar por título, descrição ou SKU
`productType`	`string`	Filtrar por tipo de produto
`vendor`	`string`	Filtrar por fornecedor
`sku`	`string`	Filtrar por SKU exato
`sortBy`	`string`	Ordenar por: `createdAt`, `updatedAt`, `title`, `price`, `inventoryQuantity`
`sortOrder`	`string`	Ordem: `asc` ou `desc` (padrão: `desc`)

Exemplo de Requisição

curl -X GET "https://api.plasmacheckout.com/api/sdk/products?limit=10&status=active" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

const response = await fetch(
  'https://api.plasmacheckout.com/api/sdk/products?limit=10&status=active',
  {
    headers: {
      'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
      'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx'
    }
  }
);

const result = await response.json();
console.log(result.data);        // array de produtos
console.log(result.pagination);  // { hasMore, nextCursor, count, total }

import requests

response = requests.get(
    'https://api.plasmacheckout.com/api/sdk/products',
    headers={
        'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
        'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx'
    },
    params={'limit': 10, 'status': 'active'}
)

data = response.json()
print(data['data'])        # lista de produtos
print(data['pagination'])  # { hasMore, nextCursor, count, total }

Resposta

{
  "data": [
    {
      "id": "cm5abc123def456ghi789",
      "title": "Camiseta Premium",
      "description": "Camiseta 100% algodão",
      "price": 7990,
      "compareAtPrice": 9990,
      "sku": "CAM-001",
      "status": "active",
      "productType": "Vestuário",
      "vendor": "Minha Marca",
      "images": ["https://..."],
      "imageUrl": "https://...",
      "inventory": 100,
      "trackInventory": true,
      "tags": ["algodão", "premium"],
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cm5abc123def456ghi790",
    "count": 10,
    "total": 150
  },
  "filters": {
    "status": "active",
    "search": null,
    "productType": null,
    "vendor": null
  }
}

Paginação com Cursor

Para buscar a próxima página, use o nextCursor retornado:

curl -X GET "https://api.plasmacheckout.com/api/sdk/products?limit=10&cursor=cm5abc123def456ghi790" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

Quando hasMore for false, não há mais produtos. O campo nextCursor será null.

Criar Produto

POST /api/sdk/products

Body

Campo	Tipo	Obrigatório	Descrição
`title`	`string`	✅	Título do produto (max 255)
`price`	`number`	✅	Preço em centavos (≥ 0)
`description`	`string`	❌	Descrição (max 5000)
`compareAtPrice`	`number`	❌	Preço comparativo (deve ser maior que `price`)
`sku`	`string`	❌	SKU único por loja (max 100)
`status`	`string`	❌	`active`, `draft`, `archived` (padrão: `active`)
`productType`	`string`	❌	Tipo de produto
`vendor`	`string`	❌	Fornecedor
`images`	`array`	❌	URLs das imagens (max 10)
`imageUrl`	`string`	❌	URL da imagem principal
`inventory`	`number`	❌	Quantidade em estoque (padrão: 0)
`trackInventory`	`boolean`	❌	Controlar estoque (padrão: `true`)
`tags`	`string[]`	❌	Tags do produto

Exemplo

curl -X POST "https://api.plasmacheckout.com/api/sdk/products" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Camiseta Premium",
    "description": "Camiseta 100% algodão, confortável e durável",
    "price": 7990,
    "compareAtPrice": 9990,
    "sku": "CAM-001",
    "status": "active",
    "productType": "Vestuário",
    "vendor": "Minha Marca",
    "inventory": 50,
    "trackInventory": true,
    "tags": ["algodão", "premium"],
    "images": [
      "https://exemplo.com/imagem1.jpg",
      "https://exemplo.com/imagem2.jpg"
    ]
  }'

const response = await fetch('https://api.plasmacheckout.com/api/sdk/products', {
  method: 'POST',
  headers: {
    'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
    'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Camiseta Premium',
    description: 'Camiseta 100% algodão, confortável e durável',
    price: 7990,
    compareAtPrice: 9990,
    sku: 'CAM-001',
    status: 'active',
    productType: 'Vestuário',
    vendor: 'Minha Marca',
    inventory: 50,
    trackInventory: true,
    tags: ['algodão', 'premium'],
    images: [
      'https://exemplo.com/imagem1.jpg',
      'https://exemplo.com/imagem2.jpg'
    ]
  })
});

const result = await response.json();
console.log(result.data);     // produto criado
console.log(result.message);  // "Product created successfully"

Resposta (201 Created)

{
  "data": {
    "id": "cm5abc123def456ghi789",
    "title": "Camiseta Premium",
    "description": "Camiseta 100% algodão, confortável e durável",
    "price": 7990,
    "compareAtPrice": 9990,
    "sku": "CAM-001",
    "status": "active",
    "productType": "Vestuário",
    "vendor": "Minha Marca",
    "images": ["https://exemplo.com/imagem1.jpg", "https://exemplo.com/imagem2.jpg"],
    "imageUrl": "https://exemplo.com/imagem1.jpg",
    "inventory": 50,
    "trackInventory": true,
    "tags": ["algodão", "premium"],
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z"
  },
  "message": "Product created successfully"
}

Ao criar um produto, o webhook product.created é disparado automaticamente.

Buscar Produto

GET /api/sdk/products/:id

Exemplo

curl -X GET "https://api.plasmacheckout.com/api/sdk/products/cm5abc123def456ghi789" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

const response = await fetch(
  'https://api.plasmacheckout.com/api/sdk/products/cm5abc123def456ghi789',
  {
    headers: {
      'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
      'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx'
    }
  }
);

const { data } = await response.json();

Resposta

{
  "data": {
    "id": "cm5abc123def456ghi789",
    "title": "Camiseta Premium",
    "description": "Camiseta 100% algodão",
    "price": 7990,
    "compareAtPrice": 9990,
    "sku": "CAM-001",
    "status": "active",
    "productType": "Vestuário",
    "vendor": "Minha Marca",
    "images": ["https://..."],
    "imageUrl": "https://...",
    "inventory": 50,
    "trackInventory": true,
    "tags": ["algodão", "premium"],
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z"
  }
}

Produto Não Encontrado (404)

{
  "error": "Product not found",
  "code": "NOT_FOUND"
}

Atualizar Produto

PATCH /api/sdk/products/:id

Apenas os campos enviados serão atualizados (update parcial). O body aceita os mesmos campos de criação.

Exemplo

curl -X PATCH "https://api.plasmacheckout.com/api/sdk/products/cm5abc123def456ghi789" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 6990,
    "compareAtPrice": 8990,
    "inventory": 30
  }'

const response = await fetch(
  'https://api.plasmacheckout.com/api/sdk/products/cm5abc123def456ghi789',
  {
    method: 'PATCH',
    headers: {
      'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
      'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      price: 6990,
      compareAtPrice: 8990,
      inventory: 30
    })
  }
);

const { data, message } = await response.json();

Resposta

{
  "data": {
    "id": "cm5abc123def456ghi789",
    "title": "Camiseta Premium",
    "price": 6990,
    "compareAtPrice": 8990,
    "inventory": 30,
    "status": "active",
    "updatedAt": "2025-01-15T11:00:00Z"
  },
  "message": "Product updated successfully"
}

Ao atualizar um produto, o webhook product.updated é disparado.

Remover Produto

DELETE /api/sdk/products/:id

A remoção é permanente. O produto é deletado do banco de dados e não pode ser recuperado.

Exemplo

curl -X DELETE "https://api.plasmacheckout.com/api/sdk/products/cm5abc123def456ghi789" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

Resposta

{
  "data": {
    "id": "cm5abc123def456ghi789",
    "deleted": true
  },
  "message": "Product deleted successfully"
}

Validações

Regra	Descrição
Título obrigatório	Mínimo 1, máximo 255 caracteres
Preço obrigatório	Deve ser ≥ 0 (em centavos)
Compare at price	Deve ser maior que `price`
SKU único	Não pode repetir na mesma loja (max 100 chars)
Máximo de imagens	10 imagens por produto
Descrição	Máximo 5000 caracteres

Erros Comuns

Código HTTP	Código	Descrição
`400`	`VALIDATION_ERROR`	Campo inválido ou obrigatório faltando
`404`	`NOT_FOUND`	Produto não encontrado
`409`	`DUPLICATE_SKU`	SKU já existe na loja

Exemplo de Erro

{
  "error": "A product with this SKU already exists",
  "code": "DUPLICATE_SKU"
}

Webhooks Relacionados

Evento	Quando é disparado
`product.created`	Produto criado
`product.updated`	Produto atualizado
`product.deleted`	Produto removido

Webhooks

Saiba mais sobre como receber notificações

Webhooks

On this page