Listas Oficiales

JAAK - Versión 2.0

1. Introducción

El API de Listas Oficiales de JAAK permite realizar consultas de verificación contra diferentes bases de datos oficiales de México y organismos internacionales. Este servicio es fundamental para procesos de KYC (Know Your Customer) y verificación de identidad.

1.1 Endpoints

Sandbox (Desarrollo)

POST https://sandbox.api.jaak.ai/api/v2/blacklist/investigate

Producción

POST https://services.api.jaak.ai/api/v2/blacklist/investigate

1.2 Autenticación

El API utiliza autenticación mediante Bearer Token. Debes incluir tu token de API en el header Authorization:

Authorization: Bearer {tu_token_de_api}

1.3 Servicios Disponibles

El API soporta los siguientes servicios de verificación:

CURP - Validación de CURP contra la base de datos de RENAPO
INE - Verificación de credencial de elector del INE
OFAC - Consulta de listas de sanciones de la Oficina de Control de Activos Extranjeros (EEUU)
SAT69B - Consulta de lista 69-B del SAT
INTERPOL - Búsqueda en listas de INTERPOL

2. Servicio CURP

El servicio de CURP permite validar una Clave Única de Registro de Población contra la base de datos oficial de RENAPO (Registro Nacional de Población).

2.1 Request

Estructura del Request

{
    "eventId": "example_event_id",
    "services": {
        "renapo": {
            "curp": true
        }
    },
    "payload": {
        "identifications": {
            "curp": "GOMA900101HDFRRL09"
        }
    }
}

Parámetros

Campo	Tipo	Descripción
`eventId`	String	Identificador único del evento
`services.renapo.curp`	Boolean	Activar servicio de validación de CURP (true)
`payload.identifications.curp`	String	CURP a validar (18 caracteres)

2.2 Response

El servicio retorna información completa de la persona registrada con el CURP:

{
    "eventId": "abc123-def456-ghi789",
    "responseId": "",
    "processTime": 0,
    "organization": "curp",
    "service": "validaCurp",
    "result": {
        "validaCurp": {
            "content": {
                "codeError": "0",
                "curp": "GOMA900101HDFRRL09",
                "error": "False",
                "errorMessage": "",
                "personalDataBirthDate": "1990-01-01",
                "personalDataBirthEntity": "CIUDAD DE MEXICO",
                "personalDataFirstName": "JUAN",
                "personalDataGender": "HOMBRE",
                "personalDataLastName": "GOMEZ",
                "personalDataNationality": "MEX",
                "personalDataSecondLastName": "MARTINEZ",
                "probativeDocActNumber": "00123",
                "probativeDocProbativeDoc": "",
                "probativeDocRegistrationEntity": "CIUDAD DE MEXICO",
                "probativeDocRegistrationMunicipality": "BENITO JUAREZ",
                "probativeDocRegistrationYear": "1990",
                "statusCURP": "RCN",
                "valid": "true"
            }
        }
    },
    "state": {
        "message": "",
        "foundInService": true,
        "mustBeFound": true
    }
}

Campos de la Respuesta

Campo	Descripción
`personalDataFirstName`	Nombre(s) de la persona
`personalDataLastName`	Apellido paterno
`personalDataSecondLastName`	Apellido materno
`personalDataBirthDate`	Fecha de nacimiento (formato: YYYY-MM-DD)
`personalDataGender`	Género (HOMBRE/MUJER)
`personalDataBirthEntity`	Entidad de nacimiento
`personalDataNationality`	Nacionalidad (código ISO)
`probativeDocActNumber`	Número de acta de nacimiento
`probativeDocRegistrationEntity`	Entidad de registro
`probativeDocRegistrationMunicipality`	Municipio de registro
`probativeDocRegistrationYear`	Año de registro
`statusCURP`	Estado del CURP (RCN: Registrado y Certificado por RENAPO)
`valid`	Indica si el CURP es válido (true/false)

3. Servicio INE

El servicio de INE permite verificar la autenticidad de una credencial de elector mediante la validación de sus números de identificación (CIC y OCR).

3.1 Request

Estructura del Request

{
    "eventId": "example_event_id",
    "services": {
        "ine": true
    },
    "payload": {
        "identifications": {
            "ine": {
                "cic": "123456789",
                "ocr": "1234567890123"
            }
        }
    }
}

Parámetros

Campo	Tipo	Descripción
`eventId`	String	Identificador único del evento
`services.ine`	Boolean	Activar servicio de verificación de INE (true)
`payload.identifications.ine.cic`	String	Clave de Identificación del Ciudadano (9 dígitos)
`payload.identifications.ine.ocr`	String	Número OCR de la credencial (13 dígitos)

