Pular para o conteúdo

PATCH /vasp/screenings/{id}/tx-hash

Anexa o hash da transação transmitida ao screening (pré-checagem em dois passos)

Depois de pré-checar um saque (screening sem tx_hash) e transmitir a transação, o cliente anexa o hash ao mesmo screening. O registro liga a recomendação e a decisão do cliente ao fato que elas autorizaram ou recusaram. Não reavalia o screening, não altera a recomendação nem a decisão do cliente, não exige decisão prévia e não gera cobrança. Vale também para recomendação HOLD ou DENY: a recomendação não é ordem.

Registro imutável e idempotente: o primeiro hash válido vence. Repetir o mesmo hash, em qualquer grafia canônica equivalente, devolve 200 com idempotent_replay: true e não escreve de novo; outro hash sobre um screening que já tem hash (do POST ou de anexo anterior) devolve 409. O mesmo hash pode constar em screenings diferentes do mesma empresa.

O hash é declarado pelo cliente: o formato é validado conforme a rede do screening, mas a existência da transação na rede não é medida (on_chain_verification é sempre NOT_MEASURED). Mesmo escopo (vasp:transactions:screen) e mesmo portão do módulo KYT das demais escritas de screening; o anexo não gera evento de saída.

Item Valor
Método PATCH
Caminho /vasp/screenings/{id}/tx-hash
URL https://crypto-api.sentinexrisk.com/api/v1/vasp/screenings/{id}/tx-hash
Grupo VASP - Screening
operationId attachScreeningTxHash
Versão do contrato 8.5.1

Chave de API do tenant no header X-API-Key (esquema ApiKeyAuth). A chave identifica o tenant e carrega os escopos; não existe header de tenant. Detalhes em Autenticação.

Nome Em Tipo Obrigatório Descrição
id path string (uuid) sim

Corpo obrigatório.

Tipo de mídia application/json.

Schema KYTTxHashAttachRequest, do tipo objeto.

Não aceita propriedades além das listadas.

Campo Tipo Obrigatório Descrição
tx_hash string sim Hash da transação transmitida. O formato é validado conforme a rede do screening (EVM: 32 bytes em hex, com ou sem 0x, gravado com 0x e minúsculo; Tron, Bitcoin e demais redes de hash hex: 64 hex minúsculo sem 0x; Solana: base58 de 64 a 90 caracteres com a caixa preservada; outras redes: identificador opaco de 32 a 128 caracteres). A grafia canônica é a gravada e a devolvida. De 1 a 128 caracteres.

Exemplo de corpo, publicado no contrato:

{
"tx_hash": "<hash de 32 bytes em hex da transação transmitida>"
}
Janela do terminal
curl -X PATCH "https://crypto-api.sentinexrisk.com/api/v1/vasp/screenings/{id}/tx-hash" \
-H "X-API-Key: $SENTINEX_API_KEY" \
-H "Content-Type: application/json" \
-d @corpo.json

O arquivo corpo.json segue o schema do corpo acima.

Status Descrição
200 Hash anexado, ou repetição idêntica (idempotent_replay)

Hash anexado, ou repetição idêntica (idempotent_replay)

Tipo de mídia application/json.

Schema KYTTxHashAttachResponse, do tipo objeto.

Campo Tipo Obrigatório Descrição
success boolean sim
idempotent_replay boolean não Presente e verdadeiro quando o hash já estava gravado e é o mesmo.
data objeto sim
data.screening_id string (uuid) sim
data.tx_hash string sim
data.tx_hash_state string sim Valores: ATTACHED.
data.origin string sim TX_HASH_PATCH quando o hash veio deste anexo; SCREENING_REQUEST quando já veio no POST /vasp/screenings. Valores: TX_HASH_PATCH, SCREENING_REQUEST.
data.recorded_at string (date-time) ou null sim Instante do anexo; nulo quando o hash veio no POST original.
data.on_chain_verification string sim A existência da transação na rede não é medida pela Sentinex neste passo. Valores: NOT_MEASURED.
data.recommendation string sim A recomendação original, inalterada. Valores: ALLOW, REVIEW, HOLD, DENY.
data.client_decision objeto (KYTClientDecision) sim Decisão e desfecho atribuídos exclusivamente ao cliente.
data.client_decision.status string sim Valores: PENDING_CLIENT_DECISION, RECORDED.
data.client_decision.authority string não Valores: CLIENT_EXCHANGE.
data.client_decision.operational_action string não Valores: ALLOW, HOLD, DENY.
data.client_decision.suspicion_outcome string não Valores: SUSPICIOUS, NOT_SUSPICIOUS.
data.client_decision.rationale string não
data.client_decision.recorded_at string (date-time) não Data e hora em RFC 3339, UTC.

