La API de Solicitudes de Evidencia de Cobre proporciona un mecanismo seguro, auditable y estructurado para solicitar, recopilar y revisar documentación e información de respaldo requerida para procesos de cumplimiento, prevención de fraudes y gestión de riesgos.

Este servicio transversal se integra con recursos centrales de la plataforma como Movimientos de Dinero, Contrapartes y Destinos, permitiendo que Cobre y los clientes colaboren de manera eficiente cuando se requiere evidencia adicional para satisfacer controles regulatorios o internos.

Las Solicitudes de Evidencia siguen un ciclo de vida claro impulsado por notificaciones, cargas seguras y envíos estructurados, asegurando transparencia, trazabilidad y confiabilidad operacional.

Creación de Solicitudes de Evidencia (Resumen Conceptual)

Las Solicitudes de Evidencia son iniciadas por Cobre y entregadas a los clientes a través de Notificaciones y Suscripciones.
Los clientes no crean solicitudes de evidencia directamente, sino que reaccionan a ellas enviando los documentos e información requeridos.

Para recibir Solicitudes de Evidencia, los clientes deben suscribirse al evento:

evidence-request.ask

Una vez suscritos, los clientes recibirán un webhook cada vez que se cree una nueva solicitud de evidencia.

Ciclo de Vida de las Solicitudes de Evidencia

Notificación
Se envía un webhook al cliente con el evidence_request_id, fecha límite, contexto y tipos de evidencia requeridos.

Envío de Evidencia
Los clientes envían la evidencia solicitada a través de:

Documentos → Cargados usando URLs firmadas

Información → Enviada como cargas útiles JSON estructuradas

Finalización
Una vez que se completa el envío (o expira la fecha límite), la solicitud transiciona a completed.

Los clientes pueden enviar evidencia solo una vez por solicitud de evidencia. No se permiten envíos posteriores.

Notificación de Solicitud de Evidencia

Los clientes reciben solicitudes de evidencia a través de la API de Notificaciones cuando están suscritos a evidence-request.ask.

Esquema de Notificación

{
  "id": "ev_1234567890",
  "event_key": "evidence-request.ask",
  "event_type": "EvidenceRequest",
  "timestamp": "2024-06-01T12:00:00.000Z",
  "content": {
    "evidence_request_id": "evr_01923801823",
    "evidence_request_context": {
      "counterparty_id": "cp_456"
    },
    "evidence_request_description": "Please provide the required documents and information.",
    "evidence_requested": {
      "documents": ["doc_funds"],
      "information": ["information_counterparty_id"]
    }
  }
}

Contexto de Solicitud de Evidencia

El objeto evidence_request_context identifica qué desencadenó la solicitud de evidencia y ayuda a los clientes a correlacionarla con sus sistemas internos.

Campos de Contexto

Campo	Descripción
`counterparty_id`	Contraparte asociada con la solicitud
`mm_id`	Movimiento de Dinero que desencadenó la solicitud
`destination_id`	Identificador del recurso de destino
`destination_type`	Tipo de identificador de destino (ej., RFC, NIT)
`destination_number`	Número de identificación del destino
`destination_fullname`	Nombre completo del destino
`destination_account_number`	Número de cuenta del destino
`destination_providers_id`	Identificador de destino específico del proveedor

No todos los campos están presentes en cada solicitud. El contexto depende de lo que desencadenó la solicitud de evidencia.

Catálogo de Tipos de Evidencia

La evidencia puede solicitarse en dos formatos: Documentos e Información.

Tipos de Documento

Tipos de Información

Tipo de Documento	Evidencia Esperada
`doc_funds`	Comprobante de fondos y justificación para movimientos de dinero inusuales
`official_identification_copy`	ID emitido por el gobierno (pasaporte, licencia de conducir, etc.)
`identification_and_address_copy`	ID emitido por el gobierno más comprobante de domicilio

Esquema de Información

