# Introdução

O que a API faz, como está organizada e o caminho mais curto para a primeira cobrança.

A API da Novex é **REST sobre HTTPS**: recebe e devolve JSON, autentica por chave e usa os códigos HTTP com o significado que você já espera. Com ela você cobra por **PIX**, **boleto** e **cartão de crédito** direto do seu sistema — e-commerce, ERP, aplicativo ou o que você tiver.

`BASE https://novexfinance.com.br/api/v1`

- [Autenticação](https://novexfinance.com.br/docs/autenticacao) — Gere sua chave e faça a primeira chamada autenticada.
- [Primeira cobrança](https://novexfinance.com.br/docs/primeiros-passos) — Do zero ao PIX pago, com código pronto.
- [Webhooks](https://novexfinance.com.br/docs/webhooks) — Saiba na hora quando um pagamento é confirmado.
- [Referência](https://novexfinance.com.br/docs/referencia) — Todos os endpoints, campos e respostas.

## O que dá para fazer

| Recurso | Endpoint | Para quê |
| --- | --- | --- |
| **Cobranças** | `/v1/charges` | Criar cobrança PIX, boleto ou cartão e acompanhar o pagamento. |
| **Checkout** | `/v1/checkouts` | Gerar uma página de pagamento pronta e receber por qualquer meio, sem construir tela. |
| **Saldo** | `/v1/balance` | Consultar quanto está disponível e quanto ainda vai liquidar. |
| **Saques** | `/v1/withdrawals` | Transferir o saldo para uma chave PIX sua. |
| **Webhooks** | `/v1/webhooks` | Cadastrar a URL que recebe os eventos de pagamento em tempo real. |

## Como escolher o caminho

Há dois jeitos de receber, e a diferença prática é *quem monta a tela de pagamento*:

### Cobrança direta (API)

Você chama `POST /v1/charges` e recebe os dados brutos: o código copia e cola do PIX, a linha digitável do boleto. A tela é sua — você decide como e onde exibir. É o caminho para quem já tem checkout próprio.

### Checkout hospedado

Você chama `POST /v1/checkouts` e recebe uma **URL**. Redirecione o cliente para lá e nós cuidamos do resto: escolha do meio de pagamento, formulário, validação e confirmação. É o caminho mais rápido para começar — e o único recomendado para **cartão de crédito**, porque os dados do cartão nunca passam pelo seu servidor.

> ✅ **Cartão sem PCI-DSS.** Receber número de cartão no seu próprio servidor exige certificação PCI-DSS. Com o checkout hospedado, esse dado nunca chega até você — e a exigência deixa de existir. Veja [Cartão de crédito](https://novexfinance.com.br/docs/cartao).

## Formato das respostas

Toda resposta é JSON com `Content-Type: application/json; charset=utf-8`. Objetos trazem o campo `object` dizendo o que são, e listagens vêm dentro de `data`:

_Objeto_

```json
{
  "object": "charge",
  "id": "ch_9f2a71c4e8b35d06a147",
  "status": "pending",
  "amount": 12990,
  "currency": "BRL",
  "payment_method": "pix"
}
```

_Listagem_

```json
{
  "object": "list",
  "data": [
    // … objetos
  ],
  "has_more": true,
  "limit": 25,
  "offset": 0
}
```

Erros seguem um formato único, com um `code` estável para você programar em cima. Detalhes em [Erros](https://novexfinance.com.br/docs/erros).

_Erro_

```json
{
  "error": {
    "code": "validation_error",
    "message": "Um campo está inválido. Veja "fields".",
    "fields": {
      "customer.document": "CPF inválido."
    },
    "request_id": "a3f1c09b7e42d85610fb2c7d9a4e5b83"
  }
}
```

## Antes de integrar

1. Ter uma [conta Novex](https://novexfinance.com.br/app/register) ativa.
2. Concluir a **verificação de identidade** no painel. Sem ela, consultas funcionam mas cobranças e saques respondem `kyc_required`.
3. Gerar uma [chave de API](https://novexfinance.com.br/app/api-keys).

Confira a qualquer momento se a conta já pode transacionar:

_Requisição_

```bash
curl https://novexfinance.com.br/api/v1/account \
  -H "Authorization: Bearer $NOVEX_API_KEY"
```

_Resposta_

```json
{
  "object": "account",
  "id": "acct_42",
  "name": "Loja Exemplo LTDA",
  "status": "active",
  "verification_status": "approved",
  "can_transact": true
}
```


---

Documentação completa: https://novexfinance.com.br/docs
Base da API: https://novexfinance.com.br/api/v1