Entrega A+B: firma de contratos y remediación documental
Esta sección define el contrato de implementación para el portal y la API. Los ejemplos usan las rutas públicas de plataforma y los campos de respuesta normalizados por los handlers.Remediación inline: verificar el correo, agregar un número y desbloquearlo
Cuando se enlaza un teléfono nuevo sin verificarlo, las acciones OTP por teléfono quedan en cooldown de cuatro horas. El portal debe mostrar el CTA de compliance y permitir un factor independiente: desafío por correo verificado o TOTP. Un código enviado al número nuevo nunca desbloquea esta protección.{"status":"unlocked","channel":"email"}; sin
cooldown es {"status":"not_locked"}. Un código ausente o usado responde
401 invalid_otp; un factor telefónico responde 403 independent_factor_required. Sin factor independiente, el titular espera
las cuatro horas. El resultado queda visible en GET /v1/me.
Un administrador puede limpiar el marcador sin cambiar el teléfono ni
phone_verified:
{"status":"cleared","account_id":"<ACCOUNT_ID>"} y la
acción queda auditada.
Firma tipeada en el portal y el wizard
El wizard ofrece Dibujar firma y Escribir nombre completo. Ambos producensignature_png. Para firma tipeada, envía el PNG renderizado, el
modo y el nombre exacto:
signature_mode puede ser drawn (por defecto) o typed. En modo tipeado,
typed_name es obligatorio y debe coincidir exactamente con signer_name;
si no, responde 422 typed_name_mismatch. Un modo desconocido responde
422 invalid_signature_mode. El OTP sigue siendo un header.
Wizard KYB: Reino Unido y país genérico
Para una empresa británica usacountry: "uk"; el wizard solicita número de
empresa, datos registrados, directores, beneficiarios finales y roles de
control/firma según el perfil UK. Para otro país usa country: "generic" y
generic_country ISO alpha-2:
Correos de verificación e idioma
Los correos incluyen un CTA Continuar compliance cuando existe un link o una submission accionable. El CTA usa el mismo token del wizard. El idioma sigue el locale del perfil (en, es o zh) y cae a inglés. El correo no es
la fuente de verdad del estado.
Subida nativa de documentos: multipart y raw
La respuesta de presign indica el transporte:
shape: "multipart", haz POST con la parte file, category y key:
shape: "raw", haz PUT de los bytes con el mismo Content-Type. Ambos
flujos terminan con POST .../{submissionID}/documents/confirm y luego
GET .../documents. El proxy acepta hasta 24 MiB; el límite del core es 15
MiB por archivo.
Si compliance pidió el archivo, aparece uploaded_after_request: true.
Muéstralo como badge Subido después de la solicitud, junto a outcome y
effective_outcome. Este último usa la resolución manual cuando existe y, si
no, el resultado OCR.
Estados y errores
Consulta el catálogo de errores para el contrato completo.
Preguntas frecuentes
¿El número nuevo puede desbloquear su cooldown?
¿El número nuevo puede desbloquear su cooldown?
No. Usa el correo verificado o la app autenticadora, o espera cuatro horas.
¿Qué shape debe usar el portal?
¿Qué shape debe usar el portal?
Usa el
shape devuelto por presign; nunca lo infieras desde una URL de storage.