Produtos

Visão geral

O sistema de Produtos permite que você crie e gerencie um catálogo completo de produtos que podem ser associados a links de pagamento. Organize seu inventário, defina preços, adicione imagens e controle o estoque de forma centralizada.

Pré-requisitos

Antes de começar, você precisa:

Uma conta ativa na Alpa
Sua API Key configurada (veja Autenticação)
Conhecimento básico de APIs REST

Funcionalidades

Catálogo completo: Gerencie todos os seus produtos em um só lugar
Preços em centavos: Defina preços em centavos (ex: 19990 = R$ 199,90)
Imagens: Adicione URLs de imagens para seus produtos
Controle de estoque: Gerencie quantidade disponível (opcional)
Descrições ricas: Adicione descrições detalhadas para seus produtos
Status: Ative ou desative produtos conforme necessário
Integração com links: Associe produtos a links de pagamento

Criando um produto

Requisição Básica

curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/products" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Curso de JavaScript Avançado",
    "price": 19990,
    "description": "Aprenda JavaScript do zero ao avançado"
  }'

Requisição Completa

curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/products" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Curso de JavaScript Avançado",
    "price": 19990,
    "description": "Aprenda JavaScript do zero ao avançado com projetos práticos",
    "imageUrl": "https://exemplo.com/imagens/curso-js.jpg",
    "stockQuantity": 100,
    "stockEnabled": true,
    "isDigital": false,
    "status": "ACTIVE"
  }'

Resposta

{
  "message": "Produto criado com sucesso.",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Curso de JavaScript Avançado",
    "price": 19990,
    "description": "Aprenda JavaScript do zero ao avançado com projetos práticos",
    "imageUrl": "https://exemplo.com/imagens/curso-js.jpg",
    "stockQuantity": 100,
    "stockEnabled": true,
    "isDigital": false,
    "status": "ACTIVE",
    "createdAt": "2025-12-30T00:00:00.000Z",
    "updatedAt": "2025-12-30T00:00:00.000Z"
  }
}

Campos disponíveis

Campos obrigatórios

Campo	Tipo	Descrição
`name`	string	Nome do produto. Máximo 255 caracteres.
`price`	integer	Preço em centavos. Exemplo: 19990 = R$ 199,90. Mínimo: 1.

Campos opcionais

Campo	Tipo	Descrição	Padrão
`description`	string	Descrição detalhada do produto. Máximo 1000 caracteres.	-
`imageUrl`	string	URL da imagem do produto. Deve ser uma URL válida.	-
`stockQuantity`	integer	Quantidade em estoque. Obrigatório quando `stockEnabled` for true.	null
`stockEnabled`	boolean	Ativa controle de estoque. Quando true, `stockQuantity` é obrigatório.	false
`isDigital`	boolean	Indica se o produto é digital (sem entrega física).	false
`status`	string	Status do produto: “ACTIVE” ou “INACTIVE”.	”ACTIVE”

Exemplos completos

Produto Digital (Sem Estoque)

const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'E-book: Guia Completo de Node.js',
    price: 4990,
    description: 'E-book com 300 páginas sobre Node.js, incluindo exemplos práticos e projetos reais',
    imageUrl: 'https://exemplo.com/ebook-nodejs.jpg',
    isDigital: true,
    status: 'ACTIVE'
  })
});

Produto Físico (Com Estoque)

const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Camiseta Dev JavaScript',
    price: 7990,
    description: 'Camiseta 100% algodão com estampa exclusiva para desenvolvedores JavaScript',
    imageUrl: 'https://exemplo.com/camiseta-js.jpg',
    stockQuantity: 50,
    stockEnabled: true,
    isDigital: false,
    status: 'ACTIVE'
  })
});

Serviço/Consultoria

const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Consultoria de Arquitetura de Software - 1h',
    price: 35000,
    description: 'Sessão de consultoria individual de 1 hora sobre arquitetura de software e boas práticas',
    status: 'ACTIVE'
  })
});

Listando produtos

Listar todos os produtos

curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/products?page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"

Filtrar por status

curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/products?status=ACTIVE" \
  -H "Authorization: Bearer SUA_API_KEY"

Buscar produto específico

curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/products/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"

Resposta da listagem

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Curso de JavaScript Avançado",
      "price": 19990,
      "description": "Aprenda JavaScript do zero ao avançado",
      "imageUrl": "https://exemplo.com/curso-js.jpg",
      "stockQuantity": 100,
      "stockEnabled": true,
      "isDigital": false,
      "status": "ACTIVE",
      "createdAt": "2025-12-30T00:00:00.000Z",
      "updatedAt": "2025-12-30T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Atualizando um produto

curl -X PATCH "https://alpa-sistema-api.onrender.com/api/v1/products/{id}" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 17990,
    "stockQuantity": 75
  }'

Você pode atualizar apenas os campos que desejar. Campos não enviados permanecerão inalterados.

Exemplo: Atualizar preço

const response = await fetch(`https://alpa-sistema-api.onrender.com/api/v1/products/${productId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    price: 14990
  })
});

Exemplo: Desativar produto

const response = await fetch(`https://alpa-sistema-api.onrender.com/api/v1/products/${productId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'INACTIVE'
  })
});

Exemplo: Atualizar estoque

