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:

Campos Obrigatórios

Campo	Tipo	Descrição
`name`	string	Nome do produto (exibido ao cliente)
`image`	string	URL da imagem do produto
`value`	number	Preço em Reais (ex: `47.00`), nunca em centavos. `0` = produto sem preço; qualquer outro preço precisa ser de pelo menos R$ 5,00

Campos Opcionais (com valores padrão)

Campo	Tipo	Padrão	Descrição
`description`	string	`""`	Descrição do produto
`pix`	boolean	`false`	Habilitar pagamento via PIX
`creditCard`	boolean	`false`	Habilitar cartão de crédito
`boleto`	boolean	`false`	Habilitar boleto bancário
`pixAutomatic`	boolean	`true`	Habilitar Pix Automático (débito recorrente) no checkout de assinatura
`installments`	number	`1`	Parcelas máximas (1-12)
`isSubscription`	boolean	`false`	Produto de assinatura: o preço fica nos preços de assinatura

Campos Opcionais (sem padrão)

Campo	Tipo	Descrição
`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

Os métodos de pagamento vêm desligados por padrão. Envie pix, creditCard e boleto com true para os que você quer aceitar.

O Preço do Produto

O value de um produto é sempre em Reais (47.00 = R$ 47,00) e segue uma regra simples:

`value`	Resultado
`0`	Aceito: o produto fica sem preço
De `0.01` a `4.99`	Recusado com `400`
Negativo	Recusado com `400`
`5.00` ou mais	Aceito

undefined

5,00.

Um produto sem preço não vende pelo link de pagamento: a cobrança de R

0,00 é recusada. Use-o para um produto que você cobra de outro jeito, como por [cobranças agendadas](/guias/cobrancas-agendadas), que levam o próprio valor. Para vender pelo link, dê ao produto um preço de pelo menos R

5,00.

Ao atualizar um produto, a regra só vale quando o pedido envia value. Um produto que já custava menos de R$ 5,00 antes da regra continua vendendo pelo mesmo preço, e um pedido que não envia value mantém o preço antigo.

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/v1/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",
    "image": "https://meusite.com/imagens/ebook-marketing.jpg",
    "value": 47.00,
    "pix": true,
    "creditCard": true,
    "boleto": true,
    "installments": 3
  }'

Resposta:

{
  "name": "E-book: Guia de Marketing Digital",
  "description": "Aprenda as melhores estratégias de marketing digital",
  "image": "https://meusite.com/imagens/ebook-marketing.jpg",
  "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"
}

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 Sem Preço

Para um produto que você não vende pelo link, por exemplo um profissional de uma plataforma que você cobra por cobranças agendadas, envie value: 0:

curl -X POST https://garu.com.br/api/v1/products \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coach Maria",
    "image": "https://meusite.com/imagens/coach-maria.jpg",
    "value": 0
  }'

Criando um Produto Completo

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

curl -X POST https://garu.com.br/api/v1/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"
  }'

Vendendo o Mesmo Produto por Outro Preço (Ofertas)

Uma oferta é um preço com nome em um produto, com link próprio. Use para vender o mesmo produto por R

497,00 na página de vendas e por R

97,00 para a sua lista de e-mails, sem duplicar o produto. A oferta muda só o preço: métodos de pagamento, parcelas, nome, descrição e imagem continuam os do produto.

curl -X POST https://garu.com.br/api/v1/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890/offers \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "value": 97.00,
    "slug": "black-friday"
  }'

O link da oferta é https://garu.com.br/pay/{uuid}?offer=black-friday. O link do produto sem ?offer= continua cobrando o preço do produto.

Campo	Descrição
`name`	Seu rótulo interno. Nunca aparece para o comprador
`value`	Preço em Reais, na mesma unidade do `value` do produto. Precisa ser de pelo menos R$ 5,00. Diferente do produto, a oferta não pode ter preço `0`: de `0` a `4.99` a API responde `400`
`slug`	Opcional. Letras minúsculas, números e hífens, de 3 a 40 caracteres. É público e fácil de adivinhar: sem ele, o link usa o id da oferta
`isActive`	Padrão `true`. Para encerrar uma promoção, envie `false` com `PATCH /api/v1/offers/{offerId}`

Ao mudar o preço de uma oferta com PATCH /api/v1/offers/{offerId}, o mínimo vale para o novo value. Um pedido sem value (por exemplo, só para desativar a oferta) passa normalmente e mantém o preço.

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 ligado por padrão (true) na API; envie false para não oferecer
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" \
  --image "https://meusite.com/imagens/plano-mensal.jpg" \
  --value 49.90 \
  --pix --credit-card --pix-automatic \
  --subscription --subscription-type monthly

--value é em Reais: 49.90 é R

49,90. Não use centavos, porque `--value 4990` cadastraria um produto de R

4.990,00.

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 - name, image e value são obrigatórios
const produtoSimples = await criarProduto({
  name: 'Meu Produto',
  image: 'https://meusite.com/imagens/meu-produto.jpg',
  value: 49.90,
  pix: true
});

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

// Salvar UUID no banco de dados
await salvarNoBanco({
  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

Preço abaixo do mínimo

{
  "statusCode": 400,
  "message": "O preço mínimo de um produto é R$ 5,00. Use R$ 0,00 para um produto sem preço."
}

Solução: Envie um value de pelo menos 5.00, ou 0 para um produto sem preço. De R

0,01 a R

4,99 o produto é recusado.

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
URL da imagem do produto
Preço em Reais: pelo menos R$ 5,00 para vender pelo link, ou 0 para um produto sem preço
URL de retorno configurada (opcional mas recomendado)
Webhook configurado para receber confirmações

name, image e value são obrigatórios. Os métodos de pagamento (PIX, Cartão, Boleto) vêm desligados por padrão: ligue os que você quer aceitar.

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

Primeiros Passos

Integrando Pagamentos

Ferramentas para Agentes

Integrações

Criando Produtos

Visão Geral

Tipos de Produto

Estrutura de um Produto

Campos Obrigatórios

Campos Opcionais (com valores padrão)

Campos Opcionais (sem padrão)

O Preço do Produto

Criando um Produto com Preço

Criando um Produto Sem Preço

Criando um Produto Completo

Vendendo o Mesmo Produto por Outro Preço (Ofertas)

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

​Campos Obrigatórios

​Campos Opcionais (com valores padrão)

​Campos Opcionais (sem padrão)

​O Preço do Produto

​Criando um Produto com Preço

​Criando um Produto Sem Preço

​Criando um Produto Completo

​Vendendo o Mesmo Produto por Outro Preço (Ofertas)

​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

Campos Obrigatórios

Campos Opcionais (com valores padrão)

Campos Opcionais (sem padrão)

O Preço do Produto

Criando um Produto com Preço

Criando um Produto Sem Preço

Criando um Produto Completo

Vendendo o Mesmo Produto por Outro Preço (Ofertas)

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