Guía de Integración API

Cómo funciona la API

La API de CRiskCo es centrada en el aplicante. Antes de consultar datos financieros o de cumplimiento, el negocio (el "Aplicante") debe ser onboardeado — ya sea a través de tu propia UI vía API, la página de landing white-label de CRiskCo, o mediante webhooks basados en eventos.

Tres conceptos clave:

• Credit Provider — tu plataforma, llamando a la API usando apiId y apiKey.
• Applicant — el negocio aplicando a crédito. Autorizan acceso de CRiskCo a sus datos del SAT.
• Customer — un negocio que es cliente del Aplicante (usado para análisis de contraparte).

Los tres niveles de la API

Los endpoints están organizados en los mismos niveles que la plataforma. Puedes empezar en el Nivel 1 con solo el RFC y avanzar cuando necesites profundidad o monitoreo.

• Nivel 1 — Verify — validaciones a partir del RFC, sin CIEC: ValidateRFC (individual y masivo), certificados de e.firma, accionistas (SIGER/RUG) y SatHealthCheck (disponible en cualquier nivel).
• Nivel 2 — Inteligencia Financiera — onboarding con CIEC y profundidad total: situación fiscal, regímenes y Constancia de Situación Fiscal (requieren un onboarding SAT/CIEC completado), CFDI de cobros y pagos, estados financieros (CFSS), nómina y FinScore.
• Nivel 3 — Monitoreo y Alertas — suscripciones de callback y payloads asíncronos cuando los datos cambian.

Consulta cada endpoint por nivel en el Explorador de API.

Nivel 1 — Endpoints Verify (solo RFC)

Certificados de e.firma

Verifica los certificados de e.firma de un RFC de forma síncrona, asíncrona (webhook) o en lote de hasta 100 elementos. Deja CertificateSerialNumber vacío para consultar todos los certificados del RFC.

POST /apiservice.svc/VerifyEFirmaCertificates
{ "TransactionId": "", "Rfc": "XXXX000000X00", "CertificateSerialNumber": "" }

POST /apiservice.svc/VerifyEFirmaCertificatesWebhook
{ "TransactionId": "", "Rfc": "XXXX000000X00", "CertificateSerialNumber": "", "WebhookSubscriptionId": 1 }

POST /apiservice.svc/VerifyEFirmaCertificatesBatchWebhook
{
  "WebhookSubscriptionId": 1,
  "Items": [
    { "TransactionId": "", "Rfc": "XXXX000000X00", "CertificateSerialNumber": "" },
    { "TransactionId": "", "Rfc": "XXXX11111X11", "CertificateSerialNumber": "" }
  ]
}

Accionistas (SIGER/RUG)

Flujo de dos pasos: solicita los accionistas y luego los documentos del registro usando el uuid devuelto en el callback.

GET /apiservice.svc/siger-webhook?taxId=XXXX000000X00&subscriptionId=1&querySocios=true

GET /apiservice.svc/siger-pdf-webhook?taxId=XXXX000000X00&subscriptionId=1&uuid=YOUR_UUID

Autenticación

Todas las solicitudes requieren estos headers en cada llamada:

apiId: YOUR_API_ID
apiKey: YOUR_API_KEY
Content-Type: application/json

apiId y apiKey son emitidos por CRiskCo al registrarte. Las llaves de prueba retornan datos sandbox y no generan costo. No hay cambio de entorno — usa la llave correcta para el modo correcto.

Obtén tus credenciales de sandbox: Regístrate en api-docs.criskco.com → recibe apiId + apiKey por email.

Modelos de Integración

CRiskCo soporta tres modelos de integración. Elige según cuánto control necesites sobre la experiencia de onboarding.

Modelo A — Approve API (Control Total)

Recoges las credenciales RFC y CIEC del aplicante en tu propia UI y las envías a CRiskCo vía API.

Flujo:

