Referência

Migrar da v1 — versão rápida

O que precisa mudar pra sair da API v1 e ir pra v2.

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/*)Ativos de novo, com contrato diferente: o GET lista o que os webhooks pix.med.opened / pix.med.updated registraram (assinar os dois virou parte de integrar MED) e não devolve status de disputa; o answer agora é result + reason e apenas registra a sua defesa, que segue com os anexos para o time de análise; as rotas de evidência voltaram a funcionar (upload em 3 passos). Não existe rota de decisão — devolver ou recusar o PIX disputado não é feito por esta API. Detalhes na §4.2 da referência.
Webhooks fee.*, 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 removidos5 rotas continuam funcionando como aliases deprecated (sunset em 2026-11-21) e 9 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/qr-code (sync)POST /v1/accounts/{id}/pix/out/qr-code/async
POST /v1/accounts/{id}/pix/out/qrcode (sem hífen)POST /v1/accounts/{id}/pix/out/qr-code/async

Endpoints removidos (404 na v2)

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

Rota v1 (removida)Substituto
GET /v1/accounts/{id}/pix/qr-codes (lista paginada)GET /v1/accounts/{id}/pix/qr-code/lookup?identifier=... (um QR) ou GET /v1/accounts/{id}/pix/qr-codes/stats (agregados)
POST /v1/webhooks/replayPolling do extrato em janela curta
GET /v1/integrator/webhooksGET /v1/webhooks
GET /v1/integrator/webhooks/{id}/deliveriesGET /v1/webhooks/{subscriptionId}/deliveries (+ /{deliveryId} e /{deliveryId}/retry)
POST /v1/integrator/events/replaySem substituto
POST /v1/integrator/events/replay/batchSem substituto
POST /v1/accounts/{id}/pix/med/{medId}/responsePOST .../pix/med/{medId}/answer (corpo novo: result + reason)
POST /v1/accounts/{id}/pix/med/{medId}/sendSem substituto — nunca existiu do lado do arranjo
POST /v1/accounts/{id}/pix/med/{medId}/decideSem substituto — a CorpX não decide MED; use answer para registrar a sua defesa

Documentação relacionada

Suporte

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