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

# Versionamento de API

> Como sua integração é protegida contra mudanças de contrato, e como testar uma nova versão antes de migrar.

<Note>
  Sua conta é **fixada (pinada)** em uma versão de contrato da API. Isso significa que sua integração nunca muda de comportamento sem que você decida migrar — mesmo quando lançamos novas versões.
</Note>

## Como funciona

Cada conta possui uma versão de API associada, identificada por uma data (ex.: `2025-01-01`). Toda requisição é respondida de acordo com a versão da sua conta, a menos que você explicite outra versão na própria requisição.

Isso garante que:

* **Integrações existentes nunca quebram** quando lançamos uma mudança de contrato (formato de resposta, novos campos obrigatórios, etc.)
* **Novas contas** já nascem na versão mais recente
* Você pode **testar uma versão nova** antes de migrar sua conta para ela

## Sobrescrevendo a versão por requisição

Use o header `X-Api-Version` para testar uma versão diferente da qual sua conta está fixada, sem afetar as demais requisições:

```bash theme={null}
curl -X GET "https://api.rivopay.com/charge/:id" \
  -H "X-API-KEY: cpk_sandbox_sua_chave_aqui" \
  -H "X-Api-Version: 2026-08-16" \
  -H "Content-Type: application/json"
```

```javascript theme={null}
const apiKey = 'cpk_sandbox_sua_chave_aqui';

fetch('https://api.rivopay.com/charge/:id', {
  method: 'GET',
  headers: {
    'X-API-KEY': `${apiKey}`,
    'X-Api-Version': '2026-08-16',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

Se o header não for enviado, a requisição usa a versão fixada na sua conta.

<Warning>
  Enviar um valor de versão desconhecido retorna `400 Bad Request` com o código de erro `invalid_api_version`, listando as versões válidas. Nenhuma requisição é processada com uma versão inexistente.
</Warning>

## Formato da resposta por versão

Na versão `2025-01-01`, cada endpoint responde no seu formato próprio (o corpo cru do recurso):

```json theme={null}
{
  "id": "charge_123",
  "correlationID": "abc-123",
  "value": 1000,
  "status": "ACTIVE"
}
```

A partir da versão `2026-08-16`, toda resposta é envelopada em um formato único, independente do endpoint:

```json theme={null}
{
  "status": 200,
  "message": "OK",
  "data": {
    "id": "charge_123",
    "correlationID": "abc-123",
    "value": 1000,
    "status": "ACTIVE"
  },
  "errors": []
}
```

O mesmo vale para erros — na versão `2026-08-16` eles também seguem esse envelope, com `data: null` e o detalhe do erro em `errors`:

```json theme={null}
{
  "status": 400,
  "message": "Valor inválido",
  "data": null,
  "errors": [
    { "code": "invalid_value", "description": "Valor inválido" }
  ]
}
```

## Changelog de versões

| Versão       | Descrição                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------- |
| `2025-01-01` | Contrato inicial — respostas cruas por endpoint (DTO/array), formato de erro legado.      |
| `2026-08-16` | Envelope de resposta unificado `{ status, message, data, errors }` em todos os endpoints. |

## Migrando sua conta para uma nova versão

<Note>
  A mudança da versão fixada na sua conta é feita hoje com o suporte da nossa equipe — ainda não há um botão de autoatendimento no painel administrativo para isso.
</Note>

Recomendamos o seguinte fluxo antes de migrar:

1. **Teste a nova versão** enviando o header `X-Api-Version` em requisições de sandbox
2. **Valide sua integração** contra o novo formato de resposta
3. **Entre em contato com o suporte** para migrar sua conta de forma definitiva

## Suporte

Dúvidas sobre versionamento ou sobre qual versão sua conta está usando:

* **Email**: [contato@clickpay.app.br](mailto:contato@clickpay.app.br)
* **Chat**: Disponível no painel de controle