1. Tu app recopila RFC + CIEC del aplicante.
2. POST /OnboardingSatIntegration para registrar al aplicante y conectar al SAT.
3. GET /get-applicants para verificar onboardingStatus: "Available".
4. POST /applicantinfo u otros endpoints para obtener datos.

Paso 1 — Onboarding vía API

POST https://service.criskco.com/apiservice.svc/OnboardingSatIntegration
Headers: apiId, apiKey, Content-Type: application/json

{
  "IsAgreeTerms": true,
  "DateAgreeTerms": "2026-03-24",
  "VersionAgreeTerms": "1",
  "Email": "contact@empresa.com",
  "User": "GAPXXXXXXXXX",
  "Password": "CIEC_PASSWORD",
  "RefApplicantId": "your-internal-ref-123"
}

Modelo B — Fintech Solution (Página Hosted)

Rediriges al aplicante a la página de onboarding de CRiskCo. CRiskCo maneja la conexión y validación SAT. Obtienes datos vía API una vez que el estado es Available.

Opción 1 — Página de onboarding general (sin configuración white-label)

Dirige a tus aplicantes a la página estándar de onboarding de CRiskCo y pídeles que ingresen tu código de referencia registrado cuando se les solicite:

https://app.criskco.com/onboarding/#!/app/referrer-es

El aplicante ingresa tu código de referencia durante el flujo. CRiskCo asocia el onboarding completado con ese código, que puedes usar para consultar el estado.

Opción 2 — Página de onboarding white-label (requiere configuración con CRiskCo)

Si CRiskCo ha provisionado una instancia white-label para tu marca, tu URL dedicada será:

https://yourbrand.criskco.com/onboarding/#!/app/

Reemplaza yourbrand con el subdominio asignado por CRiskCo.

En ambos casos, una vez completado el onboarding, consulta el aplicante usando tu código de referencia:

GET /get-applicants?refApplicantId=YOUR_SUBSCRIPTION_ID

No requiere desarrollo frontend. CRiskCo gestiona la integración SAT y el manejo de credenciales.

Modelo C — Webhook (Basado en Eventos)

En lugar de hacer polling por estado, CRiskCo envía actualizaciones a tu servidor en el momento en que están listas. Este es el modelo recomendado para plataformas de underwriting automatizado.

POST https://service.criskco.com/apiservice.svc/Subscriptions
Headers: apiId, apiKey, Content-Type: application/json

{ "CallbackUrl": "https://yourdomain.com/webhooks/criskco" }

Validación: Después de recibir tu solicitud de suscripción, CRiskCo envía inmediatamente un GET a tu CallbackUrl. Tu servidor debe responder con HTTP 200 OK en 2 segundos.

Respuesta exitosa de registro:

{
  "success": true,
  "responseDetails": "Subscription 1 created successfully",
  "ApiSubscriptionData": [
	{
		"Active": true,
		"CallbackUrl": "https://yourdomain.com/path/webhook",
		"ReferrerId": "your_referrer_id",
		"SubscriptionId": 1
    }
  ]
}

Payload del Webhook — JSON Inline

Cuando fileResponse es false, CRiskCo envía el payload directamente en el cuerpo del webhook:

{
  "SubscriptionId": 1,
  "ReferrerId": "criskco_partner",
  "WebhookUrl": "https://yourdomain.com/path/webhook",
  "ApiServiceName": "GetApplicants",
  "FileType": "JSON",
  "DownloadUrlList": null,
  "applicantId": "123456",
  "refApplicantId": "abc-def",
  "APIResponse": "{ "applicantId": "123456", "onboardingStatus": "Available", ... }"
}

Payload del Webhook — Link Descargable

Cuando fileResponse es true, CRiskCo almacena el JSON y envía una URL de descarga en su lugar:

{
  "SubscriptionId": 1,
  "ReferrerId": "criskco_partner",
  "WebhookUrl": "https://yourdomain.com/path/webhook",
  "ApiServiceName": "GetApplicants",
  "FileType": "JSON_LINK",
  "DownloadUrlList": [
    "https://criskco-files.s3.amazonaws.com/..."
  ],
  "applicantId": "123456",
  "refApplicantId": "abc-def",
  "APIResponse": null
}

