# Visao Geral da API

A API FluxiQ NPC permite integrar sua aplicacao com a infraestrutura de boletos da Nuclea (PCR/CMP/SILOC).

## URL Base

| Ambiente    | URL Base                                           |
|-------------|---------------------------------------------------|
| Local       | `http://localhost:4000/api/v1/central`            |
| Sandbox     | `https://sandbox.monetarie_npc.com.br/api/v1/central`|
| Producao    | `https://api.monetarie_npc.com.br/api/v1/central`    |

## Autenticacao

Todas as requisicoes devem incluir o cabecalho `X-API-Key` com sua chave de acesso:

```bash
curl -X GET "https://api.monetarie_npc.com.br/api/v1/central/health" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"
```

::: info Prefixos de API Key
- `pk_test_` - Chaves de sandbox para testes
- `pk_live_` - Chaves de producao
:::

Para mais detalhes, consulte a pagina de [Autenticacao](/authentication).

## Formato de Resposta

### Resposta de Sucesso

Todas as respostas de sucesso seguem o formato padrao:

```json
{
  "success": true,
  "data": {
    // Dados da resposta
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

### Resposta de Erro

Erros seguem o formato:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Descricao do erro",
    "details": {
      // Detalhes adicionais quando disponiveis
    }
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

::: tip Request ID
O campo `meta.request_id` e incluido em todas as respostas. Use este valor ao contatar o suporte para facilitar a investigacao de problemas.
:::

## Endpoints Disponiveis

| Metodo   | Endpoint                           | Descricao                          |
|----------|------------------------------------|------------------------------------|
| `GET`    | `/health`                          | Verificacao de saude do servico    |
| `POST`   | `/boletos`                         | Criar novo boleto                  |
| `GET`    | `/boletos/:nosso_numero`           | Consultar boleto                   |
| `PATCH`  | `/boletos/:nosso_numero`           | Atualizar boleto (apenas rascunho) |
| `DELETE` | `/boletos/:nosso_numero`           | Cancelar boleto                    |
| `POST`   | `/boletos/:nosso_numero/pay`       | Marcar boleto como pago            |
| `POST`   | `/settlements/trigger`             | Disparar processamento de liquidacao |

## Codigos de Status HTTP

| Codigo | Status                | Descricao                                              |
|--------|----------------------|--------------------------------------------------------|
| `200`  | OK                   | Requisicao processada com sucesso                      |
| `201`  | Created              | Recurso criado com sucesso                             |
| `202`  | Accepted             | Requisicao aceita para processamento assincrono        |
| `400`  | Bad Request          | Parametros invalidos ou malformados                    |
| `401`  | Unauthorized         | API Key ausente ou invalida                            |
| `403`  | Forbidden            | Sem permissao para acessar o recurso                   |
| `404`  | Not Found            | Recurso nao encontrado                                 |
| `422`  | Unprocessable Entity | Erro de validacao nos dados enviados                   |
| `429`  | Too Many Requests    | Limite de requisicoes excedido                         |
| `500`  | Internal Server Error| Erro interno do servidor                               |
| `503`  | Service Unavailable  | Servico temporariamente indisponivel                   |

## Paginacao

Endpoints que retornam listas suportam paginacao atraves de query parameters:

### Parametros de Paginacao

| Parametro | Tipo     | Padrao | Descricao                              |
|-----------|----------|--------|----------------------------------------|
| `page`    | integer  | 1      | Numero da pagina (comeca em 1)         |
| `per_page`| integer  | 20     | Quantidade de itens por pagina (max 100) |

### Exemplo de Requisicao Paginada

```bash
curl -X GET "https://api.monetarie_npc.com.br/api/v1/central/boletos?page=2&per_page=50" \
  -H "X-API-Key: pk_live_abc123def456"
```

### Formato da Resposta Paginada

```json
{
  "success": true,
  "data": [
    // Lista de itens
  ],
  "meta": {
    "request_id": "req_abc123def456",
    "pagination": {
      "page": 2,
      "per_page": 50,
      "total_items": 247,
      "total_pages": 5,
      "has_next": true,
      "has_prev": true
    }
  }
}
```

## Rate Limiting

A API possui limites de requisicoes para garantir estabilidade:

| Ambiente | Limite                  | Janela    |
|----------|-------------------------|-----------|
| Sandbox  | 100 requisicoes         | por minuto |
| Producao | 1000 requisicoes        | por minuto |

Quando o limite e excedido, a API retorna status `429 Too Many Requests` com os headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706972400
```

Para mais detalhes, consulte [Rate Limits](/reference/rate-limits).

## Proximos Passos

- [Boletos](/api/boletos) - Criar e gerenciar boletos
- [Liquidacao](/api/settlements) - Processar arquivos de liquidacao
- [Health Check](/api/health) - Verificar saude dos servicos