> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Verificação do parceiro de antifraude do TED Lerian > Como o TED Lerian pede ao parceiro de antifraude da sua instituição que analise TEDs enviadas, transferências internas e TEDs recebidas, como você liga cada verificação e o que o parceiro precisa implementar. O TED Lerian pode pedir ao parceiro de antifraude da sua própria instituição que analise uma transferência antes de o dinheiro se mover. O parceiro responde `ALLOW`, `REVIEW` ou `DENY`. Cada verificação vem desligada por padrão. Você liga a verificação para a sua instituição. ## As quatro verificações *** Cada verificação é um fluxo. Um fluxo tem as suas próprias configurações, rota e credenciais. | Fluxo | O que o parceiro analisa | | - | - | | `out` | Uma TED que a sua instituição envia. | | `intra_out` | Uma transferência interna, pelo lado do pagador. | | `intra_in` | Uma transferência interna, pelo lado do recebedor. | | `in` | Uma TED que a sua instituição recebe. | O TED Lerian lê as configurações quando cria uma transferência. Uma transferência criada com todos os fluxos desligados não é analisada, mesmo que você ligue um fluxo depois. O `fraudCheck` dela é `null`. ## TEDs enviadas e transferências internas *** O TED Lerian espera o parceiro por no máximo o `syncBudgetMs` da rota, que é 4000 ms ou menos. Uma TED é analisada depois que o TED Lerian reserva o valor e antes de enviar a TED ao STR. Em uma transferência interna com os dois fluxos ligados, o TED Lerian consulta primeiro o lado do pagador e depois o lado do recebedor. Ele para na primeira recusa. | Resposta | Resultado | | - | - | | `ALLOW` | Uma TED segue para o STR. Uma transferência interna liquida quando todos os lados estão aprovados. | | `DENY` | A transferência fica `REJECTED` com `TED-0050` e `rejection.source` `ANTIFRAUD`. O TED Lerian libera a reserva, se houver, e o limite de uso. | | `REVIEW` | A transferência espera em `FRAUD_ANALYSIS`. Uma TED mantém a reserva. Em uma transferência interna, o TED Lerian reserva o valor do pagador logo depois, então uma recusa do ledger ainda pode rejeitá-la. | A resposta de criação pode retornar `REJECTED` ou `FRAUD_ANALYSIS`. Toda consulta de transferência traz `fraudCheck`. Ele tem `decideBy` e uma verificação para cada fluxo que estava ligado quando o TED Lerian criou a transferência. Cada verificação tem a `decision`, a sua `origin` (`PROVIDER` ou `FALLBACK`), a `cause`, o `analysisId`, o `score`, os `reasons`, a `resolution` e `resolvedAt`. O `score` e os `reasons` são os do parceiro, como ele os enviou. O texto de um motivo pode citar um terceiro. `decideBy` é o horário de criação mais a janela de revisão do fluxo, menos 2 minutos. A janela de revisão é a configuração `review_window_minutes`, de 10 a 30 minutos. Quando os dois fluxos internos estão ligados, vale a menor janela. Em uma TED, o fechamento da janela de funcionamento pode antecipar `decideBy`: ele passa a ser o fechamento menos 2 minutos. O fechamento da janela de funcionamento não vale para uma transferência interna. Com o fluxo `out` ligado, o TED Lerian recusa uma TED com `422 TED-0020` quando a janela de funcionamento fecha em 2 minutos e 4 segundos ou menos. O TED Lerian não reserva nada nesse caso. Se o TED Lerian não consegue ler as configurações de antifraude, ele recusa o envio com um `503` antes de reservar qualquer valor. Uma transferência em `FRAUD_ANALYSIS` termina de uma destas formas: 1. **O parceiro decide.** O parceiro chama a [operação de resolução](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/apply-a-fraud-analysis-decision-to-a-transfer.md). Em `DENY`, o TED Lerian rejeita a transferência com `TED-0050`. Em `ALLOW`, ele envia uma TED ao STR, ou liquida uma transferência interna quando todos os lados aprovam. 2. **Você cancela.** `POST /v1/transfers/{transferId}/cancel` responde `200`, e o TED Lerian libera a reserva e o limite de uso. Enquanto uma chamada ao Midaz ou ao Lerian SPB para a transferência está em andamento, a resposta é `409 TED-0061`. 3. **`decideBy` passa.** O TED Lerian rejeita a transferência com `TED-0052`, com a origem `WORKER` na linha do tempo, e libera a reserva e o limite de uso. Depois de `decideBy`, o TED Lerian ainda aceita um `DENY` para uma transferência em `FRAUD_ANALYSIS`. Um `ALLOW` que chega em `decideBy` ou depois recebe `409 TED-0060`. Um `ALLOW` para uma TED que chega a tempo, com a janela de funcionamento fechada, rejeita a TED com `TED-0020` ou `TED-0021`. Se o TED Lerian não consegue ler a janela, ele responde `503 TED-0022` e não faz nenhuma mudança. `TED-0050`, `TED-0051` e `TED-0052` chegam em `rejection.code` de uma transferência `REJECTED`. Eles não são respostas de erro. ## Quando o parceiro não consegue responder *** Um parceiro pode estourar o tempo, recusar uma chamada ou enviar uma resposta inválida. Em `out`, `intra_out` e `intra_in`, a `posture` da rota decide então: * `CLOSED` rejeita a transferência com `TED-0051`. * `OPEN` deixa a transferência seguir sem análise. A verificação mostra `origin` `FALLBACK` e a `cause`. `posture.default` define a postura. As `bands` opcionais a definem por valor: a primeira faixa cujo `upTo` é igual ou maior que o valor decide. O TED Lerian rejeita a transferência com `TED-0051`, seja qual for a postura, nestes casos: * A rota não está definida. * O pacote de credenciais está ausente ou não pode ser lido. * `ANTIFRAUD_SECRETS_BACKEND` está vazio. * O endereço é um que o TED Lerian não chama, ou o certificado TLS dele não é verificado. Se o gerenciador de segredos não responde, a postura decide. O fluxo `in` não tem postura. Em uma TED recebida, uma resposta que não vem do parceiro não credita nem devolve a TED. O TED Lerian a envia para revisão manual. ## TEDs recebidas *** Com o fluxo `in` ligado, o TED Lerian não credita uma TED recebida antes de o parceiro responder. | Resposta | Resultado | | - | - | | `ALLOW` | O TED Lerian credita o cliente. | | `REVIEW` | A TED espera em `MANUAL_REVIEW` com `reviewReason` `FRAUD_REVIEW`. Nada é creditado. | | `DENY` | O TED Lerian devolve a TED à instituição remetente com o motivo oficial `9` (fraude). O evento `incoming_return.requested` traz `fraudCheck`. | | Sem resposta do parceiro | A TED espera em `MANUAL_REVIEW` com `reviewReason` `FRAUD_CHECK_UNAVAILABLE`. Um operador decide. | Uma TED em `FRAUD_REVIEW` termina de uma destas formas: 1. **O parceiro decide.** O parceiro chama a [operação de resolução](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/apply-a-fraud-analysis-decision-to-an-incoming-ted.md). Em `ALLOW`, o TED Lerian credita a TED. Em `DENY`, ele devolve a TED com o motivo `9`. 2. **Um operador resolve a revisão.** O operador usa `resolve-review`, como em qualquer outra revisão manual. 3. **`decideBy` passa.** `decideBy` é 15 minutos antes do prazo regulatório de 60 minutos, ou seja, 45 minutos depois da liquidação interbancária. O TED Lerian marca a revisão aberta como `EXPIRED`. Com `antifraud.in.auto_return_enabled` ligado, ele devolve a TED com o motivo `9`. Com ele desligado, a TED fica com o operador. A operação de resolução responde `409 TED-0060` nestes casos: * A TED não aguarda esta análise. * O `analysisId` é diferente. * Há outra decisão registrada. * `decideBy` passou. * Um `DENY` chega depois que o crédito da TED por um operador pode ter chegado ao ledger. Não repita um `409`. Um `503` significa que o TED Lerian não terminou. Repita com o mesmo `X-Idempotency`. `TED-0053` significa que a decisão chegou antes de o TED Lerian registrar a análise, ou que a mesma chave ainda está em andamento. Com `TED-1000` ou `TED-0080`, a decisão continua registrada, e a repetição a conclui. ## Ligar uma verificação *** Grave as configurações no namespace `plugin-br-ted-lerian.policy` pela API de administração do [systemplane](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md) do TED Lerian, no plano `/v1/system`. O papel `editor` grava as configurações. Para cada fluxo: | Chave | Significado | | - | - | | `antifraud..enabled` | Liga a verificação. O padrão é desligada. | | `antifraud..route` | A rota do parceiro, como um único objeto JSON. `{}` significa não definida. O TED Lerian valida a rota quando você a grava. | | `antifraud..review_window_minutes` | O tempo que o parceiro tem para decidir um `REVIEW`, em minutos, de 10 a 30. O padrão é 30. O fluxo `in` não tem. | | `antifraud.in.auto_return_enabled` | Devolve com o motivo `9` uma revisão expirada de uma TED recebida. O padrão é desligada. | A rota tem estes campos: | Campo | Significado | | - | - | | `endpoint` | O endereço que recebe a avaliação. | | `feedbackEndpoint` | Opcional. O endereço que recebe o resultado de cada TED enviada e transferência interna analisada. | | `auth` | `mode` (`hmac-v1`, `lerian-m2m` ou `oauth2-client-credentials`). Os dois modos de token também precisam de `tokenUrl` e `clientId`. `oauth2-client-credentials` aceita `scopes`. `staticHeaders` opcional vale para todos os modos. | | `syncBudgetMs` | A espera máxima por uma avaliação, tentativas incluídas. De 100 a 4000. | | `attemptTimeoutMs` | O limite de tempo de uma tentativa. Não pode ser maior que `syncBudgetMs`. | | `maxAttempts` | O número de tentativas, 1 ou mais. | | `posture` | `default` (`OPEN` ou `CLOSED`) é obrigatório, e `bands` são opcionais. O fluxo `in` recusa uma `posture`. | ```json theme={null} { "endpoint": "https://antifraud.example.com/evaluate", "feedbackEndpoint": "https://antifraud.example.com/feedback", "auth": { "mode": "hmac-v1" }, "syncBudgetMs": 3000, "attemptTimeoutMs": 1500, "maxAttempts": 2, "posture": { "default": "CLOSED" } } ``` O TED Lerian chama um `endpoint`, `feedbackEndpoint` ou `tokenUrl` apenas quando ele é `https` em um endereço público, a menos que o host dele esteja em `ANTIFRAUD_ALLOWED_PRIVATE_HOSTS`. Quando você grava uma rota que não cumpre essa regra, o TED Lerian a recusa. Veja as [variáveis de ambiente](https://docs.lerian.studio/pt/interfaces/ted-lerian/ted-lerian-environment-variables.md#antifraud-partner). No BYOC, o TED Lerian lê um pacote de credenciais do gerenciador de segredos que `ANTIFRAUD_SECRETS_BACKEND` nomeia. O caminho é `tenants/{ENVIRONMENT_NAME}/single-tenant/plugin-br-ted-lerian/external/antifraud-/credentials`. `` é `out`, `intra-out`, `intra-in` ou `in`. Com `vault`, o caminho fica sob o mount KV v2 `secret`. O pacote aceita estas chaves: * `secret`: o segredo do cliente, ou o segredo HMAC em `hmac-v1`. É obrigatório em todos os modos de autenticação. * `certPem` e `keyPem`: um par de certificado de cliente opcional. Envie os dois ou nenhum. * `header.`: um header opcional que o TED Lerian envia em cada chamada. ## O que o parceiro recebe *** Com um fluxo ligado, o TED Lerian envia ao parceiro estes dados das duas partes: * O nome completo. * O CPF ou CNPJ. * O ISPB, a agência, a conta e o tipo de conta. Ele também envia o valor e o código de finalidade. * **TEDs enviadas e transferências internas:** a descrição e o `metadata` da transferência. O lado do pagador também recebe `clientReference`. * **TEDs recebidas:** a descrição que a instituição remetente escreveu, o `nuop`, o número de controle do STR e o horário da liquidação. ## O que o parceiro implementa *** O TED Lerian envia cada avaliação como um `POST` de um corpo JSON ao `endpoint` da rota. Os headers são: | Header | Valor | | - | - | | `Idempotency-Key` | A chave da avaliação. A mesma chave retorna a mesma análise. | | `X-Lerian-Decide-By` | O prazo da decisão, em RFC 3339 UTC. | | `X-Lerian-Payload-Schema` | `ted-out.v1` para o lado do pagador de uma TED ou de uma transferência interna. `ted-in.v1` para o lado do recebedor e para uma TED recebida. | Cada corpo tem `transferId`, `flow` (`EXTERNAL` ou `INTRA`), `amount`, `currency` (`BRL`), `payer`, `payee` e `createdAt`. Ele também tem `purposeCode`, sem zeros à esquerda, e `description` quando existem. `ted-out.v1` soma `clientReference` e `metadata`. `ted-in.v1` soma `metadata` em uma transferência interna, e `messageCode`, `numCtrlStr`, `settledAt` e `nuop` em uma TED recebida. Cada parte tem `name`, `taxId`, `ispb`, `branch`, `account` e `accountType`. TEDs enviadas e transferências internas também levam `personType`. O lado com conta na sua instituição leva `accountId`. O TED Lerian assina cada chamada com o `auth.mode` da rota: * `hmac-v1`: `X-Webhook-Timestamp` tem o horário Unix em segundos. `X-Webhook-Signature` é `v1,sha256=` seguido do HMAC-SHA256 em hexadecimal de `v1:.` com o `secret`. * `lerian-m2m` e `oauth2-client-credentials`: o TED Lerian obtém um token em `auth.tokenUrl` com o `clientId` e o `secret`. Ele envia o token como bearer token. O parceiro responde `200` com um corpo JSON: | Campo | Significado | | - | - | | `decision` | `ALLOW`, `REVIEW` ou `DENY`. | | `analysisId` | De 1 a 64 caracteres ASCII imprimíveis, sem espaço. Obrigatório com `REVIEW`. | | `score`, `reasons` | Opcionais. O TED Lerian não decide por eles. | Um `202` conta como `REVIEW`, e precisa de um `analysisId`, a menos que o corpo diga `DENY`. O TED Lerian repete um `408`, `429` ou `5xx` com a mesma `Idempotency-Key`, dentro de `syncBudgetMs` e `maxAttempts`. Ele não repete um `403`. Nos modos de token, quando `maxAttempts` é 2 ou mais, repete um `401` uma vez, depois de obter um token novo. Qualquer status diferente de `200` ou `202`, um corpo de mais de 64 KiB, ou um `REVIEW` sem `analysisId` válido não é uma decisão. O TED Lerian trata isso como uma resposta que não veio do parceiro (veja [Quando o parceiro não consegue responder](#when-the-partner-cannot-answer)). O parceiro envia a decisão final de um `REVIEW` com estas operações. As duas exigem o papel `editor`. Uma aplicação com o papel `operator` não pode chamá-las. | Operação | Permissão | | - | - | | [`POST /v1/transfers/{transferId}/fraud-analysis/resolve`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/apply-a-fraud-analysis-decision-to-a-transfer) | `transfers:resolve-fraud-analysis` | | [`POST /v1/incoming-transfers/{incomingTransferId}/resolve`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/apply-a-fraud-analysis-decision-to-an-incoming-ted) | `incoming-transfers:resolve-fraud-check` | O corpo é `analysisId`, `decision` (`ALLOW` ou `DENY`) e `reasons` opcional. `X-Idempotency` é obrigatório, e o valor dele é `:`. Os `reasons` de uma resolução substituem os motivos da avaliação na verificação. O `score` continua. Quando a rota do fluxo `out`, `intra_out` ou `intra_in` tem um `feedbackEndpoint`, o TED Lerian informa o resultado de cada TED enviada e transferência interna analisada. Ele não envia feedback para TEDs recebidas. O corpo tem `evaluationKey`, `analysisId`, `decisionOrigin` (`PROVIDER` ou `FALLBACK`), `outcome` e `occurredAt`. `outcome` é `SETTLED`, `REJECTED`, `CANCELLED`, `EXPIRED` ou `RETURNED`. A `Idempotency-Key` é a chave da avaliação, dois-pontos e o resultado. O feedback precisa de `OUTBOX_ENABLED` com o valor `true`. Sem ele, a análise funciona e o TED Lerian não envia feedback. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.