Criando Produtos

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

Pré-requisito: Você precisa de uma chave de API. Veja como obter em Autenticação.

Inclua sua chave de API no header Authorization de todas as requisições:

Authorization: Bearer sk_test_sua_chave_api

Nunca exponha sua chave de API em código frontend ou repositórios públicos.

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.

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 (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

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.

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:

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:

{
  "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"
}

Link de pagamento: https://garu.com.br/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890Saiba mais sobre o formato dos links em Link de Pagamento.

Criando um Produto com Preço

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

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:

{
  "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:

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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 liga o Pix Automático na criação com a flag --pix-automatic:

garu products create \
  --name "Plano Mensal" \
  --value 4990 \
  --pix --credit-card --pix-automatic \
  --subscription --subscription-type monthly

Guia do Pix Automático

Entenda como o cliente autoriza, o que acontece nos próximos ciclos e como cancelar.

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

URL de Retorno Personalizada

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

{
  "returnUrl": "https://meusite.com/obrigado",
  "returnUrlButtonText": "Acessar Meu Produto"
}

Após o pagamento, o cliente verá:

Uma mensagem de sucesso
Um botão com o texto “Acessar Meu Produto”
Ao clicar, será redirecionado para https://meusite.com/obrigado

Passando Dados na URL de Retorno

Você pode incluir parâmetros dinâmicos:

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

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

Rastreamento com Facebook Pixel

Para rastrear conversões no Facebook Ads:

{
  "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:

{
  "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

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

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 para todos os eventos disponíveis.

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

Valor mínimo não atingido

{ "message": ["value must be at least 5"] }

Solução: O preço mínimo é R$ 5,00.

Nenhum método de pagamento

{ "message": "At least one payment method is required" }

Solução: Habilite pelo menos pix, creditCard ou boleto.

Parcelas inválidas

{ "message": ["installments must be between 1 and 12"] }

Solução: Use um valor entre 1 e 12.

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

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.

Precisa listar, atualizar ou excluir produtos? Consulte a referência completa: Listar, Atualizar, Excluir.

Criando Produtos

Visão Geral

Tipos de Produto

Estrutura de um Produto

Campo Obrigatório

Campos Opcionais (com valores padrão)

Campos Opcionais (sem padrão)

Criando um Produto Mínimo

Criando um Produto com Preço

Criando um Produto Completo

Configurando Métodos de Pagamento

PIX

Cartão de Crédito

Boleto

Pix Automático

Guia do Pix Automático

URL de Retorno Personalizada

Passando Dados na URL de Retorno

Rastreamento com Facebook Pixel

Usando Tags para Organização

Fluxo Completo de Integração

1. Criar Produto

2. Exibir Link de Pagamento

3. Receber Webhook de Pagamento

Erros Comuns

Checklist de Criação

Próximos Passos

Webhooks

Ir para Produção

​Visão Geral

​Tipos de Produto

​Estrutura de um Produto

​Campo Obrigatório

​Campos Opcionais (com valores padrão)

​Campos Opcionais (sem padrão)

​Criando um Produto Mínimo

​Criando um Produto com Preço

​Criando um Produto Completo

​Configurando Métodos de Pagamento

​PIX

​Cartão de Crédito

​Boleto

​Pix Automático

Guia do Pix Automático

​URL de Retorno Personalizada

​Passando Dados na URL de Retorno

​Rastreamento com Facebook Pixel

​Usando Tags para Organização

​Fluxo Completo de Integração

​1. Criar Produto

​2. Exibir Link de Pagamento

​3. Receber Webhook de Pagamento

​Erros Comuns

​Checklist de Criação

​Próximos Passos

Webhooks

Ir para Produção

Visão Geral

Tipos de Produto

Estrutura de um Produto

Campo Obrigatório

Campos Opcionais (com valores padrão)

Campos Opcionais (sem padrão)

Criando um Produto Mínimo

Criando um Produto com Preço

Criando um Produto Completo

Configurando Métodos de Pagamento

PIX

Cartão de Crédito

Boleto

Pix Automático

URL de Retorno Personalizada

Passando Dados na URL de Retorno

Rastreamento com Facebook Pixel

Usando Tags para Organização

Fluxo Completo de Integração

1. Criar Produto

2. Exibir Link de Pagamento

3. Receber Webhook de Pagamento

Erros Comuns

Checklist de Criação

Próximos Passos