API de cribado de transacciones o API de sanciones y PEP: ¿cuál encaja en su flujo de pagos?

Checklynx ofrece dos modelos de API que pueden respaldar el cribado en un flujo de pagos, pero asignan la responsabilidad de forma distinta.

Utilice POST /transactions cuando el pago y sus partes deban convertirse en una ejecución duradera de cribado de transacciones en Checklynx. Cada solicitud crea un ID de ejecución, mantiene las partes aportadas en un mismo contexto de transacción, permite recuperarlas posteriormente y puede vincular los resultados que requieren actuación con un caso de Checklynx.

Utilice POST /check/sanctions_pep cuando su aplicación deba seguir siendo el sistema de registro de la transacción y del flujo de trabajo. El endpoint criba directamente un objetivo frente a datos de sanciones, PEP y listas de personas buscadas. Su aplicación sigue siendo responsable de conservar su copia de registro del contexto del pago, las relaciones entre partes, la correlación, las evidencias y el flujo de revisión posterior.

No se trata simplemente de elegir entre «más» o «menos» cribado. Se trata de decidir qué sistema controla la ejecución del cribado de transacciones y el modelo de evidencias.

La decisión de un vistazo

La API de cribado de transacciones mantiene varias partes aportadas dentro de una sola ejecución de Checklynx:

evento de pago del cliente → POST /transactions → ID de ejecución de Checklynx → resultados de las partes y evidencias de la ejecución → caso opcional → decisión del cliente

La API directa de sanciones y PEP deja esa estructura en la plataforma del cliente:

evento de pago del cliente → elegir parte → POST /check/sanctions_pep → guardar respuesta bajo la transacción y la parte del cliente → repetir según proceda → revisión del cliente → decisión del cliente

Ambos modelos pueden alimentar un flujo de pagos. La cuestión clave es si Checklynx debe conservar una ejecución nativa de transacción o actuar como capa de cribado directo dentro de una arquitectura que ya controla el registro completo de la transacción y su revisión.

Si la pregunta subyacente es cómo se diferencia el cribado de transacciones de la monitorización de comportamiento, consulte cribado de transacciones frente a monitorización de transacciones. Esta guía no reabre esa distinción.

Qué crea POST /transactions

POST /transactions adopta un enfoque centrado en la transacción. La solicitud contiene un objeto transaction y otro screening. La transacción exige un transaction_reference_id aportado por el cliente y parties; el objeto de cribado exige un screening_profile_id.

La transacción también puede incluir su tipo, la fecha y hora en que se produjo, el importe y la divisa. Los tipos documentados actualmente incluyen pago bancario, pago con tarjeta, remesa, ingreso de efectivo, retirada de efectivo, transferencia interna y otros. Estos campos añaden contexto de pago a la ejecución; no determinan el tratamiento jurídico del pago.

La respuesta contiene un id generado por Checklynx, el resumen de la transacción, el status de ejecución, hit_status, hit_count, screening_summary, la hora de creación, resultados por parte y un case_id que puede ser nulo. El contrato actual define el estado de ejecución como completed o failed y el estado de coincidencia como hit o clear. Un estado de coincidencia refleja resultados no suprimidos que requieren actuación según el flujo de cribado configurado; no es una conclusión jurídica definitiva.

Los esquemas exactos pueden cambiar, por lo que las implementaciones deben utilizar la guía para desarrolladores de Checklynx y la definición OpenAPI actuales como contrato.

Varias partes permanecen vinculadas a una ejecución de transacción

La solicitud de transacción admite entre una y 100 partes. Las funciones documentadas actualmente son:

debtor, creditor, customer, counterparty, ultimate_debtor, ultimate_creditor, debtor_agent, creditor_agent, intermediary_agent y merchant.

Cada parte necesita una función y al menos un dato de cribado utilizable: un nombre, un documento de identidad o un instrumento de pago compatible. Un external_customer_id opcional permite asociar la parte con un cliente existente de Checklynx mediante el identificador estable del cliente. Si no se resuelve, Checklynx criba igualmente los datos aportados y deja la parte sin vincular en esa ejecución.

El modelo nativo de partes resulta útil cuando el ordenante, beneficiario, intermediario, comercio u otras funciones relevantes para la política deben permanecer conectados a la misma ejecución. La lista de funciones describe lo que admite la API, no qué partes está obligada jurídicamente a cribar una organización. El alcance debe ajustarse a los requisitos aplicables y a la política del cliente.

El perfil de cribado pertenece a la ejecución

La solicitud exige screening.screening_profile_id. Este identifica el perfil de cribado AML de Checklynx aplicado a la ejecución. Proporciona al flujo de transacciones un contexto de cribado configurado sin exigir que cada solicitud reproduzca todos los controles.