Estes são os códigos que o contrato declara para esta operação. Os limites que valem para toda a API, antes da autenticação, estão em Limites de requisição.

Status Descrição
400 Identificador, corpo ou hash inválido (KYT_SCREENING_ID_INVALID, KYT_REQUEST_INVALID, KYT_TX_HASH_INVALID).
401 A chave de API não autenticou a requisição, e nenhuma camada adiante rodou. error.code é missing_api_key (nenhuma chave em X-API-Key nem em Authorization: Bearer snxc_...) ou invalid_api_key (chave desconhecida, revogada ou expirada). Quando a plataforma não consegue verificar a chave, a resposta é 503 com api_key_verification_unavailable, e não 401: repita com backoff.
402 Conta sem direito comercial (TRIAL_EXPIRED): trial vencido, trial sem data ou empresa sem contrato. A requisição NÃO foi processada; uma triagem recusada assim é transação não triada, nunca aprovada.
403 Acesso recusado antes da operação. Além das recusas de ErroAcessoNegado (escudo de borda, IP da chave, ambiente, conta e escopo), a empresa pode não ter o módulo de KYT contratado (ModuleNotEnabledResponse, MODULE_NOT_ENABLED, com details.module). Não repita sem corrigir a causa.
404 Análise inexistente nesta empresa (KYT_SCREENING_NOT_FOUND). Com chave válida, route_not_found diz que o caminho ou o método não corresponde a operação servida (ErrorResponseCoded).
409 O screening já tem outro hash de transação (KYT_TX_HASH_ALREADY_ATTACHED); o registro é imutável.
413 Corpo acima de 1 MiB, recusado pelo escudo de borda antes da autenticação (code BODY_TOO_LARGE). Nada foi processado.
429 Limite de requisições atingido; nada foi processado. Formas, pela camada que recusou: limite da chave (ErrorResponseCoded, api_key_rate_limit_exceeded, 60 por minuto quando a chave não define outro valor, Retry-After: 60); limite global por hora (ErroLimite, retry_after 3600 e Retry-After: 3600); escudo de borda por IP (ErroLimite: RATE_LIMIT_HARD acima de 1.000 por minuto, com 300 segundos; IP_BANNED no bloqueio temporário; e a rajada com intervalo menor que 50 ms, que vem sem Retry-After e sem retry_after). A busca de clientes tem limite próprio (error rate_limited, com retry_after e detail) e o laudo também (error RATE_LIMIT_EXCEEDED, 120 por hora por IP, Retry-After: 3600). No sandbox, chamadas VASP autenticadas também usam sandbox_simulator_rate_limit_exceeded: 60 por minuto por key, 300 por minuto por empresa e 10.000 por dia UTC por empresa. Essa recusa inclui Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining: 0. Espere o Retry-After quando ele vier.
500 Falha inesperada. A mensagem é genérica de propósito; guarde o X-Request-ID da resposta para o suporte e repita com espera.
503 Persistência, auditoria ou transação da requisição indisponível (KYT_PERSISTENCE_UNAVAILABLE, KYT_AUDIT_UNAVAILABLE), ou leitura do módulo contratado indisponível (MODULE_STORE_UNAVAILABLE); a transação inteira é desfeita e o hash não fica gravado sem a trilha. As camadas anteriores à operação também respondem 503, nada processado: limitador por IP ou da empresa sem contagem (ErroTexto), estado da conta (empresa_ACCESS_STATE_UNAVAILABLE), limitador da chave (rate_limit_unavailable) e verificação da chave (api_key_verification_unavailable).

Identificador, corpo ou hash inválido (KYT_SCREENING_ID_INVALID, KYT_REQUEST_INVALID, KYT_TX_HASH_INVALID).

Tipo de mídia application/json.

Schema KYTPublicErrorResponse, do tipo objeto.

Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error objeto sim
error.code string sim Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status integer sim Exemplo: 503.
error.message string sim
error.action string sim
error.retriable boolean sim
error.retry_after_seconds integer não Mínimo: 1.
error.request_id string não
error.reason string não Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.

