Saltar para o conteúdo principal
POST
curl

Por que não tem estado

A triagem de carteiras independente não grava nada na tabela de transações, por isso não existe um registo guardado a partir do qual este endpoint possa gerar o PDF. Em vez disso, volta a enviar o JSON exato que POST /v3/wallet-screening/ já devolveu, e a Didit transforma esse payload num PDF sem voltar a chamar um fornecedor.

O campo report_signature

Cada resposta de POST /v3/wallet-screening/ inclui agora um campo report_signature, uma assinatura opaca específica da sua aplicação. Este endpoint verifica-a antes de gerar o PDF, para que quem chama não consiga alterar risk_score, severity, sanctions_hit ou qualquer outro campo e obter um PDF com aspeto legítimo e com a marca Didit para um resultado que a Didit nunca produziu. Reenvie sempre o corpo completo da resposta sem alterações, incluindo report_signature. Reordenar as chaves é aceitável; alterar qualquer valor assinado não é.

Faturação

Não é feita nenhuma chamada a um fornecedor e nada é faturado: isto apenas volta a gerar um resultado pelo qual já pagou quando chamou POST /v3/wallet-screening/.

Erros

Próximos passos

Triagem de carteiras

Execute a triagem de carteiras subjacente mediante pedido e obtenha o resultado JSON para reenviar aqui.

Triagem de carteiras a pedido

Visão geral do endpoint de triagem de carteiras independente e do modelo de resultados.

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json

O objeto JSON não modificado devolvido por POST /v3/wallet-screening/, incluindo report_signature.

O mesmo formato que a resposta de POST /v3/wallet-screening/ — transmita esse corpo de resposta textualmente, incluindo report_signature.

provider
string
obrigatório

Fornecedor que realizou a triagem (por exemplo, merklescience, crystal).

screening_type
enum<string>
obrigatório

Sempre WALLET_SCREENING para este endpoint.

Opções disponíveis:
WALLET_SCREENING
risk_score
integer
obrigatório

Pontuação de risco normalizada de 0-100. Um valor mais alto significa maior exposição a entidades de risco. A Merkle Science classifica um endereço de 0 a 5, o que mapeia para 0, 15, 35, 55, 75 ou 95.

severity
enum<string>
obrigatório

Intervalo de risco derivado de risk_score: 0-9 UNKNOWN, 10-39 LOW, 40-69 MEDIUM, 70-89 HIGH, 90-100 CRITICAL. UNKNOWN é a faixa mais baixa, não um estado separado sem dados: um risk_score de 0 (o caso comum de endereço limpo) significa que não há avaliação adversa, enquanto uma pontuação diferente de zero no intervalo de 1 a 9 é um sinal real, mas abaixo de LOW - leia o risk_score, não apenas a faixa. Nunca trate UNKNOWN como uma classificação afirmativa de baixo risco ou limpa; não a apresente como aprovação.

Opções disponíveis:
UNKNOWN,
LOW,
MEDIUM,
HIGH,
CRITICAL
status
enum<string>
obrigatório

Estado do resultado da triagem.

Opções disponíveis:
SCREENED,
PENDING,
ERROR
summary
string
obrigatório

Resumo legível por humanos do resultado da triagem.

wallet_address
string
obrigatório

O endereço submetido a triagem, devolvido tal como foi recebido.

blockchain
string
obrigatório

A blockchain que foi analisada.

source_of_funds
object[]
obrigatório

De onde o endereço recebeu fundos, atribuídos por entidade. Cada entrada é um detalhe de exposição.

destination_of_funds
object[]
obrigatório

Para onde o endereço enviou fundos, atribuídos por entidade. Mesma estrutura de itens que source_of_funds com exposure_direction = outgoing.

counterparty_connections
object[]
obrigatório

