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

# Criando Produtos

> Guia completo para criar produtos e começar a vender via API

## Visão Geral

Este guia cobre tudo que você precisa saber para criar produtos na Garu e começar a receber pagamentos. Ao final, você terá:

* Um produto configurado com todos os métodos de pagamento
* Um link de pagamento para compartilhar com seus clientes
* Webhooks configurados para receber notificações de pagamento

<Note>
  **Pré-requisito:** Você precisa de uma chave de API. Veja como obter em [Autenticação](/api-reference/autenticacao).
</Note>

<Snippet file="snippets/auth-header.mdx" />

## Tipos de Produto

A Garu suporta dois tipos de produto:

| Tipo             | Descrição            | Uso                                |
| ---------------- | -------------------- | ---------------------------------- |
| **Venda Avulsa** | Pagamento único      | Cursos, e-books, produtos digitais |
| **Assinatura**   | Pagamento recorrente | SaaS, membresias, serviços mensais |

Este guia foca em **vendas avulsas**. Para assinaturas, consulte o [guia de Assinaturas](/guias/assinaturas).

## Estrutura de um Produto

Um produto na Garu possui os seguintes campos:

### Campo Obrigatório

| Campo  | Tipo   | Descrição                            |
| ------ | ------ | ------------------------------------ |
| `name` | string | Nome do produto (exibido ao cliente) |

### Campos Opcionais (com valores padrão)

| Campo          | Tipo    | Padrão  | Descrição                                                             |
| -------------- | ------- | ------- | --------------------------------------------------------------------- |
| `description`  | string  | `""`    | Descrição do produto                                                  |
| `value`        | number  | `0`     | Preço em Reais (use 0 para produtos de assinatura)                    |
| `pix`          | boolean | `true`  | Habilitar pagamento via PIX                                           |
| `creditCard`   | boolean | `true`  | Habilitar cartão de crédito                                           |
| `boleto`       | boolean | `true`  | Habilitar boleto bancário                                             |
| `pixAutomatic` | boolean | `false` | Habilitar [Pix Automático](/guias/pix-automatico) (débito recorrente) |
| `installments` | number  | `1`     | Parcelas máximas (1-12)                                               |

### Campos Opcionais (sem padrão)

| Campo                 | Tipo      | Descrição                             |
| --------------------- | --------- | ------------------------------------- |
| `image`               | string    | URL da imagem do produto              |
| `tags`                | string\[] | Tags para categorização               |
| `returnUrl`           | string    | URL de redirecionamento pós-pagamento |
| `returnUrlButtonText` | string    | Texto do botão de retorno             |
| `pixelFB`             | string    | ID do Facebook Pixel                  |

<Tip>
  Com a API simplificada, você pode criar um produto enviando apenas o campo `name`. Todos os métodos de pagamento serão habilitados por padrão.
</Tip>

## Criando um Produto Mínimo

O exemplo mais simples de criação de produto. Envie apenas o nome e todos os métodos de pagamento serão habilitados por padrão:

```bash theme={null}
curl -X POST https://garu.com.br/api/products \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu Produto"
  }'
```

**Resposta:**

```json theme={null}
{
  "id": 123,
  "name": "Meu Produto",
  "description": "",
  "value": 0,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pix": true,
  "creditCard": true,
  "boleto": true,
  "installments": [{ "quantity": 1, "value": 0 }],
  "isActive": true,
  "createdAt": "2024-12-24T10:30:00.000Z"
}
```

<Check>
  **Link de pagamento:** `https://garu.com.br/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890`

  Saiba mais sobre o formato dos links em [Link de Pagamento](/api-reference/produtos/link-pagamento).
</Check>

## Criando um Produto com Preço

Para produtos de venda avulsa, defina o valor e personalize os métodos de pagamento:

```bash theme={null}
curl -X POST https://garu.com.br/api/products \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-book: Guia de Marketing Digital",
    "description": "Aprenda as melhores estratégias de marketing digital",
    "value": 47.00,
    "pix": true,
    "creditCard": true,
    "boleto": true,
    "installments": 3
  }'
```