La forma del payload es idéntica en ambos modos. FileType te dice si parsear APIResponse directamente o descargar de DownloadUrlList.

Gestionar Suscripciones

Listar todas las suscripciones activas:

GET https://service.criskco.com/apiservice.svc/Subscriptions
Headers: apiId, apiKey

Eliminar una suscripción:

POST https://service.criskco.com/apiservice.svc/Subscriptions?id=YOUR_SUBSCRIPTION_ID
Headers: apiId, apiKey

Obtener Aplicantes y Verificar Estado

Sin importar qué modelo de integración uses, obtén el applicantId aquí. Es requerido para todos los endpoints de datos financieros.

GET https://service.criskco.com/apiservice.svc/get-applicants
Headers: apiId, apiKey

Respuesta de Ejemplo

{
  "responseDetails": "Data retrieved successfully",
  "success": true,
  "ApiApplicantData": {
    "applicantId": "1000143693",
    "taxId": "GAPXXXXXXXXX",
    "dateConnected": "2026-03-24T09:15:00Z",
    "onboardingStatus": "Available",
    "financials": { ... },
    "blackLists": ["SAT", "OFAC"]
  }
}

Estados de Onboarding

blackLists: Retornado cuando fullResponse=true. Lista las fuentes de blacklist donde el aplicante tiene una bandera (e.g. "SAT" = EFOS/EDOS, "OFAC" = sanciones de EE.UU.).

Validación de RFC

RFC Individual

GET /ValidateRFC?rfc=GAPXXXXXXXXX&name=GAP&postal=12345

Params: rfc (required) · name (optional) · postal (optional)

Response:
{
  "Success": true,
  "ValidParameters": [
    { "Property": "ValidRFC", "Valid": true },
    { "Property": "ValidName", "Valid": true },
    { "Property": "ValidPostal", "Valid": true }
  ],
  "message": "RFC válido, y susceptible de recibir facturas"
}

Validación Masiva (hasta 5,000)

Envía un archivo de texto con un RFC por línea, o RFC|Nombre|CP separados por pipe.

POST /ValidateRFCBulk
Body: plain-text file

RFC only:
ABCYYYYYYYYYY
DEFZZZZZZZZZZ

RFC + Name + Postal (pipe-separated):
ABCYYYYYYYYYY|EMPRESA ABC|98765
DEFZZZZZZZZZZ|EMPRESA DEF|12345

Endpoints de Cumplimiento SAT

Estos endpoints consultan por taxId (RFC) — no se requiere applicantId.

Estado Fiscal (Opinión de Cumplimiento)

GET /GetCompanyTaxStatus?taxId=GAPXXXXXXXXX

Returns POSITIVO or NEGATIVO plus outstanding obligations (populated only when NEGATIVO).

Regímenes Fiscales

GET /GetCompanyTaxRegimes?taxId=GAPXXXXXXXXX

Returns: RFC, Regime, ReportUpdateDate, PayingTax

Constancia De Fiscal

GET /GetCompanyFiscalDetails?taxId=GAPXXXXXXXXX

Returns: RFC, Name, FirstSurname, SecondSurname, CompanyName, CapitalRegime,
CommercialName, OperationStartDate, FiscalStatus, LastStatusChangeDate,
FiscalRegisteredAddress

FinScore Histórico

GET /GetHistoricalFinscore?taxId=GAPXXXXXXXXX

{
  "HistoricalFinscores": [
    { "Year": 2025, "Month": 10, "FinScore": 68.2 },
    { "Year": 2025, "Month": 11, "FinScore": 70.4 },
    { "Year": 2026, "Month": 1, "FinScore": 74.0 }
  ]
}

Datos Financieros del Aplicante

