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

# Publicar condições do programa

> Publica a oferta do produto para próximas adesões.

Use uma API key da organização dona do programa com escopo de escrita. O produto precisa estar ativo. Envie **todas as condições** e a `version` obtida na consulta. A primeira publicação usa `version: 0`. Publicar também ativa o programa.

Por exemplo, o Studio publica 20% nas três primeiras faturas. Sandy aceita. Uma publicação posterior de 15% vale para novas adesões; o acordo aceito por Sandy continua em 20%.

Se outra pessoa alterar as condições antes de sua publicação, a API responde `409`. Consulte o programa novamente, confira as condições e só então envie outra publicação com a versão atual. Reenviar as mesmas condições não cria outra versão.

**id** `string` *required*

ID do programa.

**admission\_mode** `string` *required*

`invite_only`, `manual` ou `automatic`.

**affiliate\_fee\_rate** `integer` *required*

De 1 a 10000 pontos-base. `2000` representa 20%.

**attribution\_window\_days** `integer` *required*

Prazo da indicação, de 1 a 180 dias.

**recurrence\_limit** `integer | null`

Obrigatório e positivo quando `recurrence_mode` é `limited`, até 2147483647. Nos demais modos, omita ou envie `null`.

**recurrence\_mode** `string` *required*

`first`, `all` ou `limited`.

**version** `integer` *required*

Versão recebida na última consulta; `0` antes da primeira publicação.

Use uma `Idempotency-Key` diferente para cada operação que deseja executar.

```bash cURL theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/affiliate-programs/afp_7Dk9mQ2vX5rT8pWN/publish" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: programa-produto-001" \
  -d '{"admission_mode":"manual","affiliate_fee_rate":2000,"attribution_window_days":30,"recurrence_limit":3,"recurrence_mode":"limited","version":0}'
```

```json 200 theme={"theme":"css-variables"}
{
  "id": "afp_7Dk9mQ2vX5rT8pWN",
  "object": "affiliate_program",
  "admission_mode": "manual",
  "affiliate_fee_rate": 2000,
  "attribution_window_days": 30,
  "created_at": "2026-10-27T12:00:00Z",
  "livemode": true,
  "metadata": {},
  "product": "prod_7Dk9mQ2vX5rT8pWN",
  "recurrence_limit": 3,
  "recurrence_mode": "limited",
  "status": "active",
  "updated_at": "2026-10-27T12:00:00Z",
  "version": 1
}
```

```json 400 theme={"theme":"css-variables"}
{
  "error": {
    "code": "invalid_request",
    "message": "affiliate_fee_rate must be an integer from 1 to 10000 basis points.",
    "param": "affiliate_fee_rate",
    "type": "invalid_request_error"
  }
}
```

```json 403 theme={"theme":"css-variables"}
{
  "error": {
    "code": "permission_denied",
    "message": "You cannot manage this affiliate program.",
    "type": "invalid_request_error"
  }
}
```

```json 404 theme={"theme":"css-variables"}
{
  "error": {
    "code": "resource_missing",
    "message": "Affiliate program not found.",
    "type": "invalid_request_error"
  }
}
```

```json 409 theme={"theme":"css-variables"}
{
  "error": {
    "code": "affiliate_program_changed",
    "message": "The program changed. Reload its current version before publishing.",
    "type": "invalid_request_error"
  }
}
```

## Exemplos de duração

| Intenção | `recurrence_mode` | `recurrence_limit` |
| - | - | - |
| Somente a primeira fatura positiva | `first` | `null` |
| Todas as faturas positivas enquanto o acordo estiver ativo | `all` | `null` |
| As três primeiras faturas positivas emitidas | `limited` | `3` |

## Erros

| Código | Quando acontece | Como corrigir |
| - | - | - |
| `authentication_failed` | A chave não é válida | Confira a chave enviada |
| `permission_denied` | A chave não tem acesso à organização ou à operação | Confira os escopos e a organização |
| `resource_missing` | O programa ou produto não existe no modo e na organização da chave | Confira o ID e use a chave correspondente |
| `invalid_request` | Um campo ou uma combinação de condições é inválida | Corrija o campo indicado em `param` |

`affiliate_program_changed` indica conflito de versão e exige nova consulta antes de publicar.

## Chargefy for Platforms

> [!WARNING]
>
> Esta seção só se aplica a contas com o produto **Chargefy for Platforms** habilitado. Nesse produto, uma plataforma opera pagamentos para **suas organizações conectadas**.

Use a chave da plataforma e o header `Organization` com o ID da organização conectada dona do produto. A organização conectada precisa estar ativa na sua rede. O programa continua pertencendo à organização conectada e ao modo da chave.


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