> ## 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. # Verificación del socio de antifraude de TED Lerian > Cómo TED Lerian pide al socio de antifraude de tu institución que analice TEDs enviadas, transferencias internas y TEDs recibidas, cómo activas cada verificación y qué debe implementar el socio. TED Lerian puede pedir al socio de antifraude de tu propia institución que analice una transferencia antes de que el dinero se mueva. El socio responde `ALLOW`, `REVIEW` o `DENY`. Cada verificación viene desactivada de forma predeterminada. Tú activas la verificación para tu institución. ## Las cuatro verificaciones *** Cada verificación es un flujo. Un flujo tiene sus propios ajustes, ruta y credenciales. | Flujo | Qué analiza el socio | | - | - | | `out` | Una TED que tu institución envía. | | `intra_out` | Una transferencia interna, desde el lado del pagador. | | `intra_in` | Una transferencia interna, desde el lado del destinatario. | | `in` | Una TED que tu institución recibe. | TED Lerian lee los ajustes cuando crea una transferencia. Una transferencia creada con todos los flujos desactivados no se analiza, aunque actives un flujo después. Su `fraudCheck` es `null`. ## TEDs enviadas y transferencias internas *** TED Lerian espera al socio como máximo el `syncBudgetMs` de la ruta, que es 4000 ms o menos. Una TED se analiza después de que TED Lerian retiene el monto y antes de enviar la TED al STR. En una transferencia interna con los dos flujos activados, TED Lerian consulta primero el lado del pagador y después el lado del destinatario. Se detiene en el primer rechazo. | Respuesta | Resultado | | - | - | | `ALLOW` | Una TED sigue al STR. Una transferencia interna se liquida cuando todos los lados están aprobados. | | `DENY` | La transferencia queda `REJECTED` con `TED-0050` y `rejection.source` `ANTIFRAUD`. TED Lerian libera la retención, si la hay, y el límite de uso. | | `REVIEW` | La transferencia espera en `FRAUD_ANALYSIS`. Una TED mantiene la retención. En una transferencia interna, TED Lerian retiene el monto del pagador justo después, así que un rechazo del ledger todavía puede rechazarla. | La respuesta de creación puede devolver `REJECTED` o `FRAUD_ANALYSIS`. Toda lectura de transferencia trae `fraudCheck`. Tiene `decideBy` y una verificación por cada flujo que estaba activado cuando TED Lerian creó la transferencia. Cada verificación tiene la `decision`, su `origin` (`PROVIDER` o `FALLBACK`), la `cause`, el `analysisId`, el `score`, los `reasons`, la `resolution` y `resolvedAt`. El `score` y los `reasons` son los del socio, como los envió. El texto de un motivo puede nombrar a un tercero. `decideBy` es la hora de creación más la ventana de revisión del flujo, menos 2 minutos. La ventana de revisión es el ajuste `review_window_minutes`, de 10 a 30 minutos. Cuando los dos flujos internos están activados, vale la menor ventana. En una TED, el cierre de la ventana operativa puede adelantar `decideBy`: pasa a ser el cierre menos 2 minutos. El cierre de la ventana operativa no vale para una transferencia interna. Con el flujo `out` activado, TED Lerian rechaza una TED con `422 TED-0020` cuando la ventana operativa cierra en 2 minutos y 4 segundos o menos. En ese caso TED Lerian no retiene nada. Si TED Lerian no puede leer los ajustes de antifraude, rechaza el envío con un `503` antes de retener cualquier monto. Una transferencia en `FRAUD_ANALYSIS` termina de una de estas formas: 1. **El socio decide.** El socio llama a la [operación de resolución](https://docs.lerian.studio/es/reference/interfaces/ted-lerian/apply-a-fraud-analysis-decision-to-a-transfer.md). En `DENY`, TED Lerian rechaza la transferencia con `TED-0050`. En `ALLOW`, envía una TED al STR, o liquida una transferencia interna cuando todos los lados aprueban. 2. **Tú cancelas.** `POST /v1/transfers/{transferId}/cancel` responde `200`, y TED Lerian libera la retención y el límite de uso. Mientras una llamada a Midaz o a Lerian SPB para la transferencia está en curso, la respuesta es `409 TED-0061`. 3. **`decideBy` pasa.** TED Lerian rechaza la transferencia con `TED-0052`, con el origen `WORKER` en la línea de tiempo, y libera la retención y el límite de uso. Después de `decideBy`, TED Lerian aún acepta un `DENY` para una transferencia en `FRAUD_ANALYSIS`. Un `ALLOW` que llega en `decideBy` o después recibe `409 TED-0060`. Un `ALLOW` para una TED que llega a tiempo, con la ventana operativa cerrada, rechaza la TED con `TED-0020` o `TED-0021`. Si TED Lerian no puede leer la ventana, responde `503 TED-0022` y no hace ningún cambio. `TED-0050`, `TED-0051` y `TED-0052` llegan en `rejection.code` de una transferencia `REJECTED`. No son respuestas de error. ## Cuando el socio no puede responder *** Un socio puede agotar el tiempo, rechazar una llamada o enviar una respuesta inválida. En `out`, `intra_out` e `intra_in`, la `posture` de la ruta decide entonces: * `CLOSED` rechaza la transferencia con `TED-0051`. * `OPEN` deja que la transferencia siga sin análisis. La verificación muestra `origin` `FALLBACK` y la `cause`. `posture.default` define la postura. Las `bands` opcionales la definen por monto: decide la primera banda cuyo `upTo` es igual o mayor que el monto. TED Lerian rechaza la transferencia con `TED-0051`, sea cual sea la postura, en estos casos: * La ruta no está definida. * El paquete de credenciales falta o no se puede leer. * `ANTIFRAUD_SECRETS_BACKEND` está vacío. * La dirección es una a la que TED Lerian no llama, o su certificado TLS no se verifica. Si el gestor de secretos no responde, decide la postura. El flujo `in` no tiene postura. En una TED recibida, una respuesta que no viene del socio no acredita ni devuelve la TED. TED Lerian la envía a revisión manual. ## TEDs recibidas *** Con el flujo `in` activado, TED Lerian no acredita una TED recibida antes de que el socio responda. | Respuesta | Resultado | | - | - | | `ALLOW` | TED Lerian acredita al cliente. | | `REVIEW` | La TED espera en `MANUAL_REVIEW` con `reviewReason` `FRAUD_REVIEW`. No se acredita nada. | | `DENY` | TED Lerian devuelve la TED a la institución emisora con el motivo oficial `9` (fraude). El evento `incoming_return.requested` trae `fraudCheck`. | | Sin respuesta del socio | La TED espera en `MANUAL_REVIEW` con `reviewReason` `FRAUD_CHECK_UNAVAILABLE`. Un operador decide. | Una TED en `FRAUD_REVIEW` termina de una de estas formas: 1. **El socio decide.** El socio llama a la [operación de resolución](https://docs.lerian.studio/es/reference/interfaces/ted-lerian/apply-a-fraud-analysis-decision-to-an-incoming-ted.md). En `ALLOW`, TED Lerian acredita la TED. En `DENY`, devuelve la TED con el motivo `9`. 2. **Un operador resuelve la revisión.** El operador usa `resolve-review`, como en cualquier otra revisión manual. 3. **`decideBy` pasa.** `decideBy` es 15 minutos antes del plazo regulatorio de 60 minutos, es decir, 45 minutos después de la liquidación interbancaria. TED Lerian marca la revisión abierta como `EXPIRED`. Con `antifraud.in.auto_return_enabled` activado, devuelve la TED con el motivo `9`. Con él desactivado, la TED queda con el operador. La operación de resolución responde `409 TED-0060` en estos casos: * La TED no espera este análisis. * El `analysisId` es distinto. * Hay otra decisión registrada. * `decideBy` pasó. * Un `DENY` llega después de que el crédito de la TED por un operador pudo haber llegado al ledger. No repitas un `409`. Un `503` significa que TED Lerian no terminó. Repite con el mismo `X-Idempotency`. `TED-0053` significa que la decisión llegó antes de que TED Lerian registrara el análisis, o que la misma clave sigue en curso. Con `TED-1000` o `TED-0080`, la decisión queda registrada, y la repetición la termina. ## Activar una verificación *** Escribe los ajustes en el namespace `plugin-br-ted-lerian.policy` con la API de administración de [systemplane](https://docs.lerian.studio/es/reference/platform/systemplane/overview.md) de TED Lerian, en el plano `/v1/system`. El rol `editor` escribe los ajustes. Para cada flujo: | Clave | Significado | | - | - | | `antifraud..enabled` | Activa la verificación. El valor predeterminado es desactivada. | | `antifraud..route` | La ruta del socio, como un solo objeto JSON. `{}` significa no definida. TED Lerian valida la ruta cuando la escribes. | | `antifraud..review_window_minutes` | El tiempo que el socio tiene para decidir un `REVIEW`, en minutos, de 10 a 30. El valor predeterminado es 30. El flujo `in` no tiene. | | `antifraud.in.auto_return_enabled` | Devuelve con el motivo `9` una revisión vencida de una TED recibida. El valor predeterminado es desactivada. | La ruta tiene estos campos: | Campo | Significado | | - | - | | `endpoint` | La dirección que recibe la evaluación. | | `feedbackEndpoint` | Opcional. La dirección que recibe el resultado de cada TED enviada y transferencia interna analizada. | | `auth` | `mode` (`hmac-v1`, `lerian-m2m` o `oauth2-client-credentials`). Los dos modos de token también necesitan `tokenUrl` y `clientId`. `oauth2-client-credentials` acepta `scopes`. `staticHeaders` opcional vale para todos los modos. | | `syncBudgetMs` | La espera máxima por una evaluación, reintentos incluidos. De 100 a 4000. | | `attemptTimeoutMs` | El límite de tiempo de un intento. No puede ser mayor que `syncBudgetMs`. | | `maxAttempts` | El número de intentos, 1 o más. | | `posture` | `default` (`OPEN` o `CLOSED`) es obligatorio, y `bands` son opcionales. El flujo `in` rechaza una `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" } } ``` TED Lerian llama a un `endpoint`, `feedbackEndpoint` o `tokenUrl` solo cuando es `https` en una dirección pública, a menos que su host esté en `ANTIFRAUD_ALLOWED_PRIVATE_HOSTS`. Cuando escribes una ruta que no cumple esta regla, TED Lerian la rechaza. Consulta las [variables de entorno](https://docs.lerian.studio/es/interfaces/ted-lerian/ted-lerian-environment-variables.md#antifraud-partner). En BYOC, TED Lerian lee un paquete de credenciales del gestor de secretos que `ANTIFRAUD_SECRETS_BACKEND` nombra. La ruta es `tenants/{ENVIRONMENT_NAME}/single-tenant/plugin-br-ted-lerian/external/antifraud-/credentials`. `` es `out`, `intra-out`, `intra-in` o `in`. Con `vault`, la ruta queda bajo el mount KV v2 `secret`. El paquete acepta estas claves: * `secret`: el secreto del cliente, o el secreto HMAC en `hmac-v1`. Es obligatorio en todos los modos de autenticación. * `certPem` y `keyPem`: un par de certificado de cliente opcional. Envía los dos o ninguno. * `header.`: un header opcional que TED Lerian envía en cada llamada. ## Qué recibe el socio *** Con un flujo activado, TED Lerian envía al socio estos datos de las dos partes: * El nombre completo. * El CPF o CNPJ. * El ISPB, la agencia, la cuenta y el tipo de cuenta. También envía el monto y el código de finalidad. * **TEDs enviadas y transferencias internas:** la descripción y el `metadata` de la transferencia. El lado del pagador también recibe `clientReference`. * **TEDs recibidas:** la descripción que escribió la institución emisora, el `nuop`, el número de control del STR y la hora de la liquidación. ## Qué implementa el socio *** TED Lerian envía cada evaluación como un `POST` de un cuerpo JSON al `endpoint` de la ruta. Los headers son: | Header | Valor | | - | - | | `Idempotency-Key` | La clave de la evaluación. La misma clave devuelve el mismo análisis. | | `X-Lerian-Decide-By` | El plazo de la decisión, en RFC 3339 UTC. | | `X-Lerian-Payload-Schema` | `ted-out.v1` para el lado del pagador de una TED o de una transferencia interna. `ted-in.v1` para el lado del destinatario y para una TED recibida. | Cada cuerpo tiene `transferId`, `flow` (`EXTERNAL` o `INTRA`), `amount`, `currency` (`BRL`), `payer`, `payee` y `createdAt`. También tiene `purposeCode`, sin ceros a la izquierda, y `description` cuando existen. `ted-out.v1` suma `clientReference` y `metadata`. `ted-in.v1` suma `metadata` en una transferencia interna, y `messageCode`, `numCtrlStr`, `settledAt` y `nuop` en una TED recibida. Cada parte tiene `name`, `taxId`, `ispb`, `branch`, `account` y `accountType`. Las TED enviadas y las transferencias internas también llevan `personType`. El lado con cuenta en tu institución lleva `accountId`. TED Lerian firma cada llamada con el `auth.mode` de la ruta: * `hmac-v1`: `X-Webhook-Timestamp` tiene la hora Unix en segundos. `X-Webhook-Signature` es `v1,sha256=` seguido del HMAC-SHA256 en hexadecimal de `v1:.` con el `secret`. * `lerian-m2m` y `oauth2-client-credentials`: TED Lerian obtiene un token en `auth.tokenUrl` con el `clientId` y el `secret`. Envía el token como bearer token. El socio responde `200` con un cuerpo JSON: | Campo | Significado | | - | - | | `decision` | `ALLOW`, `REVIEW` o `DENY`. | | `analysisId` | De 1 a 64 caracteres ASCII imprimibles, sin espacio. Obligatorio con `REVIEW`. | | `score`, `reasons` | Opcionales. TED Lerian no decide por ellos. | Un `202` cuenta como `REVIEW`, y necesita un `analysisId`, a menos que el cuerpo diga `DENY`. TED Lerian repite un `408`, `429` o `5xx` con la misma `Idempotency-Key`, dentro de `syncBudgetMs` y `maxAttempts`. No repite un `403`. En los modos de token, cuando `maxAttempts` es 2 o más, repite un `401` una vez, después de obtener un token nuevo. Cualquier estado distinto de `200` o `202`, un cuerpo de más de 64 KiB, o un `REVIEW` sin `analysisId` válido no es una decisión. TED Lerian lo trata como una respuesta que no vino del socio (consulta [Cuando el socio no puede responder](#when-the-partner-cannot-answer)). El socio envía la decisión final de un `REVIEW` con estas operaciones. Las dos exigen el rol `editor`. Una aplicación con el rol `operator` no puede llamarlas. | Operación | Permiso | | - | - | | [`POST /v1/transfers/{transferId}/fraud-analysis/resolve`](https://docs.lerian.studio/es/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/es/reference/interfaces/ted-lerian/apply-a-fraud-analysis-decision-to-an-incoming-ted) | `incoming-transfers:resolve-fraud-check` | El cuerpo es `analysisId`, `decision` (`ALLOW` o `DENY`) y `reasons` opcional. `X-Idempotency` es obligatorio, y su valor es `:`. Los `reasons` de una resolución reemplazan los motivos de la evaluación en la verificación. El `score` se mantiene. Cuando la ruta del flujo `out`, `intra_out` o `intra_in` tiene un `feedbackEndpoint`, TED Lerian informa el resultado de cada TED enviada y transferencia interna analizada. No envía feedback para las TED recibidas. El cuerpo tiene `evaluationKey`, `analysisId`, `decisionOrigin` (`PROVIDER` o `FALLBACK`), `outcome` y `occurredAt`. `outcome` es `SETTLED`, `REJECTED`, `CANCELLED`, `EXPIRED` o `RETURNED`. La `Idempotency-Key` es la clave de la evaluación, dos puntos y el resultado. El feedback necesita `OUTBOX_ENABLED` con el valor `true`. Sin él, el análisis funciona y TED Lerian no envía feedback. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.