Changelog

A v2 é uma reescrita completa da plataforma sobre uma infraestrutura mais rápida e previsível, com integração direta ao novo liquidante. Em geral retrocompatível com a v1.

Auth

• Nova base URL: https://tenant.api.corpx.com/v1 (era https://api.corpxapi.com/v1)
• Novo Token URL: https://auth.api.corpx.com/oauth2/token
• Novos client_id + client_secret por integrador (entregues por canal seguro)
• Scopes: api/full → api2/read api2/write
• Idempotency-Key virou opcional (auto-gerado se ausente)
• X-Tenant-Id é obrigatório em todas as requisições /v1/* (exceto GET /v1/me e health); deve coincidir com o tenant da conta quando accountId está no path

Statement consolidado em um único endpoint

• GET /v1/accounts/{accountId}/statement é agora sempre live — consulta o liquidante em tempo real (sem cache local).
• Os endpoints derivados que liam do mesmo cache (/pix/transactions, /pix/payments, /payments alias) também passam a ser live.
• A API v1 e o backoffice anteriores continuam no ar em modo somente-leitura por 30 dias após o cutover para consulta histórica.
• Endpoints /transactions/real-statement, /transactions/legacy-statement e /payments/{id}/legacy não existem na v2 — use /statement (atual) ou a v1 read-only (histórico).

Endpoints deprecated (ainda funcionam até 2026-11-21)

4 paths que existiam na v1 e ficaram fora da versão canônica da v2 voltam como aliases deprecated. Continuam respondendo normalmente, mas anexam 3 headers de aviso na resposta:

Deprecation: true
Sunset: Sat, 21 Nov 2026 00:00:00 GMT
Link: </v1/accounts/.../novo-caminho>; rel="successor-version"

Esses headers seguem RFC 8594 (Deprecation) e RFC 9745 (Sunset). Sunset previsto: 2026-11-21 — após essa data passam a retornar 410 Gone. Não aparecem mais no OpenAPI nem na Postman collection.

• GET /v1/accounts/{id}/pix/payments/{paymentId} → use /pix/payments/lookup?identifier=
• GET /v1/accounts/{id}/payments/{paymentId} (alias sem /pix/) → use /pix/payments/lookup?identifier=
• GET /v1/accounts/{id}/pix/qr-code (sem /lookup) → use /pix/qr-code/lookup?identifier=
• POST /v1/accounts/{id}/pix/out/qrcode (sem hífen) → use /pix/out/qr-code

Endpoints removidos (retornam 404 na v2)

• GET /v1/accounts/{id}/pix/qr-codes (lista paginada) → consulte um QR por vez com /pix/qr-code/lookup?identifier=, ou use /pix/qr-codes/stats para agregados
• POST /v1/webhooks/replay → sem substituto
• GET /v1/integrator/webhooks → use GET /v1/webhooks
• GET /v1/integrator/webhooks/{id}/deliveries → sem substituto (desde então ganhou um: GET /v1/webhooks/{subscriptionId}/deliveries, com detalhe e retry individual)
• POST /v1/integrator/events/replay + /batch → sem substituto
• POST .../pix/med/{medId}/send + /response → use /decide + /answer

GET /v1/health continua existindo na v2 (ganhou alias adicional GET /health para health checks externos).

Endpoints novos

• GET /v1/me (debug do client_id autenticado)
• GET /v1/transactions/{id}/timeline (sem accountId no path)
• GET /v1/accounts/{id}/pix/out/bigpix/{batchId} (status agregado de lote BigPix)
• GET /health (alias do /v1/health sem o prefixo)
• Boleto family (POST .../boleto/preview|pay, GET .../boleto/payments/{id}) — era 503 na v1, agora ativo

Mudanças de comportamento (mesmo path, novo shape ou semântica)

• Statement e endpoints derivados: cache → live; sem tariff_ref derivado; header X-Source: live; janela máxima por consulta 31 dias.
• Internal transfer by-bank-account: aceita holderDocument + holderName opcionais (não breaking).
• Locked balance unlock: v2 só valida lockId; campos extras são ignorados (não breaking).
• Campo fee no objeto de transação removido temporariamente — conciliação manual via identifier=fee-{slug}-{operationReferenceId} no extrato. Volta sem mudança de payload em release futura.

MED e webhooks temporariamente suspensos

• Endpoints /v1/accounts/{id}/pix/med/* retornam HTTP 503 durante a migração. Disputas em aberto seguem o ciclo natural do BACEN — apenas a integração via API está pausada.
• Webhooks suspensos: fee.*, pix.med.*, edi.*. Subscriptions a esses eventos podem permanecer ativas — quando voltarem, retomam automaticamente. Tarifas seguem aparecendo no extrato como linhas independentes (com identifier=fee-{slug}-{ref}).

Compat (sem mudança no seu código)

• BigPix (POST .../pix/out/bigpix e .../bank-account/bigpix): body continua single ({amount, key, ...}); chunking permanece server-side, igual à v1.
• PIX out variants (/pix/out/async, /bank-account/async, /bank-account/bigpix): preservados.
• /v1/accounts/{accountId}/transfers/internal (todos os 3 modos): path e body preservados.
• /v1/accounts/{id}/pix/qr-code/static body: value continua como na v1.
• /v1/accounts/{id}/pix/out/qr-code/decode: path preservado.
• /v1/accounts/{id}/pix/keys (GET + POST + DELETE): mantidos.
• /v1/accounts/{id}/pix/key/{pixKey} (DICT lookup): mantido.

Suporte

Contato: api@corpx.com durante o cutover do tenant — resposta em até 1h em horário comercial.