Sinais de contexto

Antes de começar

Os sinais de contexto avaliam transações de crédito concluídas e retornam uma avaliação de risco — autofraude ou engenharia social — para enriquecer sua própria decisão antifraude.

Eles são complementares à Verificação de Cartão Não Presente: não alteram o contrato nem o comportamento dos endpoints de transação que você já utiliza. Você continua recebendo o estado terminal da transação (approved, inconclusive, e assim por diante) normalmente, e depois consulta os sinais de contexto.

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro. Saiba mais em Autenticação.

Acesso controlado por permissão

O acesso a este endpoint é controlado por uma permissão (role) atribuída à sua empresa. Sem ela, o endpoint retorna 403. Solicite a habilitação ao time Unico.

Base URL

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1
• Produção: https://transactions.transactional.unico.app/api/public/v1

Consultar sinais de contexto

GET /transactions/{transaction_id}/signals — retorna a avaliação de risco de uma transação concluída.

O resultado é pré-computado de forma assíncrona assim que a transação atinge seu estado terminal, então este endpoint é apenas uma consulta a um resultado que já está disponível.

Path parameters

Parâmetro	Tipo	Obrigatório	Descrição
transaction_id	string	sim	ID da transação (UUID v4). Por exemplo, 6ab1771e-dfab-4e47-8316-2452268e5481.

Headers

Header	Valor
Authorization	Bearer {token} — um access-token válido.
Accept	application/json

Request example

GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json

200 OK

{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Campo	Tipo	Presença	Descrição
signals.auto_fraud_risk	string (enum)	opcional	Nível de risco de autofraude. Presente apenas quando detectado.
signals.social_eng_risk	string (enum)	opcional	Nível de risco de engenharia social. Presente apenas quando detectado.
signals.more_info.limited_data	boolean	sempre	true quando não há dados suficientes para uma avaliação robusta.
signals.more_info.holder_identified	boolean	sempre	false quando o portador do cartão não pôde ser identificado.

Valores de risco possíveis: very_low, low, medium, high, very_high.

informação

auto_fraud_risk e social_eng_risk são mutuamente exclusivos — nunca aparecem juntos na mesma resposta. Quando limited_data é true, espera-se que ambos os campos de risco estejam ausentes, já que não há dados suficientes para uma avaliação.

Response examples

Risco de engenharia social detectado:

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Nenhum risco identificado — uma transação normal:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Dados insuficientes:

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

Portador do cartão não identificado:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}

Other response codes

Os erros são retornados no formato padrão descrito em Erros.

Código HTTP	Código	Situação	O que fazer
202	—	O resultado ainda não foi computado — o processamento assíncrono ainda está em andamento.	Repita a chamada (polling) até obter um 200.
400	40004	transaction_id é inválido (não é um UUID v4) ou um parâmetro está malformado.	Corrija o formato do ID antes de enviar a requisição novamente.
403	40305	A empresa não tem a permissão (role) habilitada para este endpoint.	Solicite a habilitação ao time Unico.
404	40401	A transação não foi encontrada.	Verifique o ID da transação.
404	40484	A transação não foi encontrada para avaliação.	Trate como "não haverá resultado" e pare de consultar.
409	40983	A transação ainda não atingiu seu estado terminal.	Aguarde o estado terminal antes de consultar novamente.
500	—	Erro interno do serviço.	Tente novamente com backoff. Se persistir, contate o suporte Unico.

Regras e boas práticas

• Consulte o endpoint somente depois que a transação atingir seu estado terminal. Consultar antes retorna 409.
• Apenas transações de crédito são avaliadas. Transações capturadas em modo silencioso não são.
• Em um 202, repita a chamada até obter um 200. Envie a primeira requisição 1 segundo após a resposta da transação, e depois aplique backoff: 2s, 4s, 8s, 16s — até 5 tentativas.
• O objetivo de nível de serviço é de 10 segundos após a resposta da transação.
• Trate um 404 como "não haverá resultado" e pare de consultar.
• auto_fraud_risk e social_eng_risk são mutuamente exclusivos.