Onboarding de sub-comercios

Antes de ligar un sub-comercio a Winal Connect, necesita una solicitud de alta aprobada: nombre legal, RFC, domicilio, representante legal, CLABE de liquidación y cuatro documentos. Tu plataforma administra estas solicitudes con su propia API key (análogo a POST /v1/accounts de Stripe Connect); la resolución (aprobar, rechazar, pedir más información) la hace Winal — tu plataforma no puede autoaprobar su propio KYB.

1. Alta mínima

Solo legal_name, person_type (fisica o moral) y contact_email son obligatorios para crear la solicitud.

curl -s https://api.winal.com.mx/v1/onboarding/applications \
  -H "Authorization: Bearer $SK" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Tienda Docs SA de CV",
    "person_type": "moral",
    "contact_email": "docs@example.mx"
  }'

{
  "id": "75deacfb-ff0d-476e-8292-f9471941694a",
  "object": "onboarding_application",
  "status": "draft",
  "legal_name": "Tienda Docs SA de CV",
  "person_type": "moral",
  "contact_email": "docs@example.mx",
  "created_at": "2026-07-08T06:48:56.880311+00:00",
  "updated_at": "2026-07-08T06:48:56.880311+00:00",
  "documents": []
}

No exige Idempotency-Key (no mueve dinero). person_type: "fisica" también es válido para un sub-comercio persona física.

2. Completa datos y documentos

PUT /v1/onboarding/applications/{id} acepta un patch parcial (los campos que omitas no se tocan) mientras la solicitud siga editable (draft o needs_info). Solo submit exige que todo esté completo.

Cada documento en documents[]:

curl -s -X PUT https://api.winal.com.mx/v1/onboarding/applications/75deacfb-... \
  -H "Authorization: Bearer $SK" \
  -H "Content-Type: application/json" \
  -d '{
    "rfc": "TDS900101AB1",
    "regimen_fiscal": "601",
    "domicilio_calle": "Av. Reforma", "domicilio_numero": "123",
    "domicilio_colonia": "Juárez", "domicilio_cp": "06600",
    "domicilio_ciudad": "Ciudad de México", "domicilio_estado": "CDMX",
    "clabe_liquidacion": "646180157000000004",
    "legal_representative_name": "Juan Pérez López",
    "contact_phone": "5512345678",
    "giro": "Comercio al por menor",
    "documents": [
      { "document_type": "ine", "reference": "INE-DOC-001", "reference_hash": "a1b2c3…" },
      { "document_type": "comprobante_domicilio", "reference": "CFE-REF-002", "reference_hash": "b2c3d4…" },
      { "document_type": "constancia_fiscal", "reference": "SAT-CSF-003", "reference_hash": "c3d4e5…" },
      { "document_type": "caratula_estado_cuenta", "reference": "EDOCTA-004", "reference_hash": "d4e5f6…" }
    ]
  }'

{
  "id": "75deacfb-ff0d-476e-8292-f9471941694a",
  "object": "onboarding_application",
  "status": "draft",
  "legal_name": "Tienda Docs SA de CV",
  "rfc": "TDS900101AB1",
  "clabe_masked": "**** **** **** 0004",
  "legal_representative_name": "Juan Pérez López",
  "documents": [ { "document_type": "ine", "reference": "INE-DOC-001", "reference_hash": "a1b2c3…", "created_at": "..." }, "... (4 en total)" ]
}

3. Envía a revisión

POST /v1/onboarding/applications/{id}/submit hace, en la MISMA llamada: valida completitud (los campos de arriba + los 4 documentos), valida el formato de RFC y CLABE, y corre el check de listas (PEP/OFAC/SAT 69-B). En fase 0 el check de listas está simulado — aprueba cualquier RFC salvo el centinela de pruebas — así que una solicitud completa y bien formada queda approved al instante:

curl -s -X POST https://api.winal.com.mx/v1/onboarding/applications/75deacfb-.../submit \
  -H "Authorization: Bearer $SK"

{
  "id": "75deacfb-ff0d-476e-8292-f9471941694a",
  "object": "onboarding_application",
  "status": "approved",
  "status_reason": "Verificación automática aprobada: RFC y CLABE con formato válido, sin coincidencias en listas.",
  "submitted_at": "2026-07-08T06:49:17.364553+00:00",
  "resolved_at": "2026-07-08T06:49:17.364553+00:00",
  "resolved_by": "system:auto_verification",
  "...": "resto de los campos igual que arriba"
}

Ya approved, la solicitud está lista para ligarse a una cuenta Connect.

Los tres desenlaces de submit

needs_info vuelve la solicitud editable: corrige con PUT y manda submit otra vez. Si el proceso de verificación truena entre pasos, la solicitud queda resoluble manualmente por un operador (nunca en limbo).

Verificación KYB: qué es Sim y qué está gated

Hoy el check de listas corre contra un verificador simulado (aprueba todo, sin llamadas de red) — pensado para que puedas probar el flujo completo sin depender de un proveedor real. Un KYB de producción de verdad necesita:

• Screening real contra listas PEP/OFAC/ONU y la Lista de Personas Bloqueadas de la UIF.
• Consulta contra el padrón real del SAT (el 69-B de contribuyentes con operaciones simuladas) y buró de crédito.
• Almacenamiento con retención legal de los documentos (INE, comprobante de domicilio, constancia fiscal, carátula de estado de cuenta).

El puerto IIdentityVerifier ya separa esto del resto del flujo: cambiar el verificador simulado por uno real (probablemente asíncrono — webhook o polling contra el proveedor de listas) no toca el resto del ciclo de vida de la solicitud. Es trabajo pendiente del dueño (certificación con un proveedor de KYB), no una limitación del código.

Resolución manual (portal)

Un operador de Winal puede aprobar, rechazar o pedir más información manualmente desde el portal → Onboarding — por ejemplo, si el proceso automático se detuvo a medio camino, o para revisar un caso needs_info a mano. Esa resolución vive bajo /admin (no es un endpoint público de /v1): tu plataforma, con su propia API key, no puede autoaprobarse su propio KYB — la misma razón por la que en Stripe Connect la plataforma tampoco aprueba sus propias cuentas Custom.

Estados de una solicitud

Endpoints

La resolución manual (/admin/tenants/{tenantId}/onboarding/applications/{id}/approve y equivalentes de reject/request-info) es una operación de portal para operadores de Winal, no un endpoint que documentemos como parte de tu integración pública.

Errores de onboarding_application