Entidades às quais o fornecedor atribui o endereço submetido a triagem. Para a Merkle Science, estas provêm das etiquetas de proprietário e utilizador do próprio endereço, pelo que a mesma entidade pode surgir duas vezes, e não transportam fluxos de fundos: received_usd, sent_usd, received_hops e sent_hops são null e percentage é 0. Não efetue o encaminhamento com base em risk_level ou is_direct aqui: utilize sanctions_hit, dominant_risk_category e risk_factors[].is_high_risk para o veredito, e exposure_type em source_of_funds/destination_of_funds para aferir a ligação direta.

sanctions_hit
boolean
obrigatório

True se o endereço tiver exposição direta ou indireta a sanções.

dominant_risk_category
string | null
obrigatório

Categoria de alto risco com maior peso, ou null quando nenhuma é dominante (ex.: sanctioned, mixer, stolen_funds).

report_signature
string
obrigatório

Assinatura HMAC-SHA256 opaca sobre este resultado exato, com âmbito restrito à sua aplicação. Não tem significado por si só — reenvie o corpo completo da resposta, sem modificações e incluindo este campo, para POST /v3/wallet-screening/pdf/ para o renderizar como um PDF. O endpoint de PDF rejeita o pedido com 400 se report_signature estiver em falta ou se qualquer campo assinado (por exemplo, risk_score, severity, sanctions_hit) tiver sido editado antes do reenvio.

transaction_hash
string | null

Campo de triagem de transações, partilhado com o formato do resultado. É sempre null num resultado de triagem de carteiras.

block_timestamp
string | null

Campo de triagem de transações, partilhado com o formato do resultado. É sempre null num resultado de triagem de carteiras.

total_value_usd
number | null

Campo de triagem de transações, partilhado com o formato do resultado. É sempre null num resultado de triagem de carteiras.

fee_usd
number | null

Campo de triagem de transações, partilhado com o formato do resultado. É sempre null num resultado de triagem de carteiras.

sender_rows
object[]

Campo de triagem de transações, partilhado com o formato do resultado. Está sempre vazio num resultado de triagem de carteiras.

receiver_rows
object[]

Campo de triagem de transações, partilhado com o formato do resultado. Está sempre vazio num resultado de triagem de carteiras.

transaction_flows
object[]

Campo de triagem de transações, partilhado com o formato do resultado. Está sempre vazio num resultado de triagem de carteiras.

transaction_flows_status
string | null

Campo de triagem de transações, partilhado com o formato do resultado. É sempre null num resultado de triagem de carteiras.

transaction_flows_error
string | null

Campo de triagem de transações, partilhado com o formato do resultado. É sempre null num resultado de triagem de carteiras.

network_nodes
object[]

Nós do grafo de exposição para triagem de transações. Vazio no resultado de uma triagem de carteiras.

network_edges
object[]

Arestas do grafo de exposição para triagem de transações. Vazio no resultado de uma triagem de carteiras.

pep_counterparty
boolean | null

Exposição como pessoa politicamente exposta. null quando não há qualquer conclusão de PEP disponível, o que corresponde a todos os resultados atualmente porque nenhum fornecedor o comunica; false apenas para um resultado de triagem explicitamente negativo. Não interprete null como uma verificação de PEP concluída.

risk_factors
object[]

Explicação classificada de risk_score: o que produziu este veredito. Os fornecedores avaliam um endereço no seu próprio modelo e devolvem apenas um veredito (a Merkle Science devolve um número inteiro de 0 a 5), pelo que a pontuação por si só não é acionável. Com os elementos de maior risco primeiro e, depois, ordenada pelo valor movimentado através de cada fator, limitada aos cinco mais fortes; source_of_funds e destination_of_funds incluem sempre o detalhe completo. Um risk_score elevado sem nenhuma entrada is_high_risk significa que o fornecedor não reportou sanções nem qualquer correspondência com entidades atribuídas e avaliou o endereço puramente no seu próprio modelo de exposição - o summary indica isto explicitamente.

raw_response
object

O payload próprio do fornecedor. O seu formato é específico do fornecedor e pode mudar sem aviso prévio: leia os campos normalizados em vez de o analisar diretamente.

Resposta

O documento PDF renderizado, devolvido diretamente como binário application/pdf — não há invólucro JSON.

The response is of type file.

Última modificação em 7 de novembro de 2026