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

# Visão geral da NyxPag API

> Base URL, autenticação, formato de resposta, paginação, IDs, limites e o mapa de todos os endpoints da NyxPag API v1.

Uma API REST sobre JSON, um formato de resposta e uma forma de autenticar. Esta página junta o que vale para **todos** os endpoints, para você não precisar redescobrir em cada um.

**Base URL:** `https://api.nyxpag.com.br/v1`

Toda requisição autenticada leva o header:

```http theme={"dark"}
Authorization: Bearer nyx_live_sua_chave
```

<Info>
  A API se descreve sozinha. `GET /v1` devolve o resumo dos endpoints, `GET /v1/openapi.json` entrega a especificação OpenAPI 3.1 e `GET /v1/llms.txt` traz um resumo em texto para agentes de IA. Nenhum deles exige autenticação.
</Info>

## Convenções

<AccordionGroup>
  <Accordion title="Dinheiro vai em reais, com casas decimais" defaultOpen icon="banknote">
    `149.90` é R\$ 149,90. Não há valores em centavos inteiros na API pública: `amount`, `fee`, `netAmount`, `available` e `reserved` são sempre reais decimais.

    ```json theme={"dark"}
    { "amount": 149.9, "fee": 0.5, "netAmount": 149.4 }
    ```

    A única moeda é `BRL`.
  </Accordion>

  <Accordion title="O formato de sucesso" icon="circle-check">
    Toda resposta de sucesso tem `success: true`, os dados em `data` e um `requestId`:

    ```json theme={"dark"}
    {
      "success": true,
      "data": { },
      "requestId": "req_01H..."
    }
    ```

    Em criações (`POST`) há também `idempotent` (`true` quando é uma repetição) e, às vezes, `warning`.
  </Accordion>

  <Accordion title="Erro tem sempre a mesma forma" icon="triangle-alert">
    ```json theme={"dark"}
    {
      "success": false,
      "error": { "code": "invalid_request", "message": "Texto em português" },
      "requestId": "req_01H..."
    }
    ```

    Decida pelo `error.code`, que é estável, e não pela `message`, que pode mudar. Todos os códigos estão em [Erros](/guides/erros).
  </Accordion>

  <Accordion title="requestId: o número do protocolo" icon="hash">
    Toda resposta, de sucesso ou erro, traz um `requestId`. Guarde nos seus logs: é o que o suporte pede para achar a requisição.
  </Accordion>

  <Accordion title="O prefixo do ID diz o que é" icon="fingerprint">
    | Prefixo | Recurso |
    | - | - |
    | `txn_` | Cobrança Pix |
    | `out_` | Transferência Pix |
    | `med_` | Contestação MED |
    | `evt_` | Evento de webhook de transação |
    | `nyx_live_` | API Key |
  </Accordion>

  <Accordion title="Paginação" icon="list">
    As listagens aceitam `page` (a partir de 1) e `limit` (de 1 a 100, padrão 20) e devolvem `pagination`:

    ```json theme={"dark"}
    { "pagination": { "page": 1, "limit": 20, "total": 42, "pages": 3 } }
    ```

    Vale para [`GET /transactions`](/api-reference/transações/listar-transações) e [`GET /meds`](/api-reference/med/listar-contestações-med).
  </Accordion>

  <Accordion title="Datas" icon="calendar">
    Sempre ISO 8601 em UTC, por exemplo `2026-10-03T14:00:00.000Z`. Converta para o fuso do usuário na sua tela.
  </Accordion>

  <Accordion title="Idempotência nas operações financeiras" icon="repeat">
    `POST /transactions` e `POST /transfers` exigem `Idempotency-Key` (cabeçalho) ou `externalId` (corpo). Repetir a mesma chave com o mesmo corpo devolve a operação original, sem duplicar. Veja [Idempotência](/guides/idempotencia).
  </Accordion>

  <Accordion title="Versão da API" icon="tag">
    Toda resposta traz o cabeçalho `X-NyxPag-Version`. A versão atual da v1 é `1.1.0`. Mudanças relevantes ficam no [Changelog](/guides/ajuda/changelog).
  </Accordion>
</AccordionGroup>

## Códigos de resposta

| Código | Quando |
| - | - |
| `200` | Consulta ok, ou repetição idempotente de uma criação |
| `201` | Cobrança ou transferência criada agora |
| `202` | Operação recebida e em reconciliação. **Não** é confirmação |
| `400` | Dados inválidos |
| `401` | API Key ausente, inválida ou revogada |
| `403` | Sem permissão, IP não autorizado ou conta sem verificação |
| `404` | Não encontrado |
| `409` | Conflito de idempotência |
| `422` | Operação recusada por regra de negócio |
| `429` | Passou de 100 requisições por 60 segundos |
| `5xx` | Erro do nosso lado. Tente de novo com a mesma chave de idempotência |

## O mapa

| Grupo | Endpoint | Permissão | Guia |
| - | - | - | - |
| Saldo | `GET /balance` | `balance:read` | [Saldo](/guides/pix/saldo) |
| Pagamentos | `POST /transactions` | `payments:write` | [Receber por Pix](/guides/pix/receber) |
| Transações | `GET /transactions` | `transactions:read` | [Acompanhar](/guides/pix/acompanhar) |
| Transações | `GET /transactions/{id}` | `transactions:read` | [Acompanhar](/guides/pix/acompanhar) |
| Transferências | `POST /transfers` | `transfers:write` | [Transferir por Pix](/guides/pix/transferir) |
| MED | `GET /meds` | `transactions:read` | [Contestações](/guides/disputas/med) |
| MED | `GET /meds/{id}` | `transactions:read` | [Contestações](/guides/disputas/med) |
| Transparência | `GET /transparency` | pública | [Transparência](/guides/transparencia) |

## Limites que valem lembrar

| O quê | Limite |
| - | - |
| Requisições | 100 por janela de 60 segundos, por API Key, somando todas as rotas e o MCP |
| Valor de uma cobrança | De R\$ 1,00 a R\$ 10.000,00 |
| Valor mínimo de transferência | R\$ 3,00 |
| Chave de idempotência | Até 100 caracteres: letras, números e `. _ : / -` |
| Descrição | Até 140 caracteres |
| Recebedores de split | Até 10 por venda |
| Validade do Pix | 15 minutos |

<Note>
  Os valores mínimos e máximos refletem a especificação OpenAPI atual e podem ser ajustados pela NyxPag por conta. A fonte de verdade é sempre [`/v1/openapi.json`](https://api.nyxpag.com.br/v1/openapi.json).
</Note>

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key-round" href="/guides/autenticacao">
    Como enviar a chave, permissões e boas práticas.
  </Card>

  <Card title="Referência da API" icon="code" href="/api-reference/pagamentos/criar-cobrança-pix">
    Cada endpoint com parâmetros, respostas e exemplos.
  </Card>
</CardGroup>


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