> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar inteligência da transação

> Retorna os sinais de risco de uma transação do TrustPass: status detalhado, motivo, tentativas e sinais de dispositivo — para apoiar a decisão do lojista.

Enquanto a [consulta de transação](/plataforma/trustpass/api/get-transacao) é pensada para a tela de checkout, este endpoint retorna a visão de risco completa, destinada à sua aplicação (o lojista) decidir como tratar o caso.

## Path Parameters

<ParamField path="id" type="string" required>
  ID da transação.
</ParamField>

## Response

<ResponseField name="id" type="string">
  ID da transação.
</ResponseField>

<ResponseField name="status" type="string">
  Status atual da transação. Veja a [lista completa de status](/plataforma/trustpass/fluxo-titular-terceiro#status-da-transação).
</ResponseField>

<ResponseField name="statusReason" type="string">
  Motivo específico associado ao status atual (ex.: motivo de reprovação ou de fraude). `null` quando não informado. Este campo é destinado à sua aplicação — o comprador final nunca vê este texto.
</ResponseField>

<ResponseField name="validated" type="boolean">
  Indica se a identidade já foi validada com sucesso.
</ResponseField>

<ResponseField name="validationAttempts" type="object[]">
  Histórico de tentativas de validação.

  <Expandable title="Propriedades de cada item">
    <ResponseField name="identityMasked" type="string">
      Documento (CPF/CNPJ) mascarado da tentativa.
    </ResponseField>

    <ResponseField name="validated" type="boolean">
      Resultado da tentativa.
    </ResponseField>

    <ResponseField name="at" type="string">
      Data e hora da tentativa.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="documentChangedBeforeMatch" type="boolean">
  Indica se o documento informado foi alterado antes de uma validação bem-sucedida.
</ResponseField>

<ResponseField name="hasPasskey" type="boolean">
  Indica se o titular possui uma passkey cadastrada.
</ResponseField>

<ResponseField name="biometricsAttempts" type="integer">
  Número de tentativas de biometria (liveness + ID Check) já realizadas.
</ResponseField>

<ResponseField name="deviceIntelligence" type="object">
  Sinais de dispositivo consolidados, para o comprador (`buyer`) e, quando aplicável, para o titular do cartão no [fluxo de titular terceiro](/plataforma/trustpass/fluxo-titular-terceiro) (`holder`).

  <Expandable title="Propriedades de deviceIntelligence">
    <ResponseField name="buyer" type="object">
      <Expandable title="Propriedades de buyer/holder">
        <ResponseField name="shieldId" type="string">
          Identificador do dispositivo.
        </ResponseField>

        <ResponseField name="score" type="number">
          Score de risco do dispositivo.
        </ResponseField>

        <ResponseField name="country" type="string">
          País identificado para o dispositivo.
        </ResponseField>

        <ResponseField name="flags" type="object">
          Indicadores de risco do dispositivo (ex.: uso de proxy, emulador, VPN). O conjunto de indicadores varia entre dispositivos móveis e web.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="holder" type="object">
      Mesmo formato de `buyer`, preenchido apenas quando há um fluxo de titular terceiro.
    </ResponseField>

    <ResponseField name="deviceMatchFlag" type="boolean">
      Indica se o dispositivo do comprador e do titular (quando houver validação de terceiro) foi identificado como o mesmo. `null` quando não aplicável.
    </ResponseField>

    <ResponseField name="geoMismatch" type="boolean">
      Indica divergência de geolocalização entre comprador e titular. `null` quando não aplicável.
    </ResponseField>
  </Expandable>
</ResponseField>

## Payload bruto de inteligência de dispositivo

<Warning>
  **Em definição — ainda não disponível em produção.** O nome do campo, o schema definitivo e a validação de compliance (LGPD) deste payload ainda estão em análise entre Produto, Engenharia e Jurídico. O conteúdo abaixo é um preview de como o campo deve se parecer, com base no formato já usado internamente, e pode mudar antes do lançamento.
</Warning>

Hoje, `deviceIntelligence` traz apenas os sinais já consolidados (`shieldId`, `score`, `country`, `flags`). Está em desenvolvimento um novo campo — com nome ainda a definir (ex.: `device_intelligence_raw`) — trazendo o **payload bruto** do provedor de inteligência de dispositivo integrado ao TrustPass, para lojistas que precisam de acesso aos dados originais para suas próprias regras de risco.

<Expandable title="Formato previsto (sujeito a alteração)">
  ```json theme={"theme":"catppuccin-latte"}
  {
    "app_store": "string",
    "platform": "Android | iOS | Web",
    "session_id": "string",
    "timestamp": 0,
    "version": "string",
    "device_info": {
      "ip": "string",
      "ip_country": "string",
      "gps_coordinates": "string",
      "user_agent": "string",
      "brand": "string",
      "model": "string",
      "os_version": "string",
      "carrier_name": "string",
      "timezone": "string",
      "language": "string"
    },
    "device_intelligence": {
      "device_score": 0,
      "is_emulated": false,
      "is_jailbroken": false,
      "is_proxy": false,
      "running_vpn_spoofers": false,
      "hooking": false
    }
  }
  ```
</Expandable>

<Warning>
  Este payload pode conter dados classificados como pessoais pela LGPD (IP, coordenadas de geolocalização — inclusive quando a captura de GPS estiver desabilitada no dispositivo do usuário, alguns provedores retornam esse campo como texto indicando a indisponibilidade —, User-Agent e identificadores de dispositivo). Ao receber este campo, sua aplicação passa a tratar esses dados como **Controladora**, nos termos do contrato entre sua empresa e a Valid. Avalie com sua área jurídica os impactos antes de habilitar o consumo deste campo em produção.
</Warning>

## Códigos de erro

| Código HTTP | Descrição                    |
| :---------- | :--------------------------- |
| 401         | API key ausente ou inválida. |
| 404         | Transação não encontrada.    |