# Changelog — EFXPay Mobile API

Alterações no contrato público `/api/v1/*` consumido pelo app mobile.  
Versionamento alinhado a `info.version` em [openapi.mobile.yaml](./openapi.mobile.yaml).

Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/).  
Semver do contrato: **MAJOR.MINOR.PATCH**

---

## [1.0.0] — 2026-05-24

### Adicionado

- **Auth:** `POST /auth/login`, `POST /auth/logout` (JWT Bearer).
- **Contas:** `GET /accounts/me`, `GET /accounts/balance`, `GET /accounts/statement`.
- **PIX envio:** `POST /pix/send` com header obrigatório `Idempotency-Key`.
- **PIX cobrança:** `POST /pix/charge` com `type`: `dynamic` | `static` e `Idempotency-Key`.
- **PIX consulta:** `GET /pix/{transactionId}` (estado local; sem polling no provider).
- **Chaves PIX:** `GET|POST|DELETE /pix/keys`.
- **Onboarding PF:** rotas públicas sob `/onboarding/*` (sem JWT).
- **Cadastro legado:** `POST /accounts/pf` (preferir `/onboarding/pf` em apps novos).
- OpenAPI: [openapi.mobile.yaml](./openapi.mobile.yaml).
- Coleção Postman: [EFXPay-Mobile.postman_collection.json](./EFXPay-Mobile.postman_collection.json).

### Notas para o mobile

- Guardar `access_token` após login; enviar em todas as rotas protegidas.
- `Idempotency-Key` deve ser UUID novo por operação; reutilizar apenas em retry da **mesma** operação.
- Status PIX outbound pode mudar via webhook no servidor — não há `GET` de status no provider.
- Conta precisa de `document`, `agency` e `account_number` (via login/onboarding) para PIX e chaves.

### Não incluído nesta versão

- `POST /accounts/pj` (retorna `501`).
- Webhooks (`POST /webhooks/globalscm`) — apenas servidor, não mobile.
- `GET /baas/list` — fora de escopo.

---

## Próximas versões (planejado)

### [1.1.0] — TBD

- Possível `GET /pix` (listagem paginada local).
- Eventos push / deep link quando webhook atualizar transação.

### [2.0.0] — TBD

- Breaking: prefixo `/api/v2` se contrato de onboarding ou PIX mudar de forma incompatível.

---

## Como declarar breaking change

1. Incrementar **MAJOR** em `openapi.mobile.yaml` → `info.version`.
2. Documentar aqui na secção `[X.Y.Z]` com tag **Breaking**.
3. Manter rotas antigas em `/api/v1` até data de sunset acordada com o time mobile.