# Changelog — API Pública do ERP Lompa (`/api/public/v1`)

**Status:** `v1-alpha`  
**Escopo atual:** onboarding inicial, fiscal (naturezas/configuração) e integração inicial Mercado Livre

Este changelog registra mudanças em **contratos públicos partner-facing** da API pública.

---

## Convenções

Tipos usados:
- `Added`
- `Changed`
- `Fixed`
- `Deprecated`
- `Removed`
- `Security`

Cada entrada deve indicar:
- endpoint(s) afetado(s)
- impacto para integrador
- ação necessária (se houver)

---

## 2026-02-24

### Added
- **Namespace público inicial** criado em ` /api/public/v1 `.
  - **Endpoints afetados:** placeholders iniciais de `company` e `nfe`
  - **Impacto:** base explícita para contratos partner-facing sem misturar com API interna/frontend
  - **Ação do integrador:** nenhuma (fase alpha / estrutura inicial)

- **Padrão de erro público** definido para endpoints partner-facing:
  - formato: `code`, `message`, `details`, `request_id`
  - header: `X-Request-Id` (eco/geração)
  - **Impacto:** prepara parsing consistente e troubleshooting para integradores
  - **Ação do integrador:** usar `code` como chave de tratamento; logar `request_id`

### Changed
- **Estratégia de autenticação da API pública** formalizada em documentação:
  - padrão alvo: **OAuth 2.0 + PKCE** para apps/parceiros
  - `API Key` passa a ser tratada como opção transitória (não padrão final)
  - **Impacto:** alinhamento de arquitetura e docs; sem mudança de runtime pública ainda
  - **Ação do integrador:** nenhuma imediata (implementação ainda em fases futuras)

- **Especificação OpenAPI inicial (`v1-alpha`)** publicada para a API pública:
  - **Artefato:** `API_PUBLICA_OPENAPI_V1_ALPHA.yaml`
  - **Impacto:** estabelece fonte de verdade inicial para docs/frontend e evolução do contrato
  - **Ação do integrador:** usar como referência alpha; considerar endpoints ainda placeholders

- **Página de documentação MVP no frontend** disponibilizada:
  - **Rotas:** `/developers`, `/developers/openapi/v1-alpha`, `/developers/changelog/api-publica`
  - **Impacto:** melhora DX inicial sem depender ainda de renderizador OpenAPI dedicado
  - **Ação do integrador:** opcional; pode usar o YAML e changelog direto pelas rotas

- **Convenção de sucesso da API pública** definida para `v1-alpha`:
  - **Padrão:** payload no formato natural do recurso (sem envelope global de sucesso)
  - **Header:** `X-Request-Id` agora faz parte do contrato também em respostas de sucesso
  - **Impacto:** melhora correlação e suporte sem inflar contratos no alpha
  - **Ação do integrador:** enviar/logar `X-Request-Id` quando desejar correlação ponta a ponta

---

## Template de nova entrada (copiar/colar)

```md
## YYYY-MM-DD

### Added
- Descrição
  - **Endpoints afetados:** `GET /api/public/v1/...`
  - **Impacto:** ...
  - **Ação do integrador:** ...

### Changed
- Descrição
  - **Endpoints afetados:** ...
  - **Impacto:** ...
  - **Ação do integrador:** ...

### Deprecated
- Descrição
  - **Endpoints afetados:** ...
  - **Impacto:** ...
  - **Ação do integrador:** migrar para ...
  - **Remoção prevista:** YYYY-MM-DD (se aplicável)

### Fixed
- Descrição
  - **Endpoints afetados:** ...
  - **Impacto:** ...
  - **Ação do integrador:** nenhuma
```