A chave de API não autenticou a requisição, e nenhuma camada adiante rodou. error.code é missing_api_key (nenhuma chave em X-API-Key nem em Authorization: Bearer snxc_...) ou invalid_api_key (chave desconhecida, revogada ou expirada). Quando a plataforma não consegue verificar a chave, a resposta é 503 com api_key_verification_unavailable, e não 401: repita com backoff.

Resposta compartilhada ErroChaveNaoAutenticada do contrato.

Tipo de mídia application/json.

Schema ErrorResponseCoded, do tipo objeto.

Envelope de erro codificado (middlewares de API key e erros de negócio da superfície VASP). Trate error.code como contrato estável; error.message é texto livre.

Campo Tipo Obrigatório Descrição
success boolean sim Exemplo: false.
error objeto sim
error.code string sim Exemplo: missing_api_key.
error.message string sim Exemplo: X-API-Key header required.

Conta sem direito comercial (TRIAL_EXPIRED): trial vencido, trial sem data ou empresa sem contrato. A requisição NÃO foi processada; uma triagem recusada assim é transação não triada, nunca aprovada.

Resposta compartilhada TenantAccessPaymentRequired do contrato.

Tipo de mídia application/json.

Schema TenantAccessRefusalResponse, do tipo objeto.

Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code string sim Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details objeto não
details.reason string não Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at string (date-time) não Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state string não Presente em empresa_NOT_OPERATIONAL.

Acesso recusado antes da operação. Além das recusas de ErroAcessoNegado (escudo de borda, IP da chave, ambiente, conta e escopo), a empresa pode não ter o módulo de KYT contratado (ModuleNotEnabledResponse, MODULE_NOT_ENABLED, com details.module). Não repita sem corrigir a causa.

Resposta compartilhada ErroAcessoNegadoModuloKYT do contrato.

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, TenantAccessRefusalResponse, ErroTexto, ModuleNotEnabledResponse.

Campo Tipo Obrigatório Descrição
success boolean sim Exemplo: false.
error objeto sim
error.code string sim Exemplo: missing_api_key.
error.message string sim Exemplo: X-API-Key header required.
Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code string sim Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details objeto não
details.reason string não Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at string (date-time) não Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state string não Presente em empresa_NOT_OPERATIONAL.
Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim Exemplo: Carteira não encontrada..
Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim Exemplo: Este recurso não está habilitado no contrato atual..
code string sim Valores: MODULE_NOT_ENABLED.
details objeto não
details.module string não Código do módulo no catálogo. Exemplo: mod_crypto_sanctions.

Análise inexistente nesta empresa (KYT_SCREENING_NOT_FOUND). Com chave válida, route_not_found diz que o caminho ou o método não corresponde a operação servida (ErrorResponseCoded).

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, KYTPublicErrorResponse.

Campo Tipo Obrigatório Descrição
success boolean sim Exemplo: false.
error objeto sim
error.code string sim Exemplo: missing_api_key.
error.message string sim Exemplo: X-API-Key header required.
Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error objeto sim
error.code string sim Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status integer sim Exemplo: 503.
error.message string sim
error.action string sim
error.retriable boolean sim
error.retry_after_seconds integer não Mínimo: 1.
error.request_id string não
error.reason string não Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.

O screening já tem outro hash de transação (KYT_TX_HASH_ALREADY_ATTACHED); o registro é imutável.

Tipo de mídia application/json.

Schema KYTPublicErrorResponse, do tipo objeto.

Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error objeto sim
error.code string sim Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status integer sim Exemplo: 503.
error.message string sim
error.action string sim
error.retriable boolean sim
error.retry_after_seconds integer não Mínimo: 1.
error.request_id string não
error.reason string não Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.

Corpo acima de 1 MiB, recusado pelo escudo de borda antes da autenticação (code BODY_TOO_LARGE). Nada foi processado.

Resposta compartilhada ErroCorpoAcimaDoLimite do contrato.

Tipo de mídia application/json.

Schema ErroTextoComCodigo, do tipo objeto.

Envelope de erro com a mensagem em texto em error e o código estável em code, na raiz do corpo. Na API de KYT aparece no corpo acima de 1 MiB (BODY_TOO_LARGE, 413) e na leitura do módulo contratado que não pôde ser feita (MODULE_STORE_UNAVAILABLE, 503).

Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim
code string sim Exemplo: BODY_TOO_LARGE.

