Skip to main content
POST
/
api
/
portal
/
sessions
Portal do Cliente
curl --request POST \
  --url https://garu.com.br/api/portal/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": 123,
  "productId": 123,
  "returnUrl": "<string>"
}
'

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.

​
Visão Geral

O Portal do Cliente é uma interface de autoatendimento que permite aos assinantes gerenciar suas assinaturas. Você controla o acesso gerando tokens de sessão seguros.

​
Como Funciona

  1. Você cria uma sessão do portal via API
  2. Recebe um token seguro (válido por 1 hora)
  3. Redireciona o cliente para o portal com o token
  4. Cliente gerencia sua assinatura conforme sua configuração

​
Criar Sessão do Portal

Gere um token de acesso para um cliente: 
curl -X POST https://garu.com.br/api/portal/sessions \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": 50,
    "productId": 123,
    "returnUrl": "https://seusite.com/conta"
  }'

​
Parâmetros

​
customerId
integer
required
ID do cliente na Garu.
​
productId
integer
ID do produto para configuração específica (opcional).
​
returnUrl
string
URL para redirecionar após ações no portal.

​
Resposta

{
  "sessionId": 789,
  "token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "expiresAt": "2024-01-15T11:30:00.000Z",
  "portalUrl": "/portal?token=a1b2c3d4e5f6..."
}

​
URL do Portal

https://garu.com.br/portal?token={session_token}
O token expira em 1 hora. Gere um novo token a cada acesso do cliente.

​
Configurar o Portal

​
Configuração Global (Padrão para Todos os Produtos)

curl -X PUT https://garu.com.br/api/portal/configuration \
  -H "Authorization: Bearer sk_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Sua Empresa",
    "logoUrl": "https://seu-cdn.com/logo.png",
    "primaryColor": "#257264",
    "allowCancelSubscription": true,
    "allowUpdatePaymentMethod": true,
    "allowUpdateBillingInfo": true,
    "allowViewInvoices": true,
    "cancelAtPeriodEndOnly": true,
    "requireCancelReason": false,
    "sendCancellationEmail": true,
    "sendPaymentMethodUpdatedEmail": true
  }'

​
Configuração por Produto

Para sobrescrever a configuração global por produto (B2B2C — coach/instrutor/professor como Product), use o endpoint canônico documentado em Portal customizado por produto.
A partir da v0.10.0, {productId} aceita tanto o UUID do produto quanto o id numérico legado. UUID é o caminho recomendado — é o identificador estável retornado por GET /api/products e list_products.

​
Opções de Configuração

OpçãoTipoDescrição
businessNamestringNome da empresa exibido no portal
logoUrlstringURL do logotipo
primaryColorstringCor primária em hex (padrão: #257264)
allowCancelSubscriptionbooleanPermitir cancelamento
allowUpdatePaymentMethodbooleanPermitir trocar cartão
allowUpdateBillingInfobooleanPermitir alterar dados de cobrança
allowViewInvoicesbooleanPermitir ver histórico de pagamentos
cancelAtPeriodEndOnlybooleanForçar cancelamento apenas no fim do período
requireCancelReasonbooleanExigir motivo ao cancelar
sendCancellationEmailbooleanEnviar email ao cancelar
sendPaymentMethodUpdatedEmailbooleanEnviar email ao trocar cartão
customWelcomeTextstringMensagem de boas-vindas personalizada
customSuccessMessagestringMensagem de sucesso personalizada
customCancellationMessagestringMensagem de confirmação de cancelamento

​
Ações Disponíveis no Portal

Baseado na sua configuração, clientes podem:
AçãoFlag de ConfiguraçãoPadrão
Cancelar assinaturaallowCancelSubscriptiontrue
Atualizar cartãoallowUpdatePaymentMethodtrue
Atualizar dados de cobrançaallowUpdateBillingInfotrue
Ver histórico de pagamentosallowViewInvoicestrue
Pausar assinaturaallowCancelSubscriptiontrue
Retomar assinaturaallowCancelSubscriptiontrue

​
Endpoints do Portal (Token-Based)

Todos os endpoints do portal requerem o token de sessão como query parameter.

​
Obter Dados do Portal

curl -X GET "https://garu.com.br/api/portal?token={session_token}"
Retorna informações do cliente, assinaturas ativas e configuração.

​
Cancelar Assinatura

curl -X POST "https://garu.com.br/api/portal/subscriptions/100/cancel?token={session_token}"

​
Pausar Assinatura

curl -X POST "https://garu.com.br/api/portal/subscriptions/100/pause?token={session_token}"

​
Retomar Assinatura

curl -X POST "https://garu.com.br/api/portal/subscriptions/100/resume?token={session_token}"

​
Reativar Assinatura Cancelada

curl -X POST "https://garu.com.br/api/portal/subscriptions/100/reactivate?token={session_token}"

​
Atualizar Método de Pagamento

curl -X POST "https://garu.com.br/api/portal/subscriptions/100/update-payment-method?token={session_token}" \
  -H "Content-Type: application/json" \
  -d '{"paymentMethodId": 456}'

​
Adicionar Novo Cartão

curl -X POST "https://garu.com.br/api/portal/subscriptions/100/add-card-and-update?token={session_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "4111111111111111",
    "holderName": "JOAO SILVA",
    "expiryMonth": 12,
    "expiryYear": 2025,
    "cvv": "123"
  }'