3.2 Response

Si la credencial es válida, el servicio retorna:

{
    "eventId": "def456-abc789-ghi012",
    "responseId": "",
    "processTime": 0.5180230140686035,
    "organization": "ine",
    "service": "all",
    "result": null,
    "state": {
        "message": "Investigation completed successfully",
        "foundInService": true,
        "mustBeFound": true
    }
}

Nota: El campo foundInService: true indica que la credencial es válida. Si es false, significa que la credencial no fue encontrada o es inválida.

4. Servicio OFAC

El servicio OFAC permite consultar si una persona se encuentra en las listas de sanciones de la Office of Foreign Assets Control (OFAC) del Departamento del Tesoro de Estados Unidos. Estas listas incluyen individuos y entidades sancionadas por actividades relacionadas con narcotráfico, terrorismo, proliferación de armas, y otras amenazas a la seguridad nacional.

4.1 Request

Estructura del Request

{
    "eventId": "example_event_id",
    "services": {
        "ofac": true
    },
    "payload": {
        "person": {
            "name": "JUAN",
            "lastName": "PEREZ",
            "secondName": "",
            "secondLastName": "GARCIA"
        },
        "extras": {
            "commonId": "",
            "wantedIn": "MEX"
        }
    }
}

Parámetros

Campo	Tipo	Descripción
`eventId`	String	Identificador único del evento
`services.ofac`	Boolean	Activar servicio de búsqueda OFAC (true)
`payload.person.name`	String	Nombre de la persona
`payload.person.lastName`	String	Apellido paterno
`payload.person.secondName`	String	Segundo nombre (opcional)
`payload.person.secondLastName`	String	Apellido materno (opcional)
`payload.extras.commonId`	String	ID común para búsqueda (opcional)
`payload.extras.wantedIn`	String	País de búsqueda (código ISO 3166-1 alpha-3)

4.2 Response

Si se encuentran coincidencias en las listas OFAC:

{
    "eventId": "mno345-pqr678-stu901",
    "responseId": "",
    "processTime": 21.192708730697632,
    "organization": "ofac",
    "service": "coincidences",
    "result": {
        "0": {
            "content": {
                "address": "Calle Principal No. 123, Colonia Centro",
                "city": "",
                "country": "All",
                "idNumber": "",
                "lookupId": "12345",
                "lookupType": "Individual",
                "minimumNameScore": "90",
                "name": "PEREZ GARCIA, Juan",
                "programLists": "SDN",
                "programs": "SDNTK",
                "sanctionProgram": "All",
                "score": "100",
                "searchType": "Individual",
                "state": ""
            }
        }
    },
    "state": {
        "message": "Investigation completed successfully",
        "foundInService": true,
        "mustBeFound": false
    }
}

Si NO se encuentran coincidencias:

{
    "eventId": "mno345-pqr678-stu901",
    "responseId": "",
    "processTime": 15.5,
    "organization": "ofac",
    "service": "coincidences",
    "result": null,
    "state": {
        "message": "Investigation completed successfully",
        "foundInService": false,
        "mustBeFound": false
    }
}

Campos de la Respuesta (cuando hay coincidencias)

Campo	Descripción
`name`	Nombre completo registrado en la lista OFAC
`score`	Porcentaje de coincidencia (0-100)
`lookupId`	Identificador único en la lista OFAC
`lookupType`	Tipo de entrada (Individual, Entity)
`programLists`	Lista de programa (SDN: Specially Designated Nationals)
`programs`	Programa de sanciones específico (SDNTK: Narcotics Trafficking Kingpin)
`address`	Dirección conocida
`minimumNameScore`	Score mínimo configurado para la búsqueda
`sanctionProgram`	Programa de sanción aplicable

Nota: foundInService: true es un resultado NEGATIVO, indica que la persona SÍ está en las listas de sanciones de OFAC. Si el valor es false, significa que la persona NO aparece en las listas (resultado positivo).

5. Servicio SAT69B

El servicio SAT69B permite consultar si un RFC se encuentra en la lista negativa del SAT (Lista 69-B), que contiene contribuyentes con operaciones inexistentes o simuladas.

5.1 Request

Estructura del Request

{
    "eventId": "example_event_id",
    "services": {
        "sat69b": true
    },
    "payload": {
        "identifications": {
            "rfc": "AAA010101AAA"
        }
    }
}

Parámetros

Campo	Tipo	Descripción
`eventId`	String	Identificador único del evento
`services.sat69b`	Boolean	Activar servicio de consulta SAT 69-B (true)
`payload.identifications.rfc`	String	RFC a consultar (12 o 13 caracteres)

5.2 Response

