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

# Crescimento

> Abra o programa de afiliados de um produto, simule a comissão, acompanhe coprodução e leia os relatórios de conversão e aprovação.

Trinta operações para a parte do negócio que não é vender: quem vende **por você** (afiliados), quem vende **com você** (coprodução), e os números que dizem se está funcionando (relatórios).

<Info>
  Os exemplos usam `$TOKEN` e o produto de [Catálogo](/guias/catalogo), `cmty05wl0000apyg1bx1566ej`, com a oferta `540`.
</Info>

## 1. Simule antes de decidir a comissão

Quanto sobra para você com 40% de comissão? A simulação responde em centavos, já descontando a taxa da plataforma:

```bash theme={null}
curl -s "https://api.ephra.io/v1/products/cmty05wl0000apyg1bx1566ej/affiliation-settings/commission-preview?offerId=540&commissionAffiliate=40" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": {
    "price": 49900,
    "platformFee": 1591,
    "withoutAffiliate": { "producerAmount": 48309 },
    "withAffiliate": {
      "affiliateAmount": 19323,
      "producerAmount": 28986
    }
  }
}
```

A conta é transparente: de R$ 499, a Ephra fica com R$ 15,91, o afiliado com R$ 193,23 e você com R$ 289,86. Sem afiliado, você ficaria com R\$ 483,09. Troque `commissionAffiliate` na query e compare os cenários antes de publicar.

## 2. Abra o programa

```bash theme={null}
curl -s -X PATCH https://api.ephra.io/v1/products/cmty05wl0000apyg1bx1566ej/affiliation-settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "acceptAffiliates": true,
    "commissionAffiliate": 40,
    "listedOnMarketplace": true
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "acceptAffiliates": true,
    "requireAffiliateApproval": false,
    "wantToReceiveEmails": false,
    "affiliateDataAccess": false,
    "listedOnMarketplace": true,
    "supportEmailAffiliate": null,
    "descriptionAffiliate": null,
    "commissionAffiliate": 40,
    "slugOfferProduct": "3pep1ni",
    "passRefundToAffiliates": false
  }
}
```

Três chaves decidem o feitio do programa:

| Campo                      | Efeito                                                             |
| -------------------------- | ------------------------------------------------------------------ |
| `requireAffiliateApproval` | `true` deixa cada pedido em `pending` até você aprovar             |
| `listedOnMarketplace`      | `true` põe o produto na vitrine pública de afiliação               |
| `passRefundToAffiliates`   | `true` desconta o reembolso também da comissão já paga ao afiliado |

<Warning>
  Com `passRefundToAffiliates: false`, um reembolso sai inteiro do seu bolso — a comissão do afiliado já foi paga e não volta. Num produto com garantia longa e comissão alta, isso muda a conta.
</Warning>

## 3. Veja quem se afiliou

```bash theme={null}
curl -s "https://api.ephra.io/v1/affiliates?page=1&pageSize=5&status=pending" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "cmtxyvy9n0000v1g1hacv48xd",
      "affiliateName": "Fixtures Empresa B",
      "productName": "Curso de Tráfego Pago",
      "commissionPercentage": 40,
      "status": "approved",
      "createdAt": "2026-09-12T05:51:19.355Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 5, "total": 1, "totalPages": 1 }
}
```

Aprovar ou bloquear é um `PATCH` com o novo estado:

```bash theme={null}
curl -s -X PATCH https://api.ephra.io/v1/affiliates/cmtxyvy9n0000v1g1hacv48xd \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved"}'
```

Os valores aceitos são `pending`, `approved`, `rejected` e `inactive`. `inactive` desliga o afiliado sem apagar o histórico de comissões dele.

## 4. Coprodução

Coprodução é sociedade num produto: o coprodutor recebe um percentual de toda venda, não por indicação.

```bash theme={null}
curl -s "https://api.ephra.io/v1/co-productions?page=1&pageSize=5" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "cmtxywzgk0002v1g1xjcyetjy",
      "productId": "cmtxxggxb0000vyg19j6v7qja",
      "productName": "Curso de Tráfego Pago",
      "producerCompanyId": "cmtxx1uar0001hlg1u3ajbj6o",
      "producerCompanyName": "Fixtures Empresa A",
      "coProducerEmail": "fixtures-company-b@public-api.invalid",
      "coProducerCompanyId": "cmtxx1ud20005hlg176hk0jqc",
      "contractPeriod": "2026-12-11T23:59:59.999Z",
      "saleProducer": true,
      "saleAffiliate": false,
      "commissionProducerPercentage": 35,
      "status": "approved",
      "createdAt": "2026-09-12T05:52:07.556Z",
      "updatedAt": "2026-09-12T05:52:18.450Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 5, "total": 1, "totalPages": 1 }
}
```

Convide por e-mail com `POST /v1/products/{productId}/co-productions`. Do outro lado, o convidado usa `/accept` ou `/reject`; você pode desistir com `/cancel` enquanto estiver pendente. `contractPeriod` é a data em que a sociedade expira sozinha.

