Pular para o conteúdo principal

Migrar da v1 — versão rápida

Tempo de leitura: 2 minutos. Para auditoria endpoint-por-endpoint, veja Migrar da v1 — referência completa.

Este guia é para integradores que já estavam em produção na API v1 (https://api.corpxapi.com). Integrações novas devem ir direto para a v2 e ler o guia de início rápido.

O que muda (atualize no seu código)​

ItemAntes (v1)Depois (v2)
API base URLhttps://api.corpxapi.com/v1https://tenant.api.corpx.com/v1
Token URL OAuthdomínio Cognito antigohttps://auth.api.corpx.com/oauth2/token
client_id / client_secretatuaisnovos (entregues por canal seguro junto com a data do cutover)
Scopes OAuthapi/fullapi2/read api2/write

O que NÃO muda​

  • Todos os paths /v1/accounts/{accountId}/... (com 4 ressalvas listadas abaixo)
  • Seu webhook URL e seu HMAC secret
  • account_id continuam os mesmos UUIDs
  • Payloads e headers de webhook
  • BigPix body — continua sendo {amount, key, ...} (chunking permanece server-side)

5 ressalvas pontuais​

Se sua integração depende de um dos itens abaixo, leia a referência completa antes do cutover. Caso contrário, é só trocar URL + credenciais.

RessalvaO que mudou
Statement (GET /v1/accounts/{id}/statement)Mesmo path, mas agora é tempo-real (sem cache local). Latência sobe de ~50 ms para ~500 ms–1,5 s, e o campo derivado tariff_ref deixa de vir nas linhas. Dados bancários da contraparte ficam reduzidos a name + document — branch, account, bankCode, bankIspb, pixKey não vêm mais nas linhas do extrato (o banco liquidante não expõe esses no endpoint de extrato). Para o payload completo, use GET /v1/accounts/{id}/pix/payments/lookup?endToEndId=... ou aguarde o webhook outbound (pix.in.completed / pix.out.completed). Detalhes na §4.1 da referência.
QR-code PIX — resposta achatadaOs 4 endpoints de QR (POST /pix/qr-code/dynamic, POST /pix/qr-code/static, GET /pix/qr-code/lookup, DELETE /pix/qr-code) perderam o envelope {statusCode, title, type, message, data: {...}}. Os campos viraram top-level; data.payload virou emv; data.location foi removido. Detalhes na §4.9 da referência.
MED (/v1/accounts/{id}/pix/med/* + webhooks med.*)Temporariamente em 503 durante a migração.
Webhooks fee.*, med.*, edi.* + campo fee no objeto de transaçãoTemporariamente suspensos. Tarifas aparecem como linhas independentes no extrato (type=internal-transfer para CORPX_FEE_ACCOUNT_ID com identifier=fee-{slug}-...).
Endpoints deprecated e removidos4 rotas continuam funcionando como aliases deprecated (sunset em 2026-11-21) e 7 rotas viram 404 — veja as tabelas abaixo.

Endpoints deprecated (continuam funcionando até 2026-11-21)​

Continuam respondendo normalmente, mas trazem o header Deprecation: true + Sunset: Sat, 21 Nov 2026 00:00:00 GMT + Link: <successor-url>; rel="successor-version". Migre para o substituto na próxima janela de manutenção.

Rota deprecated (ainda funciona)Substituto canônico
GET /v1/accounts/{id}/pix/payments/{paymentId}GET /v1/accounts/{id}/pix/payments/lookup?identifier=...
GET /v1/accounts/{id}/payments/{paymentId} (alias sem /pix/)GET /v1/accounts/{id}/pix/payments/lookup?identifier=...
GET /v1/accounts/{id}/pix/qr-code (sem /lookup)GET /v1/accounts/{id}/pix/qr-code/lookup?identifier=...
POST /v1/accounts/{id}/pix/out/qrcode (sem hífen)POST /v1/accounts/{id}/pix/out/qr-code

Endpoints removidos (404 na v2)​

Se você nunca chamou nenhum desses, ignore esta seção.

Rota v1 (removida)Substituto
POST /v1/webhooks/replayPolling do extrato em janela curta
GET /v1/integrator/webhooksGET /v1/webhooks
GET /v1/integrator/webhooks/{id}/deliveriesSem substituto
POST /v1/integrator/events/replaySem substituto
POST /v1/integrator/events/replay/batchSem substituto
POST /v1/accounts/{id}/pix/med/{medId}/sendPOST .../pix/med/{medId}/decide (mas MED está em 503 hoje)
POST /v1/accounts/{id}/pix/med/{medId}/responsePOST .../pix/med/{medId}/answer (mas MED está em 503 hoje)

Documentação relacionada​

Suporte​

Contato: suporte-api@corpx.com — resposta em até 1h em horário comercial.