Si el RFC NO está en la lista 69-B (resultado positivo):

{
    "eventId": "ghi789-jkl012-mno345",
    "responseId": "",
    "processTime": 0.16448426246643066,
    "organization": "sat",
    "service": "sat69b",
    "result": null,
    "state": {
        "message": "Investigation completed successfully",
        "foundInService": false,
        "mustBeFound": false
    }
}

Nota: foundInService: false es un resultado POSITIVO, indica que el RFC NO está en la lista negativa. Si el valor es true, significa que el RFC SÍ está en la lista 69-B.

6. Servicio INTERPOL

El servicio INTERPOL permite consultar si una persona se encuentra en las listas de búsqueda internacional de INTERPOL (difusiones rojas, azules, verdes, amarillas, naranjas, moradas y negras).

6.1 Request

Estructura del Request

{
    "eventId": "example_event_id",
    "services": {
        "interpol": true
    },
    "payload": {
        "person": {
            "name": "JUAN",
            "lastName": "PEREZ",
            "secondName": "",
            "secondLastName": "GARCIA",
            "nationality": "MEX"
        },
        "extras": {
            "wantedIn": "MEX"
        }
    }
}

Parámetros

Campo	Tipo	Descripción
`eventId`	String	Identificador único del evento
`services.interpol`	Boolean	Activar servicio de búsqueda INTERPOL (true)
`payload.person.name`	String	Nombre de la persona
`payload.person.lastName`	String	Apellido paterno
`payload.person.secondLastName`	String	Apellido materno (opcional)
`payload.person.nationality`	String	Código de nacionalidad ISO 3166-1 alpha-3 (ej: MEX, USA, FRA)
`payload.extras.wantedIn`	String	País donde está siendo buscado (opcional)

6.2 Response

Si la persona NO está en las listas de INTERPOL:

{
    "eventId": "jkl012-mno345-pqr678",
    "responseId": "",
    "processTime": 0.09499883651733398,
    "organization": "interpol",
    "service": "all",
    "result": null,
    "state": {
        "message": "Investigation completed successfully",
        "foundInService": false,
        "mustBeFound": false
    }
}

Nota: foundInService: false es un resultado POSITIVO, indica que la persona NO está en las listas de INTERPOL. Si el valor es true, significa que la persona SÍ aparece en alguna lista de búsqueda.

7. Códigos de Estado HTTP

El API utiliza códigos de estado HTTP estándar para indicar el resultado de las peticiones:

Código	Descripción
200	OK - La solicitud se procesó correctamente
400	Bad Request - Error en los parámetros enviados
401	Unauthorized - Token de autenticación inválido o no proporcionado
403	Forbidden - No tiene permisos para acceder al servicio solicitado
429	Too Many Requests - Se ha excedido el límite de peticiones
500	Internal Server Error - Error interno del servidor

8. Ejemplos de Uso

Ejemplo 1: Validar CURP

curl -X POST https://services.api.jaak.ai/api/v2/blacklist/investigate \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "mi_evento_123",
    "services": {
        "renapo": {
            "curp": true
        }
    },
    "payload": {
        "identifications": {
            "curp": "GOMA900101HDFRRL09"
        }
    }
}'

Ejemplo 2: Verificar INE

curl -X POST https://services.api.jaak.ai/api/v2/blacklist/investigate \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "mi_evento_456",
    "services": {
        "ine": true
    },
    "payload": {
        "identifications": {
            "ine": {
                "cic": "123456789",
                "ocr": "1234567890123"
            }
        }
    }
}'

Ejemplo 3: Consultar en OFAC

curl -X POST https://services.api.jaak.ai/api/v2/blacklist/investigate \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "mi_evento_789",
    "services": {
        "ofac": true
    },
    "payload": {
        "person": {
            "name": "JUAN",
            "lastName": "PEREZ",
            "secondLastName": "GARCIA"
        },
        "extras": {
            "wantedIn": "MEX"
        }
    }
}'

Ejemplo 4: Consultar RFC en SAT69B

curl -X POST https://services.api.jaak.ai/api/v2/blacklist/investigate \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "mi_evento_789",
    "services": {
        "sat69b": true
    },
    "payload": {
        "identifications": {
            "rfc": "AAA010101AAA"
        }
    }
}'

Ejemplo 5: Buscar en INTERPOL

curl -X POST https://services.api.jaak.ai/api/v2/blacklist/investigate \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "mi_evento_101",
    "services": {
        "interpol": true
    },
    "payload": {
        "person": {
            "name": "JUAN",
            "lastName": "PEREZ",
            "secondLastName": "GARCIA",
            "nationality": "MEX"
        },
        "extras": {
            "wantedIn": "MEX"
        }
    }
}'

