> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealpa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Produtos

> Gerencie seu catálogo de produtos e associe-os a links de pagamento

## 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](/authentication))
* 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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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)

```javascript theme={null}
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)

```javascript theme={null}
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

```javascript theme={null}
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

```bash theme={null}
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

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

### Buscar produto específico

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

### Resposta da listagem

```json theme={null}
{
  "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

```bash theme={null}
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
  }'
```

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

### Exemplo: Atualizar preço

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

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

<Warning>
  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.
</Warning>

## Associando produtos a links de pagamento

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

```javascript theme={null}
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`:

```json theme={null}
{
  "name": "E-book Digital",
  "price": 2990,
  "stockEnabled": false
}
```

### Estoque Limitado

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "stockQuantity": 0
}
```

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

## Casos de uso

### Loja de Cursos Online

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

```javascript theme={null}
// 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:

```javascript theme={null}
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:

```javascript theme={null}
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

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 em centavos (ex: 9990 = R\$ 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

<CardGroup cols={2}>
  <Card title="Referência da API" icon="code" href="/products/reference">
    Veja todos os endpoints disponíveis
  </Card>

  <Card title="Links de pagamento" icon="link" href="/pages/guides/features/payment-links">
    Associe produtos a links de pagamento
  </Card>
</CardGroup>