Plan Corporativo · v1 EstableREST HTTPS · JSON120 req/h · 500 reg/lote

Conecta tu sistema una vez y deja de subir archivos.

Tus clientes y operaciones llegan solos a PLDUnity, listos para umbrales, listas y avisos. Diseñado para sujetos obligados con volumen alto u operación continua (casinos y apuestas en línea, activos virtuales, tarjetas y prepago, financieras) y para sus equipos de TI.

Solicitar acceso a la API (Plan Corporativo)Probar simulador interactivo Ver ficha técnica

REQUESTGET /ping

// Cargando payload ficticio...

AuthorizationBearer pldbdu_test_mock_ficticio_0000...

Content-Typeapplication/json; charset=utf-8

User-AgentPLDUnity-MockSimulator/1.0

Acceptapplication/json

# Generando comando cURL ficticio...

RESPONSE200 OK

34 msMock OK

// Presiona "Ejecutar Petición" para simular...

Conexión Verificada (Simulación)

Llave de API ficticia identificada. Permisos validados contra la huella SHA-256 de prueba.

Qué es y Beneficios

Diseñado para Operación Continua sin Archivos Manuales

La API de PLDUnity conecta el sistema del cliente (su gestor de usuarios, back-office o caja) con la plataforma de cumplimiento PLD para dar de alta expedientes y enviar operaciones sin subir hojas de cálculo.

Sin capturas ni archivos

Los clientes y las operaciones llegan directamente desde tu sistema. Cada usuario se convierte en un expediente en PLDUnity sin subir archivos manuales.

Ingesta Directa

Expedientes siempre al día

Cada alta o cambio en tu gestor actualiza el expediente en PLDUnity, con su grado de riesgo inicial y en cola para la revisión en listas.

Sincronización Continua

Mismas reglas que la plataforma

Lo que entra por API pasa por la misma validación, umbrales en UMA del año, acumulación mensual y semestral por cliente, expedientes y aviso XML.

Motor Normativo

Idempotente y seguro de reintentar

Enviar el mismo lote dos veces no duplica nada. Tu equipo de TI puede reintentar envíos ante cortes de red con certeza de integridad.

Cero Duplicados

Respuesta renglón por renglón

Cada cliente u operación rechazada trae su motivo específico e índice dentro del lote, devolviendo la clave calculada para cada registro aceptado.

Detalle por Renglón

Avisos por Webhooks firmados

Avisos automáticos al sistema del cliente mediante webhooks firmados con HMAC-SHA256 cuando se genera un XML o cambia una verificación de identidad.

Eventos Firmados

Simular flujo en el clúster 3D:

Torre Core PLD y compuertas de ingesta (/clientes y /operaciones)Puente de deduplicación idempotente y trineo de lote (500 registros)Indicador radial de acumulación mensual/semestral en UMA del año

Ficha Técnica

Arquitectura REST, Seguridad de Llaves y Esquemas

Formato REST sobre HTTPS con JSON de entrada y salida. Llaves generadas con 32 bytes aleatorios, almacenadas únicamente como huella SHA-256 y registradas en bitácora de auditoría.

URL Base y Formato

https://app.pldunity.com/api/v1

REST sobre HTTPS (TLS 1.3), JSON de entrada y salida en todos los endpoints.

Autenticación y Seguridad de Llaves

Authorization: Bearer pldbdu_...

También se acepta X-API-Key. Se generan con 32 bytes aleatorios, se guardan solo como hash SHA-256, son revocables y registran su último uso.

Permisos por Llave (Scopes)

clientes (enviar y consultar expedientes)operaciones (enviar operaciones)

Cada alta por API queda registrada automáticamente en la bitácora de auditoría de la plataforma.

Límite y Capacidad por Petición

120 peticiones / hora · Hasta 500 registros / lote

120 peticiones por hora por llave; hasta 500 clientes u operaciones por petición.

Inspeccionar validador de llave:

Lector de token Bearer y rotor de 32 divisiones (32 bytes)6 pines comparan la huella SHA-256 con el hash guardado (la plataforma nunca guarda la llave en claro)Compuertas de permisos independientes (clientes y operaciones), indicador de 120 peticiones/hora y bitácora de auditoría

Tabla de Endpoints (API v1)

