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).

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

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