> ## Documentation Index
> Fetch the complete documentation index at: https://fortal-pay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenções da API

> Autenticação, headers, envelopes, paginação e formatos da API pública.

## Headers obrigatórios

Todas as requisições usam estes headers:

```http theme={null}
Authorization: ApiKey <api_key>
```

O esquema `ApiKey` diferencia maiúsculas de minúsculas e deve ser seguido por um único espaço e pela chave completa.

## Ambientes

O prefixo da chave determina o ambiente usado na autenticação:

| Prefixo         | Ambiente |
| --------------- | -------- |
| `fpay_sk_test_` | Sandbox  |
| `fpay_sk_live_` | Produção |

A chave, o merchant e a conta do provedor precisam pertencer ao mesmo ambiente. Chaves revogadas, expiradas ou associadas a um merchant desabilitado são rejeitadas.

## Envelope de sucesso

Respostas bem-sucedidas usam esta estrutura:

```json theme={null}
{
  "data": {},
  "success": true,
  "error": null
}
```

Em listagens, `data` contém a página retornada pelo Spring Data. Em consultas individuais, `data` contém o Produto ou Cupom. A criação de Cliente retorna o cliente em `data`, enquanto a criação de cobrança retorna os dados do pagamento Pix.

## Envelope de erro

Erros tratados pelo backend seguem a mesma estrutura, com `data` nulo e detalhes em `error`:

```json theme={null}
{
  "data": null,
  "success": false,
  "error": {
    "timestamp": "<date_time>",
    "status": 404,
    "message": "Recurso não encontrado",
    "path": "<request_path>",
    "fields": null
  }
}
```

<Note>
  As mensagens de erro atuais são retornadas em português pelo backend.
</Note>

## Paginação

As listagens aceitam os parâmetros nativos do Spring Data:

| Parâmetro | Tipo      | Comportamento                                                         |
| --------- | --------- | --------------------------------------------------------------------- |
| `page`    | integer   | Página baseada em zero.                                               |
| `size`    | integer   | Quantidade solicitada por página.                                     |
| `sort`    | string\[] | Aceito pelo binding HTTP, mas o serviço aplica sua própria ordenação. |

Produtos são ordenados pelo ID interno em ordem decrescente. Cupons, Clientes e Cobranças são ordenados pela data de criação em ordem decrescente. As listagens de Clientes e Cobranças limitam o tamanho efetivo da página a 100.

## Valores e datas

<AccordionGroup>
  <Accordion title="Preço de produto">
    `price` é retornado em reais, sempre convertido do valor armazenado em centavos para duas casas decimais.
  </Accordion>

  <Accordion title="Valor do cupom">
    Na entrada, `FIXED_AMOUNT.value` é enviado em centavos. Na resposta, ele é convertido para reais com duas casas decimais. Em `PERCENTAGE`, permanece um percentual inteiro.
  </Accordion>

  <Accordion title="Valores da cobrança">
    `amount`, `fee_amount` e `net_amount` são valores decimais em reais. A criação de cobrança também retorna `amount` em reais.
  </Accordion>

  <Accordion title="Datas">
    Datas devolvidas pelo backend são serializadas em ISO-8601 com o offset de `America/Sao_Paulo`. Campos opcionais podem ser `null`.
  </Accordion>
</AccordionGroup>