Tutoriales de Integración API

Un recorrido por niveles, verificado contra la documentación oficial: día 0 con solo el RFC, la CIEC cuando necesitas profundidad y monitoreo continuo un mes después.

Recursos para desarrolladores

Seis recursos, seis propósitos. Elija el que coincida con dónde está en su integración.

SAT Integration Hub

Empieza aquí: qué expone la API del SAT, cómo CRiskCo abstrae SOAP/CIEC, y FAQ técnico.

Ir a la página

Guía de Integración API

Walkthrough end-to-end: autenticación, modelos de integración (Approve / White-label / Webhook) y catálogo completo de endpoints.

Ir a la página

Ejemplos de Código

Snippets copy-paste en Python, Node.js y cURL para cada flujo común.

Ir a la página

Estás aquí

Tutoriales

Guías paso a paso para principiantes: primer request, autenticación y monitoreo.

Explorador de API

Cada endpoint y cada campo en una sola vista buscable. Pensado para equipos evaluando o migrando su integración.

Ir a la página

API Docs

Referencia técnica completa: todos los endpoints, parámetros, esquemas de respuesta y códigos de error.

Abrir docs

Documentación completa Registrarse para apiId/apiKey

El recorrido de integración

NIVEL 1 — VERIFY

Día 0

Onboard solo con el RFC: certificados e.firma/CSD y accionistas. Sin credenciales del cliente.

NIVEL 2

Cuando necesitas profundidad

Agrega la CIEC del mismo solicitante y obtén financieros CFSS, AR/AP y FinScore.

NIVEL 3

Un mes después

Registra un webhook y recibe datos frescos y alertas en lugar de volver a consultar.

Guías Paso a Paso

Preparación — tus credenciales

Antes de cualquier nivel: obtén tus llaves y comprueba que la conexión funciona. No necesitas ningún dato del cliente todavía.

1. Obtén tus credenciales (apiId + apiKey)

Regístrate en CRiskCo para recibir tu apiId y apiKey por correo. Ambos viajan como headers en cada petición — no hay flujo OAuth ni tokens Bearer. Las llaves de prueba devuelven datos sandbox sin costo.

# Required headers on every API call
apiId: YOUR_API_ID
apiKey: YOUR_API_KEY
Content-Type: application/json

Registrarse para apiId/apiKey

2. Tu primera llamada autenticada

Valida tus credenciales con GET /SatHealthCheck: es una utilidad de plataforma disponible en todos los niveles, sin solicitante, sin onboarding y sin CIEC. La base URL para todas las llamadas es https://service.criskco.com/apiservice.svc.

curl -G "https://service.criskco.com/apiservice.svc/SatHealthCheck" \
  -H "apiId: YOUR_API_ID" \
  -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "serviceName=Declarations" \
  --data-urlencode "systemType=SAT" \
  --data-urlencode "unitType=Hours" \
  --data-urlencode "unitAmount=24"

NIVEL 1 — VERIFY

Día 0 — empieza solo con el RFC

El primer contacto con un cliente no requiere ninguna credencial suya. Con el RFC ya puedes confirmar identidad, vigencia de certificados y estructura societaria — cero fricción para el solicitante.

3. Verifica certificados e.firma / CSD con el RFC

POST /VerifyEFirmaCertificates responde de forma sincrónica con los certificados del RFC: tipo (FIEL o SELLO), número de serie, estatus y vigencia. Usa TransactionId como llave de idempotencia — si repites el mismo valor, se devuelve el resultado previo sin volver a consultar al SAT.

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

{
  "TransactionId": "case-00482",
  "Rfc": "XXXX000000X00"
}

# Response (abbreviated)
{
  "success": true,
  "status": "COMPLETED",
  "result": {
    "rfc": "XXXX000000X00",
    "holderName": "Holder Name",
    "certificates": [
      {
        "certificateType": "SELLO",
        "serialNumber": "00001000000709064325",
        "status": "ACTIVE",
        "validFrom": "2024-07-31",
        "validTo": "2028-07-31",
        "revocationDate": null
      }
    ]
  }
}

4. Escala a asíncrono y por lotes

Para volumen, usa las variantes asíncronas: VerifyEFirmaCertificatesWebhook para un registro y VerifyEFirmaCertificatesBatchWebhook para 1–100 registros. Ambas devuelven 202 Accepted y entregan el resultado a tu suscripción de webhook. En el lote, los errores por fila no invalidan el resto (ROW_INVALID_RFC_FORMAT, ROW_DUPLICATE_RECORD, etc.).

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

{
  "WebhookSubscriptionId": 1,
  "Items": [
    { "TransactionId": "row-1", "Rfc": "XXXX000000X00" },
    { "TransactionId": "row-2", "Rfc": "YYYY000000Y00" }
  ]
}

# 202 Accepted
{ "batchId": "crk_batch_20260820_e6c5b39a", "itemCount": 2, "status": "processing" }

5. Accionistas y propietario real (SIGER/RUG)

GET /siger-webhook solicita los accionistas en el registro público; la respuesta HTTP solo confirma que el job fue aceptado y el payload — con el uuid — llega a tu callback. Con ese uuid, GET /siger-pdf-webhook entrega los documentos del registro. Con querySocios=true también se consulta cada accionista para ver en qué otras empresas participa.

# 1) Request shareholders (async)
curl -G "https://service.criskco.com/apiservice.svc/siger-webhook" \
  -H "apiId: YOUR_API_ID" -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "taxId=GAPXXXXXXXXX" \
  --data-urlencode "subscriptionId=0" \
  --data-urlencode "querySocios=true"

# 2) Then request the registry documents with the uuid from the callback
curl -G "https://service.criskco.com/apiservice.svc/siger-pdf-webhook" \
  -H "apiId: YOUR_API_ID" -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "taxId=GAPXXXXXXXXX" \
  --data-urlencode "subscriptionId=0" \
  --data-urlencode "uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# At this point you have identity, certificate validity and ownership —
# with no credential requested from the client.

NIVEL 2 — INTELIGENCIA FINANCIERA COMPLETA

Cuando necesitas profundidad — agrega la CIEC

Si el caso avanza y necesitas estados financieros, facturación y capacidad de pago, pides la CIEC al contribuyente. Es un upgrade sobre el mismo solicitante, no un nuevo inicio.

6. Onboarding SAT con la CIEC

El onboarding al SAT se hace con la contraseña CIEC del contribuyente (CRiskCo no requiere e.firma). Envía RFC y CIEC a OnboardingSatIntegration y reutiliza tu RefApplicantId del nivel 1 para mantener el mismo expediente.

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

{
  "IsAgreeTerms": true,
  "DateAgreeTerms": "2026-04-16",
  "VersionAgreeTerms": "1",
  "Email": "contact@empresa.com",
  "User": "GAPXXXXXXXXX",
  "Password": "CIEC_PASSWORD",
  "RefApplicantId": "loan-app-00482"
}

7. Polling del estado del onboarding

Después del onboarding, consulta GET /get-applicants cada 5–10 segundos hasta que onboardingStatus sea 'Available'. Valores posibles: NotConnected, Processing, Available.

curl -G "https://service.criskco.com/apiservice.svc/get-applicants" \
  -H "apiId: YOUR_API_ID" \
  -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "taxId=GAPXXXXXXXXX" \
  --data-urlencode "onboardingStatus=true"

# Response includes onboardingStatus: NotConnected | Processing | Available

8. Lee los financieros normalizados (CFSS)

Con el solicitante en 'Available', GET /financialStatement devuelve el CRiskCo Financial Statement Standard: balance, estado de resultados y KPIs en una taxonomía estable de 126 campos por periodo.

curl -G "https://service.criskco.com/apiservice.svc/financialStatement" \
  -H "apiId: YOUR_API_ID" \
  -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "taxId=GAPXXXXXXXXX" \
  --data-urlencode "financialYear=2022"   # optional — omit for all available years

# Response: { "FinancialStatements": [ { "ASSET": "3916350.00", "REVENUE": "13478313.00", ... } ] }

Ver el estándar CFSS completo

NIVEL 3 — MONITOREO Y ALERTAS

Un mes después — conviértelo en una cuenta monitoreada

Una decisión de crédito envejece. Pasado el primer mes, en lugar de volver a consultar manualmente, deja que los datos frescos lleguen a tu sistema por webhook.

9. Registra tu callback

Registra una CallbackUrl con POST /Subscriptions. CRiskCo enviará primero un GET de validación a tu URL — tu servidor debe responder HTTP 200 en menos de 2 segundos. Después recibirás eventos con FileType: 'JSON' (payload inline en APIResponse) o 'JSON_LINK' (URL de descarga en DownloadUrlList).

# 1) Register the webhook
POST https://service.criskco.com/apiservice.svc/Subscriptions
Headers: apiId, apiKey, Content-Type: application/json
{ "CallbackUrl": "https://yourdomain.com/webhooks/criskco" }

# 2) CRiskCo then sends a GET to that URL for validation —
#    respond HTTP 200 within 2 seconds.

# 3) Events arrive as POSTs with FileType="JSON" (inline payload)
#    or FileType="JSON_LINK" (signed download URLs).
#    Review your subscriptions with GET /Subscriptions.

10. Recibe datos frescos en lugar de consultarlos

Cada endpoint tiene su variante *-webhook. Con la suscripción activa, dispara la actualización periódica de las cuentas que ya onboardeaste — cartera, facturación AR/AP y pagos — y procesa los eventos cuando lleguen.

# Portfolio refresh
GET /Get-Applicants-Webhook?taxId=GAPXXXXXXXXX&subscriptionId=1&onboardingStatus=true

# Receivables activity for the last period
GET /ar-transactions/invoices-webhook?taxId=GAPXXXXXXXXX&subscriptionId=1 \
    &fromDate=2026-07-01&toDate=2026-07-31

# Payables activity
GET /ap-transactions/payments-webhook?taxId=GAPXXXXXXXXX&subscriptionId=1 \
    &fromDate=2026-07-01&toDate=2026-07-31

11. Del monitoreo a tus propios modelos

Con historia acumulada en tu cartera, el siguiente paso es construir scores propios sobre los mismos campos con CRiskCo Labs, y conectarlos a tus agentes vía MCP.

# Same fields, your model:
#   Tier 1  RFC only        -> identity, certificates, ownership
#   Tier 2  + CIEC          -> CFSS financials, AR/AP, FinScore
#   Tier 3  + subscription  -> continuous refresh and alerts
#   Tier 4  CRiskCo Labs    -> your own scorecards on the same taxonomy
#   Tier 5  MCP             -> the same data, agent-ready

Conocer CRiskCo Labs

¿Listo para integrar?

Empieza hoy solo con el RFC, agrega la CIEC cuando necesites profundidad y activa monitoreo cuando la cartera crezca.

Registrarse ahora Ver documentación

Explorar Más

Verify — solo RFC Integración SAT API Guía de API Ejemplos de Código Riesgo Crediticio