const response = await fetch(`https://alpa-sistema-api.onrender.com/api/v1/products/${productId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stockQuantity: 25 // Novo estoque disponível
  })
});

Deletando um produto

curl -X DELETE "https://alpa-sistema-api.onrender.com/api/v1/products/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"

A exclusão é permanente. Produtos associados a links de pagamento existentes não serão afetados, mas não poderão ser usados em novos links.

Associando produtos a links de pagamento

Após criar seus produtos, você pode associá-los a links de pagamento:

const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/payment-links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Compra de Curso',
    products: [
      { productId: '550e8400-e29b-41d4-a716-446655440000', quantity: 1 },
      { productId: '550e8400-e29b-41d4-a716-446655440001', quantity: 2 }
    ]
  })
});

Controle de estoque

Estoque Ilimitado

Para produtos digitais ou serviços sem limite, deixe stockEnabled como false:

{
  "name": "E-book Digital",
  "price": 2990,
  "stockEnabled": false
}

Estoque Limitado

Para produtos físicos, defina a quantidade disponível:

{
  "name": "Camiseta",
  "price": 7990,
  "stockEnabled": true,
  "stockQuantity": 50
}

Produto Esgotado

Quando o estoque chegar a zero, o produto não poderá ser adicionado a novos links de pagamento. Atualize o estoque via PATCH:

{
  "stockQuantity": 0
}

O estoque é decrementado automaticamente quando um pagamento é confirmado. Você também pode atualizar manualmente usando o endpoint PATCH.

Casos de uso

Loja de Cursos Online

Crie produtos para cada curso e associe-os a links de pagamento personalizados:

// Criar curso
const curso = await criarProduto({
  name: 'Curso Completo de React',
  price: 29990, // R$ 299,90
  description: 'Do básico ao avançado com projetos reais',
  imageUrl: 'https://exemplo.com/curso-react.jpg'
});

// Criar link de pagamento
const link = await criarLinkPagamento({
  title: 'Matrícula - Curso de React',
  products: [{ productId: curso.id, quantity: 1 }]
});

E-commerce de Produtos Físicos

Gerencie estoque e preços de produtos físicos:

const produto = await criarProduto({
  name: 'Livro: Clean Code',
  price: 8990, // R$ 89,90
  description: 'Livro físico sobre código limpo',
  imageUrl: 'https://exemplo.com/clean-code.jpg',
  stockEnabled: true,
  stockQuantity: 30
});

Serviços e Consultorias

Ofereça serviços sem controle de estoque:

const servico = await criarProduto({
  name: 'Consultoria Técnica - 2h',
  price: 50000, // R$ 500,00
  description: 'Sessão de consultoria técnica personalizada',
  stockEnabled: false
});

Boas práticas

Imagens: Use URLs de imagens otimizadas e hospedadas em CDN
Descrições: Seja claro e objetivo nas descrições
Preços: Sempre use valores em centavos (ex: 9990 = R$ 99,90)
Estoque: Mantenha o estoque atualizado para evitar vendas de produtos esgotados
Status: Use INACTIVE para produtos temporariamente indisponíveis
Organização: Use nomes descritivos e padronizados

Visão geral

Pré-requisitos

Funcionalidades

Criando um produto

Requisição Básica

Requisição Completa

Resposta

Campos disponíveis

Campos obrigatórios

Campos opcionais

Exemplos completos

Produto Digital (Sem Estoque)

Produto Físico (Com Estoque)

Serviço/Consultoria

Listando produtos

Listar todos os produtos

Filtrar por status

Buscar produto específico

Resposta da listagem

Atualizando um produto

Exemplo: Atualizar preço

Exemplo: Desativar produto

Exemplo: Atualizar estoque

Deletando um produto

Associando produtos a links de pagamento

Controle de estoque

Estoque Ilimitado

Estoque Limitado

Produto Esgotado

Casos de uso

Loja de Cursos Online

E-commerce de Produtos Físicos

Serviços e Consultorias

Boas práticas

Próximos passos

Referência da API

Links de pagamento

​Visão geral

​Pré-requisitos

​Funcionalidades

​Criando um produto

​Requisição Básica

​Requisição Completa

​Resposta

​Campos disponíveis

​Campos obrigatórios

​Campos opcionais

​Exemplos completos

​Produto Digital (Sem Estoque)

​Produto Físico (Com Estoque)

​Serviço/Consultoria

​Listando produtos

​Listar todos os produtos

​Filtrar por status

​Buscar produto específico

​Resposta da listagem

​Atualizando um produto

​Exemplo: Atualizar preço

​Exemplo: Desativar produto

​Exemplo: Atualizar estoque

​Deletando um produto

​Associando produtos a links de pagamento

​Controle de estoque

​Estoque Ilimitado

​Estoque Limitado

​Produto Esgotado

​Casos de uso

​Loja de Cursos Online

​E-commerce de Produtos Físicos

​Serviços e Consultorias

​Boas práticas

​Próximos passos

Referência da API

Links de pagamento

Visão geral

Pré-requisitos

Funcionalidades

Criando um produto

Requisição Básica

Requisição Completa

Resposta

Campos disponíveis

Campos obrigatórios

Campos opcionais

Exemplos completos

Produto Digital (Sem Estoque)

Produto Físico (Com Estoque)

Serviço/Consultoria

Listando produtos

Listar todos os produtos

Filtrar por status

Buscar produto específico

Resposta da listagem

Atualizando um produto

Exemplo: Atualizar preço

Exemplo: Desativar produto

Exemplo: Atualizar estoque

Deletando um produto

Associando produtos a links de pagamento

Controle de estoque

Estoque Ilimitado

Estoque Limitado

Produto Esgotado

Casos de uso

Loja de Cursos Online

E-commerce de Produtos Físicos

Serviços e Consultorias

Boas práticas

Próximos passos