Todos los endpoints financieros son POST con { "applicantId": "..." }. Parámetros opcionales fromDate/toDate filtran por fecha (ISO 8601).

Información del Aplicante (Resumen)

POST /applicantinfo

{ "applicantId": "1000143693" }

Returns verified business info, blacklist status, and summarized financials.

Clientes y Transacciones AR

Proveedores y Transacciones AP

Reportes Financieros

Reportes raw — como aparecen en el ERP del aplicante:

POST /financialreports/rowdata/balancesheet
POST /financialreports/rowdata/profitandloss
POST /financialreports/rowdata/bankstatement

{ "applicantId": "1000143693" }

Reportes estandarizados — normalizados por CRiskCo:

POST /financialreports/standard/balancesheet
POST /financialreports/standard/profitandloss

{ "applicantId": "1000143693", "financialYear": "Current" }

financialYear options:
  Current · FinancialYearEnd · PreviousFinancialYearEnd ·
  SecondPreviousFinancialYearEnd · ThirdPreviousFinancialYearEnd

Estado financiero consolidado directo del SAT (declaraciones anuales presentadas):

GET /financialStatement?taxId=GAPXXXXXXXXX

// Returns annual income, expenses, assets and liabilities as reported to SAT.
// Useful as a third-party-validated cross-check against ERP-sourced reports.

Todos los Financieros en Una Llamada

POST /grouping/applicant-financials

{ "applicantId": "1000143693", "csvInJson": false }

Returns raw data, standardized reports, documents, analytics, and summaries.
Recommended for initial data pulls.

Documentos

POST /Documents

{ "applicantId": "1000143693", "csvInJson": false }

Cada documento incluye un link de descarga HTTP directo.

Endpoints SAT Adicionales

Estructura de Propiedad

GET /GetCompanyStructure?taxId=GAPXXXXXXXXX

Returns: owner names, RFC, country, participation % (with/without vote),
tenure periods, loans, capital movements.

Detalles de Nómina

GET /GetPayrollDetails?taxId=GAPXXXXXXXXX

Detalles de Empleados

GET /GetEmployeesDetails?taxId=GAPXXXXXXXXX

Returns: name, RFC, CURP, position, start date, total work months,
payment frequency, days paid, gross salary.

Antecedentes Judiciales

GET /GetInformationReport?taxId=GAPXXXXXXXXX

Returns AntecedentesJudiciales grouped by state, with case numbers,
dates, and court references.

Salud del SAT

GET /SatHealthCheck?serviceName=Declarations&systemType=SAT&unitType=Hours&unitAmount=24

Returns avg/max response times, failure rates, and HTTP status codes per check.
Use before making SAT-dependent calls to diagnose upstream issues.

Gestión del Ciclo de Vida

Actualizar Estado del Aplicante

POST /applicant-status

{ "applicantId": "1000143693", "status": "Approved" }

Statuses: New | UnderEvaluation | Approved | Denied | CancelByApplicant | CompanyDefaulted | Completed

Los estados de desconexión detienen la sincronización de datos SAT. Volver a un estado conectado dispara un intento de reconexión.

Disparar Actualización de Monitoreo

POST /RequestMonitoring

{ "applicantId": "1000143693", "Source": "API" }

Forces a fresh SAT data pull for an applicant already in your system.

Mejores Prácticas

• Siempre usa HTTPS. Nunca expongas tu apiKey del lado del cliente.
• Valida las llamadas webhook entrantes para prevenir spoofing — verifica que las solicitudes provengan de las IPs de CRiskCo.
• Implementa lógica de reintento con backoff exponencial.
• Almacena applicantId localmente en tu LOS — lo usarás en cada llamada subsecuente.
• Usa fullResponse=true solo cuando sea necesario — agrega latencia.
• Verifica onboardingStatus Available antes de consultar endpoints financieros — consultar mientras está Processing retorna datos incompletos.
• Para pipelines automatizados, usa el modelo Webhook en lugar de polling.

Referencia Completa de Endpoints