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

# Rekomi

> Execute um programa de afiliados na sua loja Dodo Payments com a Rekomi. Uma única chave de API colada conecta as duas plataformas, e a Rekomi acompanha as vendas e paga seus afiliados.

## Introdução

[Rekomi](https://rekomi.com) é uma plataforma de gerenciamento e rastreamento de afiliados com uma integração nativa com Dodo Payments. Um afiliado compartilha um link, e a Rekomi registra o clique. Quando esse visitante compra, Dodo Payments envia a venda para a Rekomi, que atribui o crédito ao afiliado correto. A Rekomi calcula a comissão e paga seus afiliados por você, em mais de 150 países, com os formulários fiscais incluídos.

Para conectar, cole uma chave de API do Dodo Payments com acesso de gravação na Rekomi. A Rekomi valida a chave, cria o endpoint de webhook na sua conta do Dodo Payments e busca o segredo de assinatura do endpoint. Você não precisa preencher um formulário de webhook nem colar nada de volta no Dodo Payments.

> [!NOTE]
>
> A Rekomi atribui uma venda a um afiliado quando um cliente indicado conclui um pagamento único, inicia uma assinatura paga ou paga uma renovação. Reembolsos e disputas recuperam a comissão automaticamente.

## Como funciona

O Dodo Payments hospeda o checkout em seu próprio domínio, portanto a indicação do afiliado é transmitida para a venda como metadados do checkout:

1. Um visitante clica em um link de afiliado e acessa seu site, onde o script da Rekomi armazena a indicação no navegador.
2. No checkout, você associa essa indicação ao pagamento como metadados `rekomi_ref`.
3. Dodo Payments processa o pagamento e envia um webhook assinado `payment.succeeded` ao endpoint criado pela Rekomi.
4. A Rekomi associa a indicação ao afiliado, calcula a comissão sobre o valor da venda antes dos impostos e registra isso.

As renovações de assinatura chegam da mesma forma, portanto as comissões recorrentes não exigem trabalho adicional. Reembolsos e disputas também chegam pelo mesmo endpoint.

## Pré-requisitos

Antes de configurar essa integração, você precisa de:

1. Uma [conta do Dodo Payments](https://app.dodopayments.com) no modo live
2. Uma [conta da Rekomi](https://app.rekomi.com/sign-up)
3. Uma chave de API do Dodo Payments com o **acesso de gravação** habilitado, pois chaves somente leitura não podem criar webhooks

## Primeiros passos

**1. Create an API Key with Write Access**

> [!WARNING]
>
> Habilite o acesso de gravação na chave. Uma chave somente leitura passa pela validação, mas não pode criar o endpoint de webhook, então a conexão falha no meio do processo.

No dashboard do Dodo Payments, acesse **Developer → API Keys** e clique em **Add API Key**. Dê à chave o nome `Rekomi` e mantenha **Enable write access** selecionado. Para obter detalhes, consulte [Autenticação](https://docs.dodopayments.com/api-reference/introduction.md#authentication).

**2. Paste the Key into Rekomi**

Na Rekomi, abra **Setup → Connect payment processor**, escolha Dodo Payments e cole a chave. A Rekomi a valida, cria o endpoint de webhook na sua conta e busca o segredo de assinatura do endpoint.

![Página de configuração da Rekomi para Dodo Payments com o único campo de chave de API e botão de conexão](https://mintcdn.com/dodopayments/ic2bWXoH5_Rw-GN5/images/integrations/rekomi/connect.png?fit=max\&auto=format\&n=ic2bWXoH5_Rw-GN5\&q=85\&s=2271768fc16cecec3196c8006e0c73ab)

> [!NOTE]
>
> Depois que você se conecta, a Rekomi usa a chave somente para gerenciar o endpoint de webhook e executar verificações periódicas de integridade. Suas vendas chegam pelo webhook assinado, não pela API.

**3. Install the Rekomi Script**

Adicione o script de rastreamento da Rekomi ao seu site de marketing para capturar cliques de afiliados. A Rekomi exibe seu snippet, com o ID do programa preenchido, em **Setup → Install**.

```html theme={null}
<script
  async
  src="https://api.rekomi.com/api/v1/r/loader.js"
  data-program-id="YOUR_PROGRAM_ID"
></script>
```

**4. Pass the Referral into Checkout**

Associe a indicação capturada a cada pagamento como metadados `rekomi_ref`. O [Guia de implementação](#implementation-guide) mostra como fazer isso para cada tipo de checkout.

**5. Done**

Vendas, renovações, reembolsos e disputas agora atribuem e recuperam automaticamente as comissões dos afiliados, e a Rekomi paga seus afiliados.

## Guia de implementação

### Checkout Sessions via API

No frontend, leia a indicação com `window.Rekomi.getReferral()` e envie-a ao backend com a solicitação de checkout. No backend, defina-a em `metadata`:

```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';

// Reads DODO_PAYMENTS_API_KEY from the environment and defaults to live mode.
const client = new DodoPayments();

export async function createCheckout(productId: string, rekomiRef?: string) {
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    return_url: 'https://yoursite.com/success',
    metadata: {
      ...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
    },
  });

  return session.checkout_url;
}
```

O mesmo campo `metadata.rekomi_ref` funciona em produtos de assinatura, portanto a primeira cobrança e todas as renovações atribuem o crédito ao mesmo afiliado.

### Payments API

> [!NOTE]
>
> O exemplo abaixo usa `POST /payments`, que está **deprecated**. Ele ainda funciona para integrações existentes. Novas integrações devem usar [Checkout Sessions](https://docs.dodopayments.com/developer-resources/checkout-session.md) (`POST /checkouts`), que recebem `metadata` da mesma forma.

```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';

// Reads DODO_PAYMENTS_API_KEY from the environment and defaults to live mode.
const client = new DodoPayments();

export async function createPayment(productId: string, rekomiRef?: string) {
  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    product_cart: [{ product_id: productId, quantity: 1 }],
    payment_link: true,
    metadata: {
      ...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
    },
  });

  return payment;
}
```

### Links de pagamento estáticos

Adicione a indicação ao link como um parâmetro de consulta simples `metadata_rekomi_ref`, não no formato entre colchetes:

```javascript theme={null}
const ref = window.Rekomi?.getReferral?.();
let url = 'https://checkout.dodopayments.com/buy/YOUR_PRODUCT_ID';
if (ref) url += `?metadata_rekomi_ref=${encodeURIComponent(ref)}`;
// use url as the href on your Buy button
```

Dodo Payments adiciona parâmetros de consulta `metadata_*` aos metadados do pagamento, de onde a Rekomi os lê.

## O que é rastreado

A Rekomi processa cada tipo de evento de venda da seguinte forma:

| Evento | O que acontece |
| - | - |
| Pagamento único | Comissão atribuída sobre o valor da venda antes dos impostos |
| Renovação de assinatura | Comissão recorrente; cada cobrança chega como seu próprio evento de pagamento |
| Reembolso | Comissão recuperada automaticamente, até o valor atribuído |
| Disputa | Comissão recuperada assim que a disputa é aberta |

> [!TIP]
>
> A Rekomi calcula as comissões sobre o valor da venda antes dos impostos. Dodo Payments é o Merchant of Record e coleta os impostos, portanto seus afiliados ganham sobre a própria venda, não sobre o imposto adicionado pelo país do comprador.

## Observações importantes

* A Rekomi registra o endpoint de webhook exatamente com os eventos necessários. Não edite a lista de eventos desse endpoint no dashboard do Dodo Payments: as verificações de integridade da Rekomi sinalizam a conexão se os eventos forem removidos.
* Um teste gratuito não cria nenhum pagamento até o término do teste, portanto nenhuma comissão existe até a primeira cobrança. Um [teste pago](https://docs.dodopayments.com/features/subscription.md#paid-trials) cobra o valor do teste antecipadamente.
* Desconectar na Rekomi exclui o endpoint de webhook da sua conta do Dodo Payments.

## Recursos adicionais

> **[Rekomi's Dodo Payments Guide](https://rekomi.com/docs/brands/install/dodo)**
>
> O guia completo de configuração, solução de problemas e detalhes de segurança na documentação da Rekomi.

> **[Affiliates Feature Guide](https://docs.dodopayments.com/features/affiliates.md)**
>
> Todas as opções de integração de afiliados para Dodo Payments.

> [!NOTE]
>
> Para obter ajuda com a integração, entre em contato com o suporte da Rekomi pelo endereço [support@rekomi.com](mailto:support@rekomi.com) ou com o suporte do Dodo Payments pelo endereço [support@dodopayments.com](mailto:support@dodopayments.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.