Skip to main content

​
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.

​
Tipos de Produto

A Garu suporta dois tipos de produto:
TipoDescriçãoUso
Venda AvulsaPagamento únicoCursos, e-books, produtos digitais
AssinaturaPagamento recorrenteSaaS, 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

CampoTipoDescrição
namestringNome do produto (exibido ao cliente)

​
Campos Opcionais (com valores padrão)

CampoTipoPadrãoDescrição
descriptionstring""Descrição do produto
valuenumber0Preço em Reais (use 0 para produtos de assinatura)
pixbooleantrueHabilitar pagamento via PIX
creditCardbooleantrueHabilitar cartão de crédito
boletobooleantrueHabilitar boleto bancário
installmentsnumber1Parcelas máximas (1-12)

​
Campos Opcionais (sem padrão)

CampoTipoDescrição
imagestringURL da imagem do produto
tagsstring[]Tags para categorização
returnUrlstringURL de redirecionamento pós-pagamento
returnUrlButtonTextstringTexto do botão de retorno
pixelFBstringID 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
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á:
  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: 
{
  "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
});

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

{ "message": ["value must be at least 5"] }
Solução: O preço mínimo é R$ 5,00.
{ "message": "At least one payment method is required" }
Solução: Habilite pelo menos pix, creditCard ou boleto.
{ "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.

​
Próximos Passos

Webhooks

Configure notificações de pagamento

Ir para Produção

Checklist para lançar em produção