Base: https://app.pldunity.com/api/v1

Método	Ruta	Permiso (Scope)	Para qué
GET	`/ping`	Cualquiera	Probar la llave; devuelve la empresa y el prefijo de la llave.
POST	`/clientes`	clientes	Alta y actualización de hasta 500 expedientes por lote.
GET	`/clientes`	clientes	Listar expedientes; filtros `limite` (1–200), `rfc`, `idExterno`, `desde` (fecha ISO).
GET	`/clientes/{clave}`	clientes	Un expediente por su clave (o `/clientes/_?idExterno=...`).
POST	`/operaciones`	operaciones	Hasta 500 operaciones por lote, con `periodo` (año y mes) y tipo de movimiento opcional (depósitos o retiros).

POST /clientes

Clientes: Campos y Reglas de Expediente

Obligatorios:idExterno (el ID en el sistema del cliente) y rfc (12 o 13 caracteres).
Regla para RFC genérico:Para XEXX010101000 (extranjero) y XAXX010101000 (público en general) también son obligatorios nombreCliente y apellidoPaterno; así cada persona queda en su propio expediente individualizado.
Opcionales:apellidoMaterno, curp, fechaNacimiento (AAAA-MM-DD), tipoPersona (FISICA o MORAL), actuaNombrePropio, domicilio y contacto, actividad económica, nacionalidad, país y beneficiario controlador.
Cálculo de clave:La plataforma calcula la clave del expediente a partir del RFC (o del RFC genérico más el nombre) y la devuelve en clave para que el sistema del cliente la guarde.

Ejemplo de respuesta de POST /clientes (Ficticio):

{
  "ok": true,
  "recibidos": 1,
  "creados": 1,
  "actualizados": 0,
  "rechazados": 0,
  "resultados": [
    {
      "index": 0,
      "idExterno": "ID-FICTICIO-001",
      "clave": "MOCK010101XYZ",
      "estado": "creado"
    }
  ]
}

POST /operaciones

Operaciones: Campos y Acumulación UMA

Obligatorios por operación:fechaOperacion (AAAA-MM-DD), monto (> 0) y rfcCliente, o bien nombreCliente + apellidoPaterno.
Parámetros de lote:Incluye periodo (año y mes) y tipo de movimiento opcional (depósitos o retiros), con hasta 500 operaciones por petición.
Opcionales por actividad:Tipo de operación, moneda, instrumento monetario, datos del cliente y su domicilio, beneficiario controlador, y campos de juego (tipo de juego, cuenta, folio, premio).
Respuesta detallada:Informa operaciones procesadas, rechazadas, duplicadas omitidas, con advertencias, resumen de riesgo en UMA y el lote creado.

Ejemplo de respuesta de POST /operaciones (Ficticio):

{
  "ok": true,
  "loteId": "LOTE-MOCK-2026-001",
  "procesadas": 1,
  "rechazadas": 0,
  "duplicadasOmitidas": 0,
  "conAdvertencias": 0,
  "resumenRiesgo": {
    "cliente": "MOCK010101XYZ",
    "superaUmbralAvisoUMA": true
  }
}

Cómo se Conecta y Webhooks

Flujo de Integración en 5 Pasos

Configura tu acceso en minutos desde el panel de administrador y recibe notificaciones reactivas firmadas criptográficamente.

Genera tu llave de API

El administrador genera una llave en la plataforma (Cargar operaciones → Conectar mi sistema, o Configuración → API Keys) y elige sus permisos (clientes, operaciones).

Huella única SHA-256

La llave se muestra una sola vez; la plataforma guarda solo su huella (hash SHA-256). Si se pierde, se revoca y se genera otra al instante.

Envío en lotes

El sistema del cliente envía clientes y operaciones a la API en lotes de hasta 500 registros, guardando la clave devuelta para cada expediente.

Webhooks firmados (Opcional)

Configura webhooks con firma HMAC-SHA256 para recibir avisos cuando se genera un XML o cambia una verificación de identidad.

Documentación en plataforma

La documentación interactiva completa y la bitácora de auditoría están dentro de la plataforma, en la sección de documentación de la API.

Especificación Técnica de Webhooks Firmados