​
Ver Histórico de Pagamentos

curl -X GET "https://garu.com.br/api/portal/subscriptions/100/events?token={session_token}"

​
Atualizar Informações do Cliente

curl -X PUT "https://garu.com.br/api/portal/customer-info?token={session_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@email.com",
    "phone": "11999998888"
  }'

​
Integração Frontend

​
JavaScript

class GaruPortal {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://garu.com.br/api';
    this.portalUrl = 'https://garu.com.br/portal';
  }

  async criarSessao(customerId, options = {}) {
    const response = await fetch(`${this.baseUrl}/portal/sessions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customerId,
        productId: options.productId,
        returnUrl: options.returnUrl || window.location.href
      })
    });

    return response.json();
  }

  // Redirecionar para o portal
  async redirecionar(customerId, options = {}) {
    const session = await this.criarSessao(customerId, options);
    window.location.href = `${this.portalUrl}?token=${session.token}`;
  }

  // Abrir portal em nova janela
  async abrirJanela(customerId, options = {}) {
    const session = await this.criarSessao(customerId, options);
    window.open(
      `${this.portalUrl}?token=${session.token}`,
      'GaruPortal',
      'width=600,height=800'
    );
  }
}

// Uso
const portal = new GaruPortal('sk_test_sua_chave');

// Botão "Gerenciar Assinatura"
document.getElementById('btn-gerenciar').addEventListener('click', async () => {
  await portal.redirecionar(usuarioAtual.garuCustomerId, {
    returnUrl: 'https://seusite.com/conta/assinaturas'
  });
});

​
React

import { useCallback } from 'react';

function BotaoPortal({ customerId }) {
  const abrirPortal = useCallback(async () => {
    const response = await fetch('/api/portal-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ customerId })
    });

    const { portalUrl } = await response.json();
    window.location.href = `https://garu.com.br${portalUrl}`;
  }, [customerId]);

  return (
    <button onClick={abrirPortal}>
      Gerenciar Assinatura
    </button>
  );
}

​
Python (Flask)

from flask import Flask, redirect, request
import requests
import os

app = Flask(__name__)

GARU_API_KEY = os.environ['GARU_API_KEY']

@app.route('/portal')
def abrir_portal():
    customer_id = request.args.get('customer_id')

    response = requests.post(
        'https://garu.com.br/api/portal/sessions',
        headers={
            'Authorization': f'Bearer {GARU_API_KEY}',
            'Content-Type': 'application/json'
        },
        json={
            'customerId': int(customer_id),
            'returnUrl': request.url_root + 'conta'
        }
    )

    session = response.json()
    return redirect(f"https://garu.com.br/portal?token={session['token']}")

​
Boas Práticas de Segurança

Tokens de sessão são sensíveis. Não os registre em logs de aplicação.
Não pré-gere tokens. Crie um novo a cada acesso do cliente.
Sempre use URLs seguras para redirecionamento.
Certifique-se de que o cliente pertence à sua conta antes de gerar o token.
Use webhooks para acompanhar ações dos clientes no portal.

​
Próximos Passos

Webhooks

Receber notificações de ações no portal

Guia de Assinaturas

Voltar ao guia completo