# Referência de endpoints

Todos os endpoints, campos de entrada e campos de resposta.

Todos os endpoints da API v1 em uma página. Base: `https://novexfinance.com.br/api/v1`. Todos exigem o header `Authorization: Bearer <chave>`.

## Índice

| Método | Endpoint | O que faz |
| --- | --- | --- |
| `GET` | [`/v1/ping`](#ping) | Verifica a chave. |
| `GET` | [`/v1/account`](#account) | Dados da conta. |
| `POST` | [`/v1/charges`](#charges-create) | Cria cobrança PIX, boleto ou cartão. |
| `GET` | [`/v1/charges`](#charges-list) | Lista cobranças. |
| `GET` | [`/v1/charges/{id}`](#charges-show) | Consulta uma cobrança. |
| `POST` | [`/v1/checkouts`](#checkouts-create) | Cria checkout hospedado. |
| `GET` | [`/v1/checkouts`](#checkouts-list) | Lista checkouts. |
| `GET` | [`/v1/checkouts/{id}`](#checkouts-show) | Consulta um checkout. |
| `POST` | [`/v1/checkouts/{id}/expire`](#checkouts-expire) | Encerra um checkout. |
| `GET` | [`/v1/balance`](#balance) | Saldo disponível e a liquidar. |
| `POST` | [`/v1/withdrawals`](#withdrawals-create) | Solicita saque via PIX. |
| `GET` | [`/v1/withdrawals`](#withdrawals-list) | Lista saques. |
| `GET` | [`/v1/withdrawals/{id}`](#withdrawals-show) | Consulta um saque. |
| `POST` | [`/v1/webhooks`](#webhooks-create) | Cadastra endpoint de webhook. |
| `GET` | [`/v1/webhooks`](#webhooks-list) | Lista endpoints. |
| `DELETE` | [`/v1/webhooks/{id}`](#webhooks-delete) | Remove endpoint. |
| `GET` | [`/v1/webhook-deliveries`](#deliveries) | Histórico de entregas. |

---

## Conta

### Verificar a chave

`GET /v1/ping`

Sem parâmetros. Devolve `authenticated`, `account_id`, `server_time` e `api_version`.

### Dados da conta

`GET /v1/account`

_Resposta 200_

```json
{
  "object": "account",
  "id": "acct_42",
  "name": "Loja Exemplo LTDA",
  "email": "contato@exemplo.com.br",
  "document": "11222333000181",
  "person_type": "pj",
  "status": "active",
  "verification_status": "approved",
  "can_transact": true
}
```

`can_transact` resume o que importa: `false` significa que cobranças e saques vão responder `kyc_required` ou `account_inactive`.

---

## Cobranças

### Criar cobrança

`POST /v1/charges`

Aceita `Idempotency-Key`. Guias por meio: [PIX](https://novexfinance.com.br/docs/pix), [boleto](https://novexfinance.com.br/docs/boleto), [cartão](https://novexfinance.com.br/docs/cartao).

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `payment_method` obrigatório | string | `pix`, `boleto` ou `credit_card`. |
| `amount` obrigatório | inteiro | Centavos. Mínimo `500`. |
| `description` opcional | string | Até 200 caracteres. Padrão: `"Cobrança"`. |
| `reference` opcional | string | Seu identificador, até 191 caracteres. |
| `metadata` opcional | objeto | Até 30 chaves; valores de texto, número ou booleano. |
| `customer.name` obrigatório | string | Mínimo 3 caracteres. |
| `customer.email` obrigatório | string | E-mail válido. |
| `customer.phone` obrigatório | string | DDD + número (10 ou 11 dígitos). |
| `customer.document` obrigatório | string | CPF ou CNPJ, com dígito verificador válido. |
| `installments` opcional | inteiro | Só para cartão. De 1 a 12. Padrão: 1. |
| `card.number` opcional | string | Só para cartão direto (requer PCI-DSS). |
| `card.holder_name` opcional | string | Só para cartão direto. |
| `card.holder_document` opcional | string | Só para cartão direto. |
| `card.expiration_month` opcional | inteiro | Só para cartão direto. 1 a 12. |
| `card.expiration_year` opcional | inteiro | Só para cartão direto. 2 dígitos. |
| `card.cvv` opcional | string | Só para cartão direto. 3 ou 4 dígitos. |

#### Objeto charge

| Campo da resposta | Tipo | Descrição |
| --- | --- | --- |
| `id` opcional | string | ID da cobrança, prefixo `ch_`. |
| `status` opcional | string | `pending`, `processing`, `authorized`, `paid`, `failed`, `refused`, `refunded`, `chargeback`, `disputed`, `blocked`. |
| `amount` opcional | inteiro | Valor bruto em centavos. |
| `currency` opcional | string | Sempre `BRL`. |
| `payment_method` opcional | string | `pix`, `boleto` ou `credit_card`. |
| `fee_amount` opcional | inteiro | Taxa em centavos. `null` enquanto não pago. |
| `net_amount` opcional | inteiro | Líquido em centavos (bruto − taxa). |
| `available_at` opcional | data | Quando o valor fica disponível para saque. |
| `paid_at` opcional | data | Quando o pagamento foi confirmado. |
| `pix.qr_code` opcional | string | Copia e cola (EMV). Só em PIX. |
| `pix.expires_at` opcional | data | Validade do código. Só em PIX. |
| `boleto.digitable_line` opcional | string | Linha digitável (47 dígitos). Só em boleto. |
| `boleto.barcode` opcional | string | Código de barras (44 dígitos). Só em boleto. |
| `boleto.expires_at` opcional | data | Vencimento. Só em boleto. |
| `card.brand` opcional | string | Bandeira. Só em cartão. |
| `card.last4` opcional | string | Últimos 4 dígitos. Só em cartão. |
| `card.installments` opcional | inteiro | Parcelas. Só em cartão. |

### Listar cobranças

`GET /v1/charges`

| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `status` opcional | string | Filtra por status público. |
| `payment_method` opcional | string | `pix`, `boleto` ou `credit_card`. |
| `reference` opcional | string | Sua referência, exata. |
| `limit` opcional | inteiro | 1 a 100. Padrão: 25. |
| `offset` opcional | inteiro | Padrão: 0. |

### Consultar cobrança

`GET /v1/charges/{id}`

Reconcilia com o processador quando o status ainda não é final. Devolve o objeto `charge`.

---

## Checkouts

### Criar checkout

`POST /v1/checkouts`

Aceita `Idempotency-Key`. Guia completo em [Checkout hospedado](https://novexfinance.com.br/docs/checkout).

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `title` obrigatório | string | Nome do que está sendo cobrado, até 160 caracteres. |
| `amount` obrigatório | inteiro | Centavos. Mínimo `500`. |
| `description` opcional | string | Até 500 caracteres. |
| `payment_methods` opcional | lista | Subconjunto de `["pix","credit_card","boleto"]`. Padrão: os três. |
| `reference` opcional | string | Seu identificador. |
| `return_url` opcional | string | HTTPS. Para onde o cliente volta após pagar. |
| `single_use` opcional | booleano | Padrão `true`. |
| `expires_in` opcional | inteiro | Segundos, até 7776000 (90 dias). `0` desliga. |
| `metadata` opcional | objeto | Até 30 chaves. |

### Listar checkouts

`GET /v1/checkouts`

Aceita `limit` e `offset`.

### Consultar checkout

`GET /v1/checkouts/{id}`

Traz `charge` preenchido quando já houve pagamento.

### Encerrar checkout

`POST /v1/checkouts/{id}/expire`

Sem corpo. Devolve o checkout com `status: "expired"`. Um checkout já pago responde `409 checkout_already_paid`.

---

## Saldo

`GET /v1/balance`

| Campo da resposta | Tipo | Descrição |
| --- | --- | --- |
| `available` opcional | inteiro | Liquidado e livre para saque, em centavos. |
| `pending` opcional | inteiro | Pago mas ainda em prazo de liquidação. |
| `total` opcional | inteiro | Soma dos dois. |
| `as_of` opcional | data | Momento do cálculo. |

---

## Saques

### Solicitar saque

`POST /v1/withdrawals`

Aceita `Idempotency-Key`. Guia em [Saldo e saques](https://novexfinance.com.br/docs/saldo-e-saques).

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `amount` obrigatório | inteiro | Valor a receber, em centavos. Mínimo `500`. A taxa é debitada por cima. |
| `pix_key_type` obrigatório | string | `cpf`, `cnpj`, `phone`, `email` ou `evp`. |
| `pix_key` obrigatório | string | A chave PIX de destino. |
| `reference` opcional | string | Seu identificador. |

| Campo da resposta | Tipo | Descrição |
| --- | --- | --- |
| `id` opcional | string | ID do saque, prefixo `wd_`. |
| `status` opcional | string | `pending`, `approved`, `processing`, `paid`, `rejected`, `failed`, `refunded`, `canceled`, `blocked`. |
| `amount` opcional | inteiro | Valor que chega no destino. |
| `fee_amount` opcional | inteiro | Taxa cobrada. |
| `total_debited` opcional | inteiro | Valor + taxa. É o que sai do seu saldo. |
| `pix_key` opcional | string | Chave mascarada. |
| `end_to_end_id` opcional | string | Identificador da transferência PIX, quando concluída. |
| `processed_at` opcional | data | Quando foi processado. |

### Listar saques

`GET /v1/withdrawals`

Aceita `limit` e `offset`.

### Consultar saque

`GET /v1/withdrawals/{id}`

---

## Webhooks

### Cadastrar endpoint

`POST /v1/webhooks`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `url` obrigatório | string | HTTPS. Recebe os eventos. |
| `events` opcional | string | `all` (padrão), `transaction` ou `withdrawal`. |

A resposta `201` inclui `secret` — **só nesta chamada**. Guia em [Webhooks](https://novexfinance.com.br/docs/webhooks).

### Listar endpoints

`GET /v1/webhooks`

Não devolve o `secret`. Traz `consecutive_failures` e `last_status_code` para diagnóstico.

### Remover endpoint

`DELETE /v1/webhooks/{id}`

### Histórico de entregas

`GET /v1/webhook-deliveries`

Cada tentativa de entrega, com o status HTTP que o seu servidor respondeu. Aceita `limit` e `offset`.

---

## Headers

| Header | Direção | Para quê |
| --- | --- | --- |
| `Authorization` | Envio | `Bearer <chave>`. Obrigatório em todos os endpoints. |
| `Content-Type` | Envio | `application/json` em POST. |
| `Idempotency-Key` | Envio | Evita duplicidade em retentativas de POST. |
| `X-Request-Id` | Resposta | ID da requisição, para suporte. |
| `Idempotent-Replay` | Resposta | `true` quando a resposta é a repetição de uma anterior. |
| `Retry-After` | Resposta | Segundos a esperar, em `429` e `503`. |
| `Allow` | Resposta | Métodos aceitos, em `405`. |


---

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