POST a la URL que configure el cliente, firmado con HMAC-SHA256 usando el secreto del webhook.

X-PLDBDU-Event: Nombre del evento disparado.
X-PLDBDU-Signature: Firma criptográfica HMAC-SHA256 del cuerpo.
X-PLDBDU-Delivery: ID único de entrega para descartar duplicados.

Política de reintentos automáticos: Si la entrega falla (sin respuesta, 408, 429 o 5xx), PLDUnity reintenta a 1 min, 5 min, 30 min, 2 h y 12 h con el mismo cuerpo y el mismo ID de entrega. Tiempo de espera por intento: 10 segundos.

Eventos Activos

xml_generatedCuando se genera un archivo XML de aviso en la plataforma.

threshold_reachedCuando un cliente alcanza el umbral de identificación o de aviso en UMA.

payment_failedNotificación administrativa de pago fallido en la cuenta.

operation_flaggedCuando una operación es marcada por reglas de monitoreo o alerta.

verification_submittedVerificación de identidad enviada por el cliente.

verification_completedVerificación de identidad terminada (aprobada o rechazada).

verification_resubmission_requestedVerificación con solicitud de corrección o reenvío de documento.

verification_expiredEl enlace o sesión de verificación venció sin completarse.

Probar despachador 3D:

Cámara de sellado HMAC-SHA256, cronómetro de 10s y antena de despachoBanco escalonado de 5 etapas de reintento (1 min, 5 min, 30 min, 2 h, 12 h)Conservación del mismo X-PLDBDU-Delivery en cada reintento para evitar duplicados

Catálogo de Errores

Respuestas Legibles con ok: false

JSON con ok: false y un mensaje legible en cada código de estado HTTP para facilitar la depuración y los reintentos automáticos.

400 Bad Request

Datos inválidos o campos obligatorios faltantes; en envíos por lotes, devuelve el detalle renglón por renglón con su index.

401 Unauthorized

Llave de API ausente en el encabezado o previamente revocada por el administrador.

403 Forbidden

La llave es válida pero no tiene el permiso (scope clientes u operaciones) requerido para la ruta.

404 / 405

404 Not Found (expediente o ruta inexistente) o 405 Method Not Allowed (verbo HTTP incorrecto).

409 Conflict

Conflicto de integridad: existe más de un expediente registrado con el mismo idExterno.

429 Too Many Requests

Se alcanzó el límite de 120 peticiones por hora para la llave. Aplicar reintento con espera creciente.

503 Service Unavailable

Servicio de autenticación temporalmente no disponible; seguro de reintentar con espera creciente.

Buenas Prácticas para el Integrador

Lotes de 200 a 500 registros:Agrupa tus envíos en lotes de 200 a 500 clientes u operaciones y aplica reintento con espera creciente (backoff exponencial) ante códigos 429 y 503.
Guardar la clave de cada expediente:Almacena en tu base de datos la clave devuelta por POST /clientes para futuras consultas directas.
Reconciliación nocturna con GET /clientes?desde=...:Sincroniza deltas en un proceso nocturno usando el parámetro ISO desde en lugar de reenviar todo el padrón.
Sin borrado por API (Conservación regulatoria):No existe endpoint para borrar clientes; los expedientes se conservan íntegros por obligación regulatoria de la LFPIORPI.

Alcance Operativo y Regulatorio

Generación y presentación del XML al SAT:El archivo XML oficial se genera dentro de la plataforma PLDUnity y se presenta en el portal del SAT (no se presenta al SAT por API).

Screening en barrido diario:Al dar de alta un cliente por API, su expediente recibe su grado de riesgo inicial y entra en cola para ser cotejado en el barrido diario contra listas.

Conexión estándar HTTPS REST:Integración directa mediante JSON y llaves de API Bearer desde cualquier lenguaje de programación, sin requerir SDKs propietarios ni flujos OAuth complejos.

Incluido en el Plan Corporativo

Conecta tu sistema una vez y automatiza tu cumplimiento PLD

La API REST (https://app.pldunity.com/api/v1) y los webhooks con reintentos forman parte del Plan Corporativo de PLDUnity (desde $19,900 MXN/mes + IVA). Solicita acceso con el equipo de BDUnity.

Solicitar Plan Corporativo con BDU Ver planes y precios