Início rápido (SDK)

Este guia espelha o Início rápido da API, mas usando o @repass/sdk: você cria um Programa, recruta e aprova um Afiliado, gera um Link, registra uma Conversão server-to-server e consulta a Comissão, tudo com tipos e autocomplete.

Pré-requisitos

Instale o SDK e exporte a chave

npm install @repass/sdk
export REPASS_API_KEY="rstr_..."

Gere uma API key server-to-server (rstr_…) no painel da organização, com role admin ou owner. Detalhes em Autenticação.

Instancie o client

import { Repass } from "@repass/sdk";

const repass = new Repass(process.env.REPASS_API_KEY!);

Para timeout, retentativas, headers padrão e outras opções, veja Configuração.

Fluxo completo

Crie um programa

Um Programa define moeda, modelo/janela de atribuição, hold e modo de aprovação.

const program = await repass.programs.create({
  name: "Programa de Indicações",
  attributionModel: "last_click",
  approvalMode: "manual",
});

Crie uma regra de comissão versionada para o programa. Sem uma regra vigente, a conversão é atribuída mas a comissão não tem como ser calculada.

await repass.programs.commissionRules.create(program.id, {
  type: "percentage",
  percentage: 10, // 10%
  recurrence: { kind: "one_time" },
});

Crie e aprove um afiliado

O Afiliado é criado dentro de um programa. Com mode: "invite" e approvalMode: "manual", ele nasce pending.

const affiliate = await repass.affiliates.create(program.id, {
  name: "Parceiro Exemplo",
  email: "[email protected]",
  mode: "invite",
});

await repass.affiliates.approve(affiliate.id);

A aprovação muda pending → approved e cria automaticamente um Link default para o afiliado.

Gere um link rastreável

const link = await repass.links.create(affiliate.id, {
  destinationUrl: "https://app.exemplo.com/signup",
  subId: "newsletter",
});

// O afiliado divulga: https://api.userepass.com/t/{link.token}
console.log(`https://api.userepass.com/t/${link.token}`);

Registre uma conversão server-to-server

Quando a venda acontece, registre a Conversão. A API roda atribuição + fraude de forma síncrona e retorna o envelope { attributed, deduplicated, replayed, conversion }.

const result = await repass.conversions.create({
  sourceEventId: "order_8842", // torna a chamada idempotente por fato de negócio
  type: "one_time_purchase",
  amountCents: 9990,
  customer: { id: "cus_8842", email: "[email protected]" },
  visitorId: "vis_01J9Z3P9T4UG0N6XE3ZQ5ALVDH",
});

if (result.attributed && result.conversion) {
  console.log("Conversão atribuída:", result.conversion.id);
} else {
  console.log("Sem afiliado atribuído: nada persistido.");
}

Pelo menos um identificador de matching é exigido (clickId, visitorId, emailHash, fingerprint, couponCode ou customer.email). Atribuição, regra e fraude são congeladas em snapshots na conversão. Detalhes no guia de conversões S2S.

Consulte a comissão gerada

Uma conversão atribuída gera automaticamente a Comissão do primeiro ciclo.

const { data } = await repass.commissions.list({
  conversion_id: result.conversion!.id,
});

console.log(data[0]?.amountCents, data[0]?.status); // 999 'pending'

Pronto: você registrou uma venda e o Repass calculou a comissão do afiliado, tudo tipado, com retries e idempotência por baixo dos panos.

Continue

Paginação

await numa página ou for await em todas.

Erros

Estreite RepassNotFoundError, RepassRateLimitError e cia.

Recursos e métodos

Todos os repass.<recurso> e seus métodos.

Idempotência & retries

idempotencyKey por requisição e política de retentativa.

​Pré-requisitos

​Fluxo completo

​Continue

Paginação

Erros

Recursos e métodos

Idempotência & retries

Pré-requisitos

Fluxo completo

Continue