Limite de requisições atingido; nada foi processado. Formas, pela camada que recusou: limite da chave (ErrorResponseCoded, api_key_rate_limit_exceeded, 60 por minuto quando a chave não define outro valor, Retry-After: 60); limite global por hora (ErroLimite, retry_after 3600 e Retry-After: 3600); escudo de borda por IP (ErroLimite: RATE_LIMIT_HARD acima de 1.000 por minuto, com 300 segundos; IP_BANNED no bloqueio temporário; e a rajada com intervalo menor que 50 ms, que vem sem Retry-After e sem retry_after). A busca de clientes tem limite próprio (error rate_limited, com retry_after e detail) e o laudo também (error RATE_LIMIT_EXCEEDED, 120 por hora por IP, Retry-After: 3600). No sandbox, chamadas VASP autenticadas também usam sandbox_simulator_rate_limit_exceeded: 60 por minuto por key, 300 por minuto por empresa e 10.000 por dia UTC por empresa. Essa recusa inclui Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining: 0. Espere o Retry-After quando ele vier.

Resposta compartilhada ErroLimiteDeRequisicoes do contrato.

Header Tipo Descrição
Retry-After integer Segundos a esperar antes de repetir. Vem nos 429 dos limitadores (salvo a rajada do escudo) e no 503 de transação que conflitou (1 segundo).
X-RateLimit-Limit integer Teto da janela do limitador que respondeu, quando ele informa.
X-RateLimit-Remaining integer Requisições restantes na janela, quando o limitador informa.

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, ErroLimite.

Campo Tipo Obrigatório Descrição
success boolean sim Exemplo: false.
error objeto sim
error.code string sim Exemplo: missing_api_key.
error.message string sim Exemplo: X-API-Key header required.
Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim Exemplo: Too many requests. Please try again later..
retry_after integer não Mínimo: 1. Exemplo: 3600.
code string não Exemplo: RATE_LIMIT_HARD.
reference string não Identificador curto do bloqueio, para citar ao suporte.
detail string não

Falha inesperada. A mensagem é genérica de propósito; guarde o X-Request-ID da resposta para o suporte e repita com espera.

Resposta compartilhada ErroInterno do contrato.

Tipo de mídia application/json.

Schema ErroTexto, do tipo objeto.

Envelope de erro com a mensagem em texto no campo error, sem código. É o formato dos handlers de cadastro, carteira, webhooks, ledger e leituras regulatórias, da recuperação de falha inesperada (500), da indisponibilidade das camadas de borda (503) e da recusa do escudo de borda por padrão de ataque (403). Ramifique pelo status HTTP; a mensagem é texto livre e pode mudar.

Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim Exemplo: Carteira não encontrada..

Persistência, auditoria ou transação da requisição indisponível (KYT_PERSISTENCE_UNAVAILABLE, KYT_AUDIT_UNAVAILABLE), ou leitura do módulo contratado indisponível (MODULE_STORE_UNAVAILABLE); a transação inteira é desfeita e o hash não fica gravado sem a trilha. As camadas anteriores à operação também respondem 503, nada processado: limitador por IP ou da empresa sem contagem (ErroTexto), estado da conta (empresa_ACCESS_STATE_UNAVAILABLE), limitador da chave (rate_limit_unavailable) e verificação da chave (api_key_verification_unavailable).

Header Tipo Descrição
Retry-After integer Segundos a esperar antes de repetir. Vem nos 429 dos limitadores (salvo a rajada do escudo) e no 503 de transação que conflitou (1 segundo).

Tipo de mídia application/json.

Tipo um de: ErroTexto, TenantAccessRefusalResponse, ErrorResponseCoded, ErroTextoComCodigo, KYTPublicErrorResponse.

Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim Exemplo: Carteira não encontrada..
Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code string sim Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details objeto não
details.reason string não Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at string (date-time) não Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state string não Presente em empresa_NOT_OPERATIONAL.
Campo Tipo Obrigatório Descrição
success boolean sim Exemplo: false.
error objeto sim
error.code string sim Exemplo: missing_api_key.
error.message string sim Exemplo: X-API-Key header required.
Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error string sim
code string sim Exemplo: BODY_TOO_LARGE.
Campo Tipo Obrigatório Descrição
success boolean sim Valores: false.
error objeto sim
error.code string sim Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status integer sim Exemplo: 503.
error.message string sim
error.action string sim
error.retriable boolean sim
error.retry_after_seconds integer não Mínimo: 1.
error.request_id string não
error.reason string não Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.