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

# Controlar a cobrança

> Defina se uma instância está em teste ou em cobrança

**`PATCH /api/instance/billing/:instance`**

Define o modo de cobrança de uma instância. Use para pular o teste e cobrar desde já. A troca é de mão única: uma vez em cobrança, a instância não volta para teste. Autentique com o **TokenAccount** da conta, o mesmo que você usa para criar e administrar instâncias.

## Modos de cobrança

| `billingMode` | O que faz |
| - | - |
| `trial` | Modo padrão de uma instância nova. A instância ganha os dias de teste do seu contrato a partir da primeira conexão. |
| `billable` | Cobra a instância desde já, sem dias grátis. Útil para um cliente que já testou antes e está voltando. |

<Warning>
  A mudança para `billable` é definitiva. Uma instância em cobrança não pode voltar para `trial`, a API responde 400.
</Warning>

## Exemplo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://ryzeapi.cloud/api/instance/billing/minha-instancia" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{"billingMode": "billable"}'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/billing/minha-instancia", {
    method: "PATCH",
    headers: {
      "token": process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ billingMode: "billable" })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.patch(
      "https://ryzeapi.cloud/api/instance/billing/minha-instancia",
      headers={
          "token": os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={"billingMode": "billable"}
  )
  ```
</CodeGroup>

## Resposta de sucesso

```json 200 OK theme={null}
{
  "billingMode": "billable"
}
```

A resposta confirma o modo que ficou vigente na instância.

## Path parameters

<ParamField path="instance" type="string" required>
  Nome da instância.
</ParamField>

## Headers

<ParamField header="token" type="string" required>
  O seu TokenAccount, o mesmo que você usa para criar e administrar instâncias.
</ParamField>

## Body

<ParamField body="billingMode" type="string" required>
  Um de `trial` ou `billable`. Uma vez `billable`, a instância não pode voltar para `trial`.
</ParamField>

## O que acontece em cada mudança

<AccordionGroup>
  <Accordion title="Para billable" icon="circle-dollar-to-slot">
    A instância passa a ser cobrada a partir de agora. Se ela já estiver conectada, o valor comprometido do ciclo começa a contar neste momento e vai até a renovação, mesmo que você delete a instância antes.
  </Accordion>

  <Accordion title="Para trial" icon="hourglass-start">
    Só vale enquanto a instância ainda não entrou em cobrança. Uma instância que já é `billable` não volta para teste, a API responde 400. O teste segue as regras do seu contrato e o histórico do número.
  </Accordion>
</AccordionGroup>

## Erros

| HTTP | `error` | Quando |
| :-: | - | - |
| 400 | `billingMode obrigatorio` | O corpo não trouxe o campo `billingMode`. |
| 400 | `billingMode invalido (trial\|billable)` | Valor fora dos dois aceitos. |
| 400 | `instancia billable nao pode voltar para trial` | A instância já está em cobrança e não pode voltar para teste. |
| 401 | `Invalid token` | Token ausente ou inválido. |
| 403 | `Instance does not belong to your account` | A instância não é da sua conta. |
| 404 | `instance not found` | Nome não existe. |

## Próximo

<CardGroup cols={2}>
  <Card title="Como a cobrança funciona" icon="calculator" href="/pt/enterprise/how-billing-works">
    Entenda o crédito, o teste e a medição por dia.
  </Card>

  <Card title="Webhooks Enterprise" icon="webhook" href="/pt/enterprise/webhooks">
    Reaja a cada virada de estado por evento.
  </Card>
</CardGroup>


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