9. Mejores Prácticas

9.1 Gestión de EventId

Usa identificadores únicos para cada petición (UUID recomendado)
Almacena el eventId para trazabilidad y auditoría
Útil para debugging y soporte técnico

9.2 Manejo de Errores

Implementa reintentos con backoff exponencial para errores 5xx
No reintentes errores 4xx (requieren corrección de parámetros)
Valida parámetros localmente antes de enviar la petición

9.3 Seguridad

Nunca expongas tu token de API en el frontend
Almacena tokens en variables de entorno
Implementa rate limiting en tu aplicación
Usa HTTPS para todas las peticiones

9.4 Performance

Implementa caché para consultas repetidas (especialmente CURP e INE)
Procesa requests en lotes cuando sea posible
Monitorea el tiempo de respuesta (processTime)

10. Interpretación de Resultados

Campo `foundInService`

El campo foundInService tiene diferentes interpretaciones según el servicio:

Servicio	`foundInService: true`	`foundInService: false`
CURP	CURP válido y encontrado	CURP inválido o no encontrado
INE	Credencial válida	Credencial inválida
OFAC	Persona SÍ está en listas de sanciones (❌ malo)	Persona NO está en listas (✅ bueno)
SAT69B	RFC SÍ está en lista negativa (❌ malo)	RFC NO está en lista negativa (✅ bueno)
INTERPOL	Persona SÍ está en listas (❌ malo)	Persona NO está en listas (✅ bueno)

Campo `mustBeFound`

mustBeFound: true - Se espera que el dato sea encontrado (CURP, INE)
mustBeFound: false - Se espera que el dato NO sea encontrado (SAT69B, INTERPOL)

11. Límites y Restricciones

Rate Limits

Desarrollo/Sandbox: 100 peticiones por minuto
Producción: Según plan contratado
Header X-RateLimit-Remaining indica peticiones restantes

Tamaños Máximos

Tamaño máximo de request: 1 MB
Timeout de petición: 30 segundos
Límite de caracteres por campo: según especificación de cada servicio

12. Ambientes

Sandbox (Desarrollo)

POST https://sandbox.api.jaak.ai/api/v2/blacklist/investigate

Datos de prueba
Sin costo
Rate limits reducidos

Producción

POST https://services.api.jaak.ai/api/v2/blacklist/investigate

Datos reales
Según plan contratado
SLA garantizado

13. Soporte

Para obtener soporte técnico o reportar problemas con el API, contacta al equipo de JAAK:

Email: [email protected]
Documentación: https://docs.jaak.ai
Portal de API: https://services.api.jaak.ai
Status Page: https://status.jaak.ai

Información a incluir al reportar problemas

eventId de la petición
Timestamp de la petición
Código de estado HTTP recibido
Mensaje de error completo
Request enviado (sin incluir el token)

Changelog

Versión 2.0 (Actual)

Soporte para múltiples servicios en una sola petición
Mejoras en tiempo de respuesta
Nuevos campos en respuesta de CURP
Soporte para códigos de nacionalidad ISO 3166-1

Versión 1.0

Release inicial
Soporte para CURP, INE, SAT69B e INTERPOL

1. Introducción

1.1 Endpoints

1.2 Autenticación

1.3 Servicios Disponibles

2. Servicio CURP

2.1 Request

Estructura del Request

Parámetros

2.2 Response

Campos de la Respuesta

3. Servicio INE

3.1 Request

Estructura del Request

Parámetros

3.2 Response

4. Servicio OFAC

4.1 Request

Estructura del Request

Parámetros

4.2 Response

Campos de la Respuesta (cuando hay coincidencias)

5. Servicio SAT69B

5.1 Request

Estructura del Request

Parámetros

5.2 Response

6. Servicio INTERPOL

6.1 Request

Estructura del Request

Parámetros

6.2 Response

7. Códigos de Estado HTTP

8. Ejemplos de Uso

Ejemplo 1: Validar CURP

Ejemplo 2: Verificar INE

Ejemplo 3: Consultar en OFAC

Ejemplo 4: Consultar RFC en SAT69B

Ejemplo 5: Buscar en INTERPOL

9. Mejores Prácticas

9.1 Gestión de EventId

9.2 Manejo de Errores

9.3 Seguridad

9.4 Performance

10. Interpretación de Resultados

Campo foundInService

Campo mustBeFound

11. Límites y Restricciones

Rate Limits

Tamaños Máximos

12. Ambientes

Sandbox (Desarrollo)

Producción

13. Soporte

Información a incluir al reportar problemas

Changelog

Versión 2.0 (Actual)

Versión 1.0

Campo `foundInService`

Campo `mustBeFound`