El modelo de solicitud examinado para POST /check/sanctions_pep no contiene screening_profile_id. En su lugar, expone controles directos como tolerancia de coincidencia, exclusiones y filtros. Esta es una diferencia práctica: un modelo invoca un perfil configurado para una ejecución de transacción; el otro envía una comprobación directa con parámetros de cribado en la solicitud.

Las cuentas bancarias y las direcciones de cartera se tratan de forma distinta

El modelo actual de partes admite los instrumentos de pago bank_account y wallet_address.

Para un instrumento bank_account documentado, la solicitud exige el número de cuenta y el BIC. Checklynx utiliza el BIC para el cribado de identidad frente a sanciones. El número de cuenta se conserva como evidencia complementaria de la ejecución, pero actualmente no se analiza, no se valida mediante suma de comprobación ni se criba por sí mismo. La descripción segura es, por tanto, «BIC cribado, número de cuenta guardado como evidencia», no una afirmación general de «cribado de IBAN».

Para un instrumento wallet_address, la dirección de cartera se utiliza en el cribado de identidad frente a sanciones. La red es opcional.

Ambos tipos admiten un external_instrument_id opcional del cliente. Puede devolverse con la ejecución, pero el contrato actual indica que no se incluye en los registros de coincidencias de casos ni en las cargas útiles de los webhooks. No debe ser la única clave de correlación entre sistemas para los casos.

Las comprobaciones de instrumentos de pago dependen de que el cribado de identidad frente a sanciones esté habilitado en el perfil seleccionado.

Los ID de negocio, ejecución y caso resuelven problemas distintos

El flujo de transacciones utiliza tres identificadores que no deben confundirse:

Cada POST /transactions crea una ejecución nueva, incluso si vuelve a enviarse el mismo transaction_reference_id. Este comportamiento permite nuevos cribados legítimos: varias ejecuciones pueden pertenecer a un mismo pago y conservar cada una su resultado y marca temporal. También implica que el cliente debe prevenir o conciliar envíos duplicados accidentales.

Guarde el id devuelto junto al registro de la transacción del cliente. GET /transactions/{id} recupera esa ejecución exacta. GET /transactions/references/{transaction_reference_id} devuelve un agregado de ejecuciones que comparten la referencia de negocio, y GET /transactions enumera agregados por referencia con filtrado y paginación documentados. Una consulta por referencia no debe tratarse como si identificara una ejecución única.

Esta distinción importa ante fallos inciertos. Si un llamante no sabe si una solicitud tuvo éxito, repetirla sin más puede crear otra ejecución. El cliente necesita un estado de envío y una estrategia de conciliación a nivel de aplicación; el contrato público actual no promete un procesamiento exactamente una vez.

Qué hace de forma distinta POST /check/sanctions_pep

El endpoint directo criba un objetivo frente a datos de sanciones, PEP y listas de personas buscadas. No crea un registro de cliente ni de caso, y su contrato público de respuesta no expone un objeto de transacción, una referencia de transacción del cliente ni un ID persistente equivalente al id de /transactions.

La solicitud proporciona exactamente uno de estos campos:

• search_term para una comprobación orientada a nombres, como el nombre de una persona, alias, empresa, buque o aeronave; o
• search_identity para una comprobación orientada a identificadores, como pasaporte, NIF, documento nacional, otro número documental, número IMO, valor de cartera o valor de cuenta bancaria compatible con el contrato actual.

La OpenAPI actual documenta los valores de tolerancia "0", "1" y "2", con "1" como valor predeterminado. También documenta filtros y exclusiones por tipo de fuente, tipo de grupo, nacionalidad, año de nacimiento y género. La respuesta se organiza en torno a results y match_profiles.

Debe describirse como un modelo de cribado directo sin un objeto persistente de transacción en Checklynx, no como garantía de que no existe absolutamente ningún almacenamiento backend o registro operativo. «Sin estado» es una expresión habitual del mercado, pero el contrato público no establece esa afirmación absoluta para Checklynx.

Cribar varias partes del pago con el endpoint directo

Si un cliente quiere cribar varias partes, llama al endpoint por separado para cada objetivo incluido y reconstruye la relación del pago en su propio sistema. Una asignación útil es:

ID de transacción del cliente → parte y función → payload y parámetros de solicitud → respuesta y perfiles de coincidencia → marca temporal → estado de revisión → resultado del flujo

Los identificadores de resultados o coincidencias devueltos no deben describirse como identificadores de ejecución de transacción. El cliente debe crear su propio registro de correlación antes de llamar a la API y actualizarlo de forma atómica a medida que cambien los resultados, la revisión y el estado del pago.

Este modelo puede encajar en una plataforma de pagos consolidada que ya disponga de sistema de casos, registro de eventos y repositorio de evidencias. Le permite controlar qué partes se comprueban, cuándo se realizan las llamadas, cómo se combinan las respuestas y dónde se revisan. Esa flexibilidad también transfiere más responsabilidad al cliente: las relaciones de funciones, protección frente a duplicados, persistencia, recuperación e historial de investigación no proceden de una ejecución nativa de Checklynx bajo este endpoint.

La documentación pública actual no documenta un mecanismo de idempotencia para POST /check/sanctions_pep, un webhook de finalización de comprobación independiente ni la creación automática de casos. Son límites precisos de la documentación, no afirmaciones de que sean imposibles capacidades internas no documentadas.

Comparación de arquitecturas

Ningún modelo elimina la necesidad de que el cliente conserve el estado de su transacción y la decisión final. La diferencia es cuánto de la ejecución, el contexto de partes y el vínculo de revisión se representa de forma nativa en Checklynx.

Implicaciones para las evidencias y la gestión de casos

Con /transactions, conserve como mínimo la referencia de negocio, el id de ejecución de Checklynx, los datos pertinentes de solicitud y correlación, el estado del sistema de pagos y la decisión posterior. La ejecución mantiene juntos el cribado y los resultados por parte. Cuando esté configurado y proceda, case_id conecta los resultados que requieren actuación con un flujo de revisión.

Con /check/sanctions_pep, el cliente necesita un registro reconstruible de cada comprobación: identificador de transacción, parte y función, marca temporal, dato aportado, parámetros y filtros, respuesta y perfiles, estado posterior, revisor, justificación y resultado. Es una recomendación arquitectónica basada en la ausencia de una estructura nativa de transacción/caso, no una afirmación de que Checklynx prescriba un esquema concreto de base de datos.

Las posibles coincidencias requieren evaluación. Deben entrar en el proceso de revisión y escalado aplicable, no tratarse como prueba automática de que la parte está sancionada. Consulte cómo documentar la investigación de una alerta de sanciones, Pista de auditoría y evidencias y Gestión de casos.

Autenticación, webhooks y protección frente a duplicados

La OpenAPI actual utiliza la cabecera x-api-key. Mantenga las claves en sistemas de servidor, fuera del código de clientes web o móviles. Los ejemplos exactos deben proceder de la documentación actual, no de ejemplos antiguos de marketing que puedan haberse desviado del contrato.

Para los eventos aplicables de casos de transacciones, Checklynx documenta transaction_screening.case.opened. Es un evento para un caso recién abierto debido a coincidencias que requieren actuación, no un callback para cada solicitud.

Los receptores de webhooks deben:

1. leer los bytes sin procesar de la solicitud;
2. calcular base64(HMAC-SHA256(signing_secret, raw_request_body));
3. comparar el resultado con X-Webhook-Signature antes de analizar o volver a serializar el JSON;
4. rechazar las firmas que no coincidan; y
5. deduplicar los reintentos mediante el event_id documentado.

La deduplicación de webhooks y la duplicación de solicitudes son controles distintos:

No describa la entrega de webhooks como exactamente una vez. El requisito de deduplicación documentado implica que los receptores deben esperar posibles reintentos.

Errores, reintentos y recuperación operativa

El contrato público documenta 429 como «Demasiadas solicitudes» e indica esperar y reintentar con backoff. No establece una cuota universal, espera fija, objetivo de latencia ni SLA que este artículo pueda prometer.

Separe los fallos por etapa. Un timeout de transporte no demuestra que no se haya creado una ejecución en el servidor. Una respuesta completa no demuestra que se haya actualizado el pago posterior o asignado el caso. Registre por separado el estado del envío, el ID devuelto, el estado de respuesta, la entrega posterior y la conciliación.

Evite copiar nombres completos, documentos, cuentas o direcciones de cartera en registros generales. Prefiera los mínimos ID de correlación, estado y metadatos de diagnóstico, y conserve evidencias sensibles solo en sistemas controlados.

¿Qué API encaja en su arquitectura de pagos?

Prefiera la API de cribado de transacciones cuando:

• varias partes deban permanecer vinculadas al mismo contexto de pago;
• resulte útil un registro duradero de ejecución en Checklynx;
• los analistas necesiten el contexto de transacción y partes en Checklynx;
• un mismo pago pueda cribarse varias veces y cada ejecución deba recuperarse por separado;
• importe consultar por ID de ejecución o referencia de negocio;
• los resultados deban poder vincularse a un caso de Checklynx; o
• la ejecución y las evidencias de revisión deban estar más estrechamente unidas en Checklynx.

Prefiera la API directa de sanciones y PEP cuando:

• la plataforma del cliente sea deliberadamente el sistema de registro;
• ya controle su arquitectura de casos, flujos y evidencias;
• la unidad de trabajo sea un objetivo directo;
• el cliente quiera coordinar por separado qué partes cribar;
• pueda conservar por sí mismo las relaciones entre transacción, función, solicitud, respuesta y revisor; o
• Checklynx deba actuar como servicio de cribado en una aplicación más amplia del cliente.

Ninguna es universalmente mejor. El modelo correcto es aquel cuyos límites de responsabilidad coinciden con los sistemas que operaciones, ingeniería y cumplimiento pueden sostener. Consulte flujos de integración AML, el flujo de cribado de transacciones y la API de cribado de sanciones y PEP en tiempo real.

Dónde encajan los lotes y dónde no

POST /check/sanctions_pep/batch acepta varios objetivos de cribado independientes y admite request_item_id para correlación por elemento. No convierte esas comprobaciones en una transacción nativa con referencia, partes relacionadas, ID de ejecución, recuperación por referencia ni relación con casos/webhooks de transacciones.

El cribado CSV también encaja con poblaciones definidas. No es una tercera arquitectura de propiedad de transacciones ni debe confundirse con la monitorización de comportamiento. Utilice la guía sobre API o cribado de sanciones por lotes cuando la decisión sea entre cribado basado en eventos y un ejercicio sobre una población.

El alcance de cumplimiento y las decisiones de pago siguen correspondiendo al cliente

Las funciones admitidas no definen qué partes deben cribarse. Los regímenes aplicables, la exposición y la política documentada determinan el alcance. Las directrices bancarias estadounidenses, por ejemplo, enmarcan los controles OFAC según el perfil de riesgo, productos, clientes, transacciones, geografías y tecnología disponible; no deben universalizarse como una regla para todos los sectores o países.

Una coincidencia es una señal para revisión, no automáticamente una coincidencia confirmada ni una disposición obligatoria del pago. Una respuesta clara tampoco constituye permiso jurídico universal: las restricciones pueden implicar propiedad, control, licencias, exenciones y hechos ajenos a una comparación de nombres.

Checklynx proporciona infraestructura de cribado y flujo de trabajo. El cliente define las transacciones y partes incluidas, aporta datos, evalúa posibles coincidencias y sigue siendo responsable del tratamiento del pago y de las decisiones jurídicas o de notificación. Para el diseño general, consulte la guía práctica sobre cribado de sanciones.

Lista de comprobación para implementar el cribado de pagos

Preguntas frecuentes

¿La API de sanciones y PEP carece de estado?

La afirmación arquitectónica segura es que POST /check/sanctions_pep no crea un cliente, un caso ni un objeto documentado de ejecución de transacción. El cliente controla el registro de transacción y flujo. El contrato público no establece que Checklynx no realice absolutamente ningún almacenamiento backend o registro operativo, por lo que una garantía absoluta de «sin estado» excedería la documentación.

¿Puede transaction_reference_id evitar ejecuciones duplicadas?

No. Es una referencia de negocio no única y no una clave de idempotencia. Cada POST /transactions crea una ejecución nueva. Guarde el id devuelto e implemente prevención y conciliación de duplicados en el cliente.

¿Cada coincidencia de transacción crea un caso de Checklynx?

No. case_id puede ser nulo. El contrato actual admite la creación o vinculación síncrona de casos para resultados aplicables, pero la integración no debe prometer que cada coincidencia produzca automáticamente un caso.

¿El endpoint de transacciones criba el número de cuenta bancaria?

Para el instrumento bank_account documentado actualmente, se utiliza el BIC para el cribado de identidad frente a sanciones. El número de cuenta se conserva como evidencia, pero actualmente no se analiza, valida mediante suma de comprobación ni criba por sí mismo.

¿Existe un webhook para cada respuesta directa de la API de sanciones y PEP?

El catálogo público actual no documenta un webhook de finalización independiente para POST /check/sanctions_pep. El evento de transacción documentado se refiere a un caso recién abierto, no a cada llamada.

¿Alguna de las API decide si debe liberarse o detenerse un pago?

No. El cliente utiliza los resultados dentro de su política y marco jurídico. Una posible coincidencia requiere evaluación y la actuación correcta depende del régimen y de los hechos aplicables.

Elija el modelo de API que corresponda a su sistema de registro

Utilice el cribado de transacciones de Checklynx cuando las partes, los resultados y las evidencias de revisión deban permanecer conectados en una ejecución duradera. Utilice la API de sanciones y PEP cuando su plataforma conserve el flujo de la transacción y Checklynx aporte la respuesta directa.

La elección debe ser explícita antes de implementar: determina los identificadores, la persistencia, la coordinación de varias partes, el traspaso a casos, la protección frente a duplicados y las evidencias que debe conservar cada sistema.