Guia de Migracao v2

Mudancas de contrato para padronizacao em portugues — breaking changes em todos os endpoints

Breaking change em todos os endpoints. Os integradores devem atualizar seus clientes antes do deploy.

Resumo das mudancas

A v2 padroniza todos os campos de request e response em portugues (pt-br).

Enums

Enum	Valor anterior	Novo valor
`WebhookTipo`	`PIX_STATUS_UPDATE`	`ATUALIZACAO_STATUS_PIX`
`WebhookTipo`	`WEBHOOK_FAILURE`	`FALHA_WEBHOOK`
`WebhookDeliveryStatus`	`SUCCESS`	`SUCESSO`
`WebhookDeliveryStatus`	`FAILED`	`FALHA`
`WebhookDeliveryStatus`	`PENDING_RETRY`	`AGUARDANDO_RETENTATIVA`

Payload PIX (`PixStatusPayload`)

Campo anterior	Campo novo	Tipo	Obrigatorio	Observacao
`amount`	`valor`	long	sim	Renomeado
`error`	`razaoRejeicao`	objeto	nao	Renomeado
—	`end2end`	string	nao	Novo campo

Os campos numeroDocumento e status permanecem iguais.

O objeto razaoRejeicao (antigo error) mantem a mesma estrutura:

{
  "codigo": "string",
  "descricao": "string"
}

Responses

DTO	Campo anterior	Campo novo
`DispatchEventResponse`	`dispatched`	`despachados`
`DispatchToWebhookResponse`	`deliveryId`	`entregaId`
`ErrorResponse`	`code`	`codigo`
`ErrorResponse`	`message`	`mensagem`
`ErrorResponse`	`details`	`detalhes`

Os campos traceId e timestamp do ErrorResponse permanecem iguais.

Campos sem alteracao

WebhookRequest: nome, url, tipo, secret, ativo
WebhookUpdateRequest: nome, url, secret, ativo
WebhookResponse: id, nome, url, tipo, ativo, criadoEm, atualizadoEm
WebhookEntregaResponse: id, webhookId, eventoId, status, tentativas, httpStatus, responseBody, payloadEnviado, tentadoEm, proximaTentativaEm
ErrorDetail: campo, erro
Endpoints (paths): sem alteracao

Como atualizar

1. Requests — Dispatch de eventos

Antes:

POST /internal/events/dispatch

{
  "tipo": "PIX_STATUS_UPDATE",
  "payload": [
    {
      "numeroDocumento": "12345678901",
      "status": "SETTLED",
      "amount": 15000,
      "error": null
    }
  ]
}

Depois:

POST /internal/events/dispatch

{
  "tipo": "ATUALIZACAO_STATUS_PIX",
  "payload": [
    {
      "numeroDocumento": "12345678901",
      "status": "SETTLED",
      "valor": 15000,
      "end2end": "E12345678202301011200abcdef12345",
      "razaoRejeicao": null
    }
  ]
}

2. Requests — Dispatch para webhook especifico

Antes:

POST /internal/events/dispatch/{webhookId}

{
  "payload": [
    {
      "numeroDocumento": "12345678901",
      "status": "REJECTED",
      "amount": 5000,
      "error": {
        "codigo": "BE08",
        "descricao": "Saldo insuficiente"
      }
    }
  ]
}

Depois:

POST /internal/events/dispatch/{webhookId}

{
  "payload": [
    {
      "numeroDocumento": "12345678901",
      "status": "REJECTED",
      "valor": 5000,
      "end2end": "E12345678202301011200abcdef12345",
      "razaoRejeicao": {
        "codigo": "BE08",
        "descricao": "Saldo insuficiente"
      }
    }
  ]
}

3. Requests — Criar webhook

Antes:

POST /api/v1/webhooks

{
  "nome": "meu-webhook",
  "url": "https://meu-servico.com/webhook",
  "tipo": "PIX_STATUS_UPDATE",
  "secret": "minha-chave-secreta-com-pelo-menos-32-caracteres"
}

Depois:

POST /api/v1/webhooks

{
  "nome": "meu-webhook",
  "url": "https://meu-servico.com/webhook",
  "tipo": "ATUALIZACAO_STATUS_PIX",
  "secret": "minha-chave-secreta-com-pelo-menos-32-caracteres"
}

4. Responses — Dispatch de eventos

Antes:

{ "dispatched": 2 }

Depois:

{ "despachados": 2 }

5. Responses — Dispatch para webhook especifico

Antes:

{ "deliveryId": "550e8400-e29b-41d4-a716-446655440000" }

Depois:

{ "entregaId": "550e8400-e29b-41d4-a716-446655440000" }

6. Responses — Erros

Antes:

{
  "code": "VALIDATION_ERROR",
  "message": "Falha de validacao",
  "details": [
    { "campo": "url", "erro": "must not be blank" }
  ],
  "traceId": "abc123",
  "timestamp": "2026-05-01T12:00:00Z"
}

Depois:

{
  "codigo": "VALIDATION_ERROR",
  "mensagem": "Falha de validacao",
  "detalhes": [
    { "campo": "url", "erro": "must not be blank" }
  ],
  "traceId": "abc123",
  "timestamp": "2026-05-01T12:00:00Z"
}

7. Query parameters — Listagem de webhooks

Antes:

GET /api/v1/webhooks?tipo=PIX_STATUS_UPDATE&ativo=true

Depois:

GET /api/v1/webhooks?tipo=ATUALIZACAO_STATUS_PIX&ativo=true

8. Headers de entrega

O header X-Webhook-Event agora envia o novo valor do enum:

Antes: X-Webhook-Event: PIX_STATUS_UPDATE
Depois: X-Webhook-Event: ATUALIZACAO_STATUS_PIX

9. Payload recebido pelo integrador

Antes:

[
  {
    "numeroDocumento": "12345678901",
    "status": "SETTLED",
    "amount": 15000,
    "error": null
  }
]

Depois:

[
  {
    "numeroDocumento": "12345678901",
    "status": "SETTLED",
    "valor": 15000,
    "end2end": "E12345678202301011200abcdef12345",
    "razaoRejeicao": null
  }
]

Checklist para integradores

Atualizar o valor do enum tipo nos requests de criacao/listagem de webhooks
Atualizar parsing do payload recebido: amount -> valor, error -> razaoRejeicao
Tratar o novo campo opcional end2end no payload
Atualizar parsing das respostas de dispatch: dispatched -> despachados, deliveryId -> entregaId
Atualizar parsing das respostas de erro: code -> codigo, message -> mensagem, details -> detalhes
Atualizar filtros por status de entrega: SUCCESS -> SUCESSO, FAILED -> FALHA, PENDING_RETRY -> AGUARDANDO_RETENTATIVA
Atualizar validacao do header X-Webhook-Event para os novos valores

Guia de Migracao v2

On this page