## 5. A vitrine

```bash theme={null}
curl -s "https://api.ephra.io/v1/marketplace/products?page=1&pageSize=3" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "cmtxzmg7c0000dcg1h5modglq",
      "name": "Produto VITRINE-DONO 1789193515648-qxjnf0",
      "companyName": "Teste Empresa VITRINE-DONO 1789193515648-qxjnf0",
      "imageUrl": null,
      "price": 49900,
      "commission": 19960
    }
  ],
  "pagination": { "page": 1, "pageSize": 3, "total": 12, "totalPages": 4 }
}
```

`commission` é o que você ganharia por venda, em centavos, se se afiliasse. Para se afiliar, `POST /v1/affiliations` com o `productSlug`.

## 6. Os relatórios

Seis relatórios, todos com a mesma assinatura `?from=&to=` em ISO 8601:

| Rota                            | Responde                                                      |
| ------------------------------- | ------------------------------------------------------------- |
| `GET /v1/reports/payment`       | Aprovação e recusa de cartão, por bandeira, parcela e emissor |
| `GET /v1/reports/conversion`    | Do clique ao pago: onde o funil vaza                          |
| `GET /v1/reports/performance`   | Receita, ticket médio e evolução no período                   |
| `GET /v1/reports/risk`          | Reembolsos, contestações e o que isso custa                   |
| `GET /v1/reports/scale`         | Volume e crescimento período a período                        |
| `GET /v1/reports/card-approval` | Aprovação de cartão isolada, para diagnóstico rápido          |

```bash theme={null}
curl -s "https://api.ephra.io/v1/reports/payment?from=2026-08-01T00:00:00.000Z&to=2026-08-31T23:59:59.000Z" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": {
    "approvalRate": { "rate": 0, "goalMet": false, "changeVsPreviousPeriod": 0 },
    "refusalRate": { "rate": 0, "totalRefused": 0, "changeVsPreviousPeriod": 0 },
    "approvedTransactions": { "total": 0, "totalAmount": 0, "changeVsPreviousPeriod": 0 },
    "processedVolume": { "totalAmount": 0, "averageTicket": 0, "changeVsPreviousPeriod": 0 },
    "refusalReasons": { "totalRefused": 0, "classifiedTotal": 0, "reasons": [] },
    "approvalByBrand": { "brands": [] },
    "approvalByInstallment": { "installments": [] },
    "approvalByIssuer": { "issuers": [] },
    "approvalEvolution": {
      "changeOverPeriod": 0,
      "points": [
        { "date": "2026-07-31", "rate": 0 },
        { "date": "2026-08-01", "rate": 0 }
      ]
    }
  }
}
```

Cada bloco traz `changeVsPreviousPeriod`: a Ephra já compara com a janela anterior de mesmo tamanho, então você não precisa fazer duas chamadas para dizer "subiu 12%".

Para um panorama rápido de um período, sem cortes por bandeira, use `GET /v1/dashboard/summary`:

```json theme={null}
{
  "success": true,
  "data": {
    "grossAmount": 0,
    "netAmount": 0,
    "transactionsCount": 0,
    "paidTransactions": 0,
    "paidToday": 0,
    "averageTicket": 0,
    "refundsCount": 0,
    "refundedAmount": 0,
    "approvalRate": 0,
    "refundRate": 0,
    "lastHourNetAmount": 0,
    "approvalRateByMethod": { "pix": 0, "creditCard": 0, "boleto": 0 },
    "salesShareByMethod": {
      "pix": { "percentage": 0, "count": 0 },
      "creditCard": { "percentage": 0, "count": 0 },
      "boleto": { "percentage": 0, "count": 0 }
    }
  }
}
```

## 7. Indicações e recompensas

```bash theme={null}
curl -s https://api.ephra.io/v1/rewards/tier \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": {
    "totalTransfers": 0,
    "rewardLevel": "LEVEL_1",
    "solicitedReward": false
  }
}
```

O programa de indicação dá bônus por empresa trazida. Se a sua conta ainda não tem código, `GET /v1/referrals/link` responde `404`:

```json theme={null}
{ "success": false, "message": "Código de indicação não encontrado para esta empresa." }
```

Não é erro de integração: é a ausência do código, que nasce quando o programa é ativado para a conta.

## Todas as operações do domínio

<CardGroup cols={2}>
  <Card title="Afiliados" icon="users" href="/api-reference/crescimento/listar-afiliados">
    Programa, comissão, aprovação e links.
  </Card>

  <Card title="Coprodução" icon="handshake" href="/api-reference/crescimento/listar-coproduções">
    Convites, aceite, recusa e cancelamento.
  </Card>

  <Card title="Relatórios" icon="chart-column" href="/api-reference/crescimento/consultar-relatório-de-pagamentos">
    Pagamento, conversão, performance, risco e escala.
  </Card>

  <Card title="Marketplace e indicações" icon="store" href="/api-reference/crescimento/listar-produtos-do-marketplace">
    Vitrine pública, bônus de indicação e nível de recompensa.
  </Card>
</CardGroup>