**Resposta:**

```json theme={null}
{
  "id": 123,
  "name": "E-book: Guia de Marketing Digital",
  "description": "Aprenda as melhores estratégias de marketing digital",
  "value": 47.00,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pix": true,
  "creditCard": true,
  "boleto": true,
  "installments": [
    { "quantity": 1, "value": 47.00 },
    { "quantity": 2, "value": 24.30 },
    { "quantity": 3, "value": 16.61 }
  ],
  "isActive": true,
  "createdAt": "2024-12-24T10:30:00.000Z"
}
```

## Criando um Produto Completo

Exemplo com todas as opções disponíveis:

```bash theme={null}
curl -X POST https://garu.com.br/api/products \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Curso Completo de Python",
    "description": "Do zero ao avançado com projetos práticos. Inclui certificado.",
    "value": 297.00,
    "pix": true,
    "creditCard": true,
    "boleto": true,
    "installments": 12,
    "image": "https://meusite.com/imagens/curso-python.jpg",
    "tags": ["curso", "programacao", "python"],
    "returnUrl": "https://meusite.com/obrigado",
    "returnUrlButtonText": "Acessar o Curso",
    "pixelFB": "123456789012345"
  }'
```

## Configurando Métodos de Pagamento

### PIX

O PIX oferece confirmação instantânea e é o método preferido para produtos digitais.

```json theme={null}
{
  "pix": true
}
```

**Vantagens:**

* Confirmação em segundos
* Sem taxas para o cliente
* Maior taxa de conversão

### Cartão de Crédito

Permite parcelamento, ideal para produtos de maior valor.

```json theme={null}
{
  "creditCard": true,
  "installments": 12
}
```

**Parcelamento:**

* O valor de cada parcela é calculado automaticamente
* Inclui juros conforme configurado na sua conta

### Boleto

Para clientes que preferem não usar cartão ou PIX.

```json theme={null}
{
  "boleto": true
}
```

**Considerações:**

* Pagamento leva 1-3 dias úteis para compensar
* Maior taxa de abandono

### Pix Automático

Débito recorrente do Pix: o cliente autoriza uma vez no app do banco e os próximos ciclos são debitados sozinhos. Ideal para mensalidades e assinaturas sem cartão.

```json theme={null}
{
  "pixAutomatic": true
}
```

**Considerações:**

* Vem desligado por padrão (`false`)
* Só faz sentido para cobranças recorrentes
* Habilita a aba **Pix Automático** no checkout do produto

Prefere o terminal? A [CLI](/guias/cli) liga o Pix Automático na criação com a flag `--pix-automatic`:

```bash theme={null}
garu products create \
  --name "Plano Mensal" \
  --value 4990 \
  --pix --credit-card --pix-automatic \
  --subscription --subscription-type monthly
```

<Card title="Guia do Pix Automático" icon="repeat" href="/guias/pix-automatico" horizontal>
  Entenda como o cliente autoriza, o que acontece nos próximos ciclos e como cancelar.
</Card>

<Tip>
  **Recomendação:** Habilite todos os métodos de pagamento para maximizar conversões. Deixe o cliente escolher.
</Tip>

## URL de Retorno Personalizada

Configure para onde o cliente será redirecionado após o pagamento:

```json theme={null}
{
  "returnUrl": "https://meusite.com/obrigado",
  "returnUrlButtonText": "Acessar Meu Produto"
}
```

Após o pagamento, o cliente verá:

1. Uma mensagem de sucesso
2. Um botão com o texto "Acessar Meu Produto"
3. Ao clicar, será redirecionado para `https://meusite.com/obrigado`

### Passando Dados na URL de Retorno

Você pode incluir parâmetros dinâmicos:

```json theme={null}
{
  "returnUrl": "https://meusite.com/ativar?produto=curso-python"
}
```

<Warning>
  A URL de retorno é apenas visual. Sempre valide o pagamento via webhook antes de liberar acesso.
</Warning>

## Rastreamento com Facebook Pixel

Para rastrear conversões no Facebook Ads:

```json theme={null}
{
  "pixelFB": "123456789012345"
}
```

Eventos disparados automaticamente:

* `PageView` - Quando a página de checkout carrega
* `InitiateCheckout` - Quando o cliente inicia o checkout
* `Purchase` - Quando o pagamento é confirmado

## Usando Tags para Organização

Tags ajudam a categorizar e filtrar produtos:

```json theme={null}
{
  "tags": ["curso", "programacao", "python", "iniciante"]
}
```

**Boas práticas:**

* Use tags consistentes em todos os produtos
* Inclua categoria, tipo e nível
* Evite tags muito específicas

## Fluxo Completo de Integração

### 1. Criar Produto

```javascript theme={null}
// Exemplo mínimo - apenas o nome é obrigatório
const produtoSimples = await criarProduto({
  name: 'Meu Produto'
});

// Exemplo completo - com todas as opções
const produto = await criarProduto({
  name: 'Curso de Python',
  description: 'Aprenda Python do zero',
  value: 297.00,
  pix: true,
  creditCard: true,
  boleto: true,
  installments: 12,
  returnUrl: 'https://meusite.com/obrigado'
});

// Salvar UUID no banco de dados
await salvarNoBanco({
  produtoId: produto.id,
  uuid: produto.uuid,
  nome: produto.name
});
```

### 2. Exibir Link de Pagamento

```javascript theme={null}
const linkPagamento = `https://garu.com.br/pay/${produto.uuid}`;

// Enviar por email, exibir no site, etc.
```

### 3. Receber Webhook de Pagamento

Configure webhooks para receber notificações em tempo real. Veja a [documentação de Webhooks](/api-reference/webhooks) para todos os eventos disponíveis.

```javascript theme={null}
app.post('/webhooks/garu', async (req, res) => {
  // Validar assinatura
  if (!validarAssinatura(req)) {
    return res.status(401).json({ error: 'Inválido' });
  }

  const { event, data } = req.body;

  if (event === 'transaction.paid') {
    // Liberar acesso ao produto
    await liberarAcesso({
      email: data.customer.email,
      produtoId: data.productId
    });

    // Enviar email de boas-vindas
    await enviarEmail({
      para: data.customer.email,
      assunto: 'Seu acesso está liberado!',
      conteudo: 'Clique aqui para acessar seu produto...'
    });
  }

  res.status(200).json({ received: true });
});
```

## Erros Comuns

<AccordionGroup>
  <Accordion title="Valor mínimo não atingido">
    ```json theme={null}
    { "message": ["value must be at least 5"] }
    ```

    **Solução:** O preço mínimo é R\$ 5,00.
  </Accordion>

  <Accordion title="Nenhum método de pagamento">
    ```json theme={null}
    { "message": "At least one payment method is required" }
    ```

    **Solução:** Habilite pelo menos `pix`, `creditCard` ou `boleto`.
  </Accordion>

  <Accordion title="Parcelas inválidas">
    ```json theme={null}
    { "message": ["installments must be between 1 and 12"] }
    ```

    **Solução:** Use um valor entre 1 e 12.
  </Accordion>
</AccordionGroup>

## Checklist de Criação

Antes de criar um produto, verifique:

* [ ] Nome claro e descritivo (único campo obrigatório)
* [ ] Preço definido (se for venda avulsa, mínimo R\$ 5,00)
* [ ] URL de retorno configurada (opcional mas recomendado)
* [ ] Webhook configurado para receber confirmações

<Note>
  Com a API simplificada, apenas o `name` é obrigatório. Todos os métodos de pagamento (PIX, Cartão, Boleto) são habilitados por padrão.
</Note>

<Tip>
  Precisa listar, atualizar ou excluir produtos? Consulte a referência completa: [Listar](/api-reference/produtos/listar), [Atualizar](/api-reference/produtos/atualizar), [Excluir](/api-reference/produtos/excluir).
</Tip>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Configure notificações de pagamento
  </Card>

  <Card title="Ir para Produção" icon="rocket" href="/guias/producao">
    Checklist para lançar em produção
  </Card>
</CardGroup>