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

# Autenticação

> Como autenticar na API da Noxpay.

## URL base

```
https://checkout.noxpay.io
```

## Autenticação

Toda requisição à API deve incluir sua chave de API no header `api-key`:

```http theme={null}
api-key: <key>
```

Sua chave de API está disponível no dashboard da Noxpay em **Configurações → Chaves de API**.

A chave identifica sua conta, e sua conta delimita toda requisição: leituras são filtradas para suas próprias transações e escritas são registradas na sua conta. Não há como alcançar dados de outra conta.

<Warning>
  Nunca exponha sua chave de API em código client-side. Todas as requisições à API da Noxpay devem partir do seu backend.
</Warning>

<Note>
  A chave de API autentica sua conta — ela não restringe quais operações podem ser executadas. Não existe chave de API somente leitura: qualquer chave válida pode criar um checkout ou aceitar uma conversão. Trate toda chave como acesso total e faça o controle de permissões na sua própria camada.
</Note>

Toda resposta autenticada carrega o header `X-API-Version` com a tag do build atual.

## Formato da requisição

Todo endpoint `POST` rejeita campos desconhecidos. Uma chave extra ou com erro de digitação no corpo retorna `400`, em vez de ser ignorada silenciosamente — então uma requisição que funcionava não passa a se comportar de outro jeito depois que um campo é renomeado.

Query params se comportam ao contrário: um parâmetro não reconhecido em um `GET` é ignorado, e um valor inválido para um parâmetro conhecido em geral é descartado, não rejeitado. Veja as páginas de cada endpoint para os detalhes.

## Códigos de status

| Status HTTP | Significado                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `200`       | Sucesso — inclusive na criação de recurso. Nenhum endpoint devolve `201`                                               |
| `202`       | Somente em `POST /v2/rfq/accept`: ainda em avaliação, **não** é um aceite                                              |
| `400`       | JSON inválido, campo desconhecido, campo obrigatório ausente, ou valor fora do conjunto permitido                      |
| `401`       | Chave de API ausente ou inválida                                                                                       |
| `404`       | Rotas de registro único: não existe, **ou** pertence a outra conta — os dois casos são deliberadamente indistinguíveis |
| `405`       | Método não registrado para aquela rota                                                                                 |
| `409`       | Somente em `POST /v2/rfq/accept`: a cotação expirou e foi renovada                                                     |
| `410`       | Somente em `POST /v2/rfq/accept`: a janela de renovação foi encerrada                                                  |
| `422`       | Somente em `POST /v2/rfq/accept`: recusado                                                                             |
| `500`       | Erro interno                                                                                                           |
| `503`       | Somente em `POST /v2/rfq/accept`: o fornecedor de cotação está indisponível e nada foi decidido                        |

## Responses de erro

**O formato do corpo de erro não é uniforme, então ramifique pelo status HTTP, não pelo corpo.** Existem três formas:

1. Um objeto JSON, com o tipo correto — os endpoints de conversão:

   ```json theme={null}
   { "error": "from_currency is required" }
   ```

   Em uma recusa, `POST /v2/rfq/accept` devolve o objeto de resposta completo, carregando `state` e `reason`.

2. Um objeto JSON enviado com `Content-Type: text/plain` — `POST /v2/crossramp_checkout`. O corpo é JSON apesar do header, então interprete o corpo e ignore o content type.

3. **Nenhum corpo** — as rotas `GET` de registro único e de lista escrevem apenas a linha de status em `401`, `404` e `500`.

Trate o corpo de erro como enriquecimento opcional. Um cliente robusto decide o que aconteceu pelo código de status e depois lê o corpo, se houver.