Skip to main content

​
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 Upay
  • 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://upay-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://upay-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",
  "product": {
    "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

CampoTipoDescrição
namestringNome do produto. Máximo 255 caracteres.
priceintegerPreço em centavos. Exemplo: 19990 = R$ 199,90. Mínimo: 1.

​
Campos opcionais

CampoTipoDescriçãoPadrão
descriptionstringDescrição detalhada do produto. Máximo 1000 caracteres.-
imageUrlstringURL da imagem do produto. Deve ser uma URL válida.-
stockQuantityintegerQuantidade em estoque. Obrigatório quando stockEnabled for true.null
stockEnabledbooleanAtiva controle de estoque. Quando true, stockQuantity é obrigatório.false
isDigitalbooleanIndica se o produto é digital (sem entrega física).false
statusstringStatus do produto: “ACTIVE” ou “INACTIVE”.”ACTIVE”

​
Exemplos completos

​
Produto Digital (Sem Estoque)

const response = await fetch('https://upay-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://upay-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://upay-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://upay-sistema-api.onrender.com/api/v1/products?page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"

​
Filtrar por status

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

​
Buscar produto específico

curl -X GET "https://upay-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://upay-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://upay-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://upay-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://upay-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://upay-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.
Após criar seus produtos, você pode associá-los a links de pagamento: 
const response = await fetch('https://upay-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',
    productIds: [
      '550e8400-e29b-41d4-a716-446655440000', // ID do produto
      '550e8400-e29b-41d4-a716-446655440001'  // Outro produto
    ],
    clientId: 'cliente-id'
  })
});

​
Controle de estoque

​
Estoque Ilimitado

Para produtos digitais ou serviços sem limite, deixe stock como null: 
{
  "name": "E-book Digital",
  "price": 29.90,
  "stock": null // Estoque ilimitado
}

​
Estoque Limitado

Para produtos físicos, defina a quantidade disponível: 
{
  "name": "Camiseta",
  "price": 79.90,
  "stock": 50 // 50 unidades disponíveis
}

​
Produto Esgotado

Quando o estoque chegar a zero, o produto não poderá ser adicionado a novos links de pagamento: 
{
  "name": "Produto Esgotado",
  "price": 99.90,
  "stock": 0 // Esgotado
}
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: 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',
  productIds: [curso.id],
  clientId: clienteId
});

​
E-commerce de Produtos Físicos

Gerencie estoque e preços de produtos físicos: 
const produto = await criarProduto({
  name: 'Livro: Clean Code',
  price: 89.90,
  description: 'Livro físico sobre código limpo',
  imageUrl: 'https://exemplo.com/clean-code.jpg',
  stock: 30
});

​
Serviços e Consultorias

Ofereça serviços sem controle de estoque: 
const servico = await criarProduto({
  name: 'Consultoria Técnica - 2h',
  price: 500.00,
  description: 'Sessão de consultoria técnica personalizada',
  stock: null // Sem limite
});

​
Boas práticas

  1. Imagens: Use URLs de imagens otimizadas e hospedadas em CDN
  2. Descrições: Seja claro e objetivo nas descrições
  3. Preços: Sempre use valores com duas casas decimais (ex: 99.90)
  4. Estoque: Mantenha o estoque atualizado para evitar vendas de produtos esgotados
  5. Status: Use INACTIVE para produtos temporariamente indisponíveis
  6. Organização: Use nomes descritivos e padronizados

​
Próximos passos

Referência da API

Veja todos os endpoints disponíveis

Links de pagamento

Associe produtos a links de pagamento