Cuando el tipo de información solicitado es information_counterparty_id, debe enviarse la siguiente carga útil estructurada:

{
  "data": {
    "full_name": "string",
    "country_of_birth": "string",
    "date_of_birth": "yyyy-mm-dd",
    "address": {
      "city": "string",
      "country": "string",
      "address_line_1": "string",
      "number": "string",
      "zip_code": "string"
    },
    "document": {
      "id_nationality": "string",
      "id_type": "string",
      "id_number": "string"
    },
    "occupation": "string",
    "phone_number": "string",
    "email": "string",
    "gender": "string"
  }
}

Acciones realizadas en Solicitudes de Evidencia

🔍 Recuperación

📄 Obtener por ID

⬆️ Cargar Documentos

⬇️ Descargar Documentos

📨 Enviar Información

Descripción: Buscar y recuperar solicitudes de evidencia usando filtros como estado, fecha de creación y fecha de actualización.

Qué esperar después de la acción:
Una lista paginada de objetos de Solicitud de Evidencia incluyendo estado, fechas límite y evidencia requerida.

📘 Aprende más: 🔗 Obtener todas las Solicitudes de Evidencia

Objeto Solicitud de Evidencia

Una Solicitud de Evidencia representa un caso único de investigación de cumplimiento o riesgo.

Atributos Clave

Campo	Descripción
`id`	Identificador único de la solicitud de evidencia
`reference_id`	Referencia externa (caso, transacción, proceso)
`expiration_date`	Fecha límite para enviar evidencia
`status`	`initiated`, `pending_information`, `completed`
`evidence_requested`	Documentos e información requeridos
`evidence_documents`	Documentos cargados
`evidence_information`	Información estructurada enviada
`created_at`	Marca de tiempo de creación
`updated_at`	Marca de tiempo de última actualización

Cómo Comenzar

Suscríbete a las notificaciones de solicitudes de evidencia

Suscríbete al evento evidence-request.ask usando la API de Notificaciones y Suscripciones.

Recibe y procesa el webhook

Captura el evidence_request_id, contexto y evidencia requerida de la carga útil del webhook.

Carga los documentos solicitados

Genera URLs de carga y carga de forma segura los documentos solicitados.

Envía la información requerida

Proporciona información estructurada usando el endpoint de envío.

Monitorea la finalización de la solicitud

Recupera la solicitud de evidencia para verificar su estado final.

Qué esperar después de usar esta API

Preparación para el cumplimiento regulatorio

Responde de manera eficiente a solicitudes de evidencia relacionadas con cumplimiento y fraude.

Manejo seguro de evidencia

Asegura que la información sensible se transmita usando URLs firmadas y esquemas estructurados.

Transparencia operacional

Mantén un registro de auditoría completo de solicitudes de evidencia y envíos.

Trazabilidad entre funciones

Vincula las solicitudes de evidencia de vuelta a movimientos de dinero, contrapartes y destinos.

API de Evidencia

Creación de Solicitudes de Evidencia (Resumen Conceptual)#

Ciclo de Vida de las Solicitudes de Evidencia#

Notificación de Solicitud de Evidencia#

Esquema de Notificación#

Contexto de Solicitud de Evidencia#

Campos de Contexto#

Catálogo de Tipos de Evidencia#

Esquema de Información#

Acciones realizadas en Solicitudes de Evidencia#

Objeto Solicitud de Evidencia#

Atributos Clave#

Cómo Comenzar#

Qué esperar después de usar esta API#

Creación de Solicitudes de Evidencia (Resumen Conceptual)

Ciclo de Vida de las Solicitudes de Evidencia

Notificación de Solicitud de Evidencia

Esquema de Notificación

Contexto de Solicitud de Evidencia

Campos de Contexto

Catálogo de Tipos de Evidencia

Esquema de Información

Acciones realizadas en Solicitudes de Evidencia

Objeto Solicitud de Evidencia

Atributos Clave

Cómo Comenzar

Qué esperar después de usar esta API