> ## Documentation Index
> Fetch the complete documentation index at: https://userepass.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido (SDK)

> Do zero a uma comissão calculada usando o @repass/sdk em TypeScript.

Este guia espelha o [Início rápido da API](/docs/quickstart), 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

<Steps>
  <Step title="Instale o SDK e exporte a chave">
    ```bash theme={null}
    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](/docs/autenticacao).
  </Step>

  <Step title="Instancie o client">
    ```ts theme={null}
    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](/docs/sdk/configuracao).
  </Step>
</Steps>

## Fluxo completo

<Steps>
  <Step title="Crie um programa">
    Um [Programa](/docs/conceitos/programas-e-regras) define moeda, modelo/janela de [atribuição](/docs/conceitos/atribuicao), hold e modo de aprovação.

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

    <Tip>
      Crie uma [regra de comissão](/docs/conceitos/comissoes) versionada para o programa. Sem uma regra vigente, a conversão é atribuída mas a comissão não tem como ser calculada.

      ```ts theme={null}
      await repass.programs.commissionRules.create(program.id, {
        type: "percentage",
        percentage: 10, // 10%
        recurrence: { kind: "one_time" },
      });
      ```
    </Tip>
  </Step>

  <Step title="Crie e aprove um afiliado">
    O [Afiliado](/docs/conceitos/afiliados) é criado dentro de um programa. Com `mode: "invite"` e `approvalMode: "manual"`, ele nasce `pending`.

    ```ts theme={null}
    const affiliate = await repass.affiliates.create(program.id, {
      name: "Parceiro Exemplo",
      email: "parceiro@exemplo.com",
      mode: "invite",
    });

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

    A aprovação muda `pending → approved` e cria automaticamente um [Link](/docs/conceitos/links-e-cupons) default para o afiliado.
  </Step>

  <Step title="Gere um link rastreável">
    ```ts theme={null}
    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}`);
    ```
  </Step>

  <Step title="Registre uma conversão server-to-server">
    Quando a venda acontece, registre a [Conversão](/docs/conceitos/conversoes-e-fraude). A API roda atribuição + fraude de forma síncrona e retorna o envelope `{ attributed, deduplicated, replayed, conversion }`.

    ```ts theme={null}
    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: "cliente@exemplo.com" },
      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.");
    }
    ```

    <Note>
      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](/docs/guias/conversoes-server-to-server).
    </Note>
  </Step>

  <Step title="Consulte a comissão gerada">
    Uma conversão atribuída gera automaticamente a [Comissão](/docs/conceitos/comissoes) do primeiro ciclo.

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

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

    <Check>
      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.
    </Check>
  </Step>
</Steps>

## Continue

<CardGroup cols={2}>
  <Card title="Paginação" icon="layer-group" href="/docs/sdk/paginacao">
    `await` numa página ou `for await` em todas.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/docs/sdk/erros">
    Estreite `RepassNotFoundError`, `RepassRateLimitError` e cia.
  </Card>

  <Card title="Recursos e métodos" icon="table-list" href="/docs/sdk/recursos">
    Todos os `repass.<recurso>` e seus métodos.
  </Card>

  <Card title="Idempotência & retries" icon="arrows-rotate" href="/docs/sdk/configuracao">
    `idempotencyKey` por requisição e política de retentativa.
  </Card>
</CardGroup>