Manual de Migração SOAP → REST

Guia de integração: diferenças de contrato, formatos de erro e mapeamento de campos entre as duas integrações.

1. Visão geral: a diferença fundamental

A API SOAP (Antifraude WebService) retorna cada erro como um elemento estruturado dentro de ErrorReportCollection, com um código numérico (<ErrorCode>) e uma descrição (<ErrorMessage>) em campos XML separados. Já a API antifraude REST não tem nenhum campo numérico de código de erro no corpo da resposta; a informação equivalente aparece sempre como texto livre, dentro de um de três formatos de corpo JSON diferentes, dependendo de qual camada de validação rejeitou a requisição:

• Formato A: corpo é uma string JSON solta (sem nenhuma chave ou envelope);
• Formato B: corpo é um objeto com a chave fixa FraudAnalysisRequestError, contendo um array de mensagens;
• Formato C: corpo é o padrão ProblemDetails do ASP.NET Core, com um objeto errors cujas chaves são os nomes dos campos que falharam.

2. Retorno HTTP de cada aplicação

3. Pode haver mais de uma validação na mesma requisição?

Sim, nas duas aplicações, mas cada uma acumula de um jeito diferente:

• SOAP: cada campo inválido gera um <ErrorReport> próprio dentro de ErrorReportCollection; se três campos estiverem errados, os três elementos ErrorReport aparecem juntos na mesma resposta;
• REST, Formato B: a API valida todos os campos numa só passada; cada violação é adicionada ao array FraudAnalysisRequestError;
• REST, Formato C: essa lógica também vale para o objeto errors; cada campo com problema aparece como uma chave própria;
• REST, Formato A: é sempre uma única mensagem; não acumula.

4. Mapeamento de campos entre as duas aplicações

A tabela a seguir apresenta o mapeamento entre os campos do Antifraude Legado (SOAP) e da API antifraude REST. Uma célula em branco indica que a validação existe somente na outra aplicação.

4.1 Dados gerais da transação

4.2 Comprador e endereço de cobrança (BillToData ↔ Billing / Customer)

4.3 Cartão (CardData ↔ Card)

4.4 Endereço de entrega (ShipToData ↔ Shipping)

4.5 Item / produto (ItemData.ProductData ↔ CartItem)

5. Exemplos: a mesma falha de negócio, nas duas aplicações

5.1 Múltiplos campos obrigatórios ou inválidos na mesma requisição

SOAP

HTTP/1.1 200 OK
<FraudAnalysisResponse>
  <Success>false</Success>
  <ErrorReportCollection>
    <ErrorReport>
      <ErrorCode>901</ErrorCode>
      <ErrorMessage>Street1: Parameter cannot
      be null or empty [BillToData]</ErrorMessage>
    </ErrorReport>
    <ErrorReport>
      <ErrorCode>902</ErrorCode>
      <ErrorMessage>Country: Invalid parameter
      length. Valid length: 2 [BillToData]</ErrorMessage>
    </ErrorReport>
  </ErrorReportCollection>
  <TransactionStatusCode>505</TransactionStatusCode>
</FraudAnalysisResponse>

REST

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "FraudAnalysisRequestError": [
    "The Customer.MerchantCustomerId is mandatory",
    "The Billing.Country length is greater than 3."
  ]
}

Este exemplo evidencia a estrutura que o cliente recebe quando mais de um campo falha na validação na mesma requisição: no SOAP, cada campo inválido aparece como um <ErrorReport> próprio dentro de ErrorReportCollection; no REST, cada campo inválido aparece como um item do array FraudAnalysisRequestError.

5.2 Campo de tipo ou formato inválido no cartão

SOAP

HTTP/1.1 200 OK
<FraudAnalysisResponse>
  <Success>false</Success>
  <ErrorReportCollection>
    <ErrorReport>
      <ErrorCode>904</ErrorCode>
      <ErrorMessage>ExpirationMonth: Only numeric values are permitted [CardData]</ErrorMessage>
    </ErrorReport>
  </ErrorReportCollection>
  <TransactionStatusCode>505</TransactionStatusCode>
</FraudAnalysisResponse>

REST

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "errors": {
    "Card.ExpirationDate": [
      "Error: Card.ExpirationDate must match the format 'mm/yyyy'."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-9c9289ecce24a77c5636de3ee60a43a2-5abcf1a7535aab99-01"
}

O SOAP não valida o formato da data de validade; ele valida mês (ExpirationMonth) e ano (ExpirationYear) em campos separados, aceitando qualquer valor numérico dentro do tamanho esperado. O exemplo desta seção mostra o cenário mais próximo disso no SOAP: enviar um valor não numérico nesses campos. Já o REST usa um único campo (Card.ExpirationDate, formato mm/yyyy) e rejeita qualquer valor que não corresponda a essa máscara.