API 1.19.1 - Cambio de correo con contraseña y referencia verificada

Aquí resumimos lo que cambió para los integradores desde la entrada 1.18.1. Incluye la versión 1.19.0, con cambios de comportamiento en la cuenta, la empresa, los mensajes de error y la emisión con Viafirma, y la 1.19.1, que revisa la referencia completa de la API sin cambiar su funcionamiento. Las rutas siguen bajo el prefijo /api/v1.

Cambios que requieren acción

• Cambiar tu propio correo con PUT /profile/{id} exige tu contraseña actual: envíala en records.current_password. Si falta o no es correcta, la API responde 422 con el detalle en errors.current_password y no guarda nada.
• El correo nuevo debe verificarse antes del próximo inicio de sesión: tu token actual sigue funcionando, pero POST /auth/login responde 400 hasta que se abra el enlace de verificación que se envía al correo nuevo. La respuesta del cambio lo indica con email_verification_required = true.
• El correo de la cuenta y el de la empresa ya no se pueden vaciar: en PUT /profile/{id} y PUT /company/{id}, un records.email vacío, solo con espacios o null responde 422 (El correo electrónico es obligatorio: no se puede dejar vacío.). Antes se guardaba vacío. Si no quieres cambiar el correo, omite el campo email.

Cambios de comportamiento

Perfil: cambio de correo

Cuando PUT /profile/{id} cambia el correo de la cuenta se aplica lo siguiente. Un cambio solo de mayúsculas o minúsculas no cuenta como cambio de correo.

• Contraseña actual: es obligatoria solo cuando cambias tu propio correo. Se ignora si el correo no cambia y nunca se guarda.
• Correo ya registrado: si el correo nuevo ya lo usa otra cuenta, la API responde 422 (Ya existe una cuenta con ese correo electrónico.) con el detalle en errors.email. Antes respondía 500.
• Límites: puedes guardar hasta 3 cambios de correo por hora; el cuarto responde 429 (Demasiados cambios de correo. Intenta de nuevo más tarde.). Los intentos rechazados no cuentan. Tras 5 contraseñas incorrectas en 15 minutos, la API responde 429 (Demasiados intentos con la contraseña actual. Intenta de nuevo más tarde.) aunque la siguiente sea correcta. Ambos 429 traen la cabecera Retry-After con los segundos que debes esperar.
• Verificación del correo nuevo: el correo nuevo queda sin verificar. Le enviamos un enlace de verificación y avisamos del cambio al correo anterior. Si el enlace no llega, pide otro con POST /email/verification-notification. Los enlaces de verificación enviados a un correo anterior ya no sirven.
• Respuesta: la respuesta 200 de PUT /profile/{id} incluye el campo email_verification_required, que es true solo si el correo cambió.
• Cuenta inactiva: si un administrador desactivó tu cuenta, PUT /profile/{id} responde 403 (La cuenta está inactiva.). Verificar el correo ya no reactiva una cuenta desactivada.

Detalle en Perfil y Autenticación.

Empresa y registro

• PUT /company/{id}: el correo de la empresa no se puede vaciar (ver el aviso de arriba). El resto de reglas del correo no cambia: si es distinto del guardado, debe poder recibir mensajes. Detalle en Empresa.
• POST /register: si envías country_id, identity_document_id o type_organization_id con un ID que no existe en el catálogo, la API responde 422 (El país no existe, El tipo de documento no existe o El tipo de organización no existe) y no crea nada. Antes respondía 500. Consulta los IDs válidos en Datos maestros.

Mensajes de error

• Cuando una operación falla por un problema al guardar o consultar los datos, message trae un texto genérico, por ejemplo Ya existe un registro con ese valor (dato duplicado)., Falta un dato obligatorio., No se puede completar: un dato relacionado no existe. o No se pudo completar la operación en la base de datos.. El código HTTP no cambia. Si tu integración analizaba el texto de estos errores, guíate por el código HTTP.

Emisión con Viafirma

• POST /certificate-request/{id}/issue: si falla la comunicación con Viafirma (error de red, tiempo de espera o servicio no disponible), la API responde 502 (Error de comunicación con Viafirma RA. Intente nuevamente.) con provider = viafirma. Antes respondía 422. No se registra ningún trámite, así que puedes reintentar la emisión pasados unos segundos, sin superar el límite de 5 emisiones por minuto.
• Si Viafirma rechaza la petición, la respuesta sigue siendo 422, ahora con un mensaje fijo: El servicio de Viafirma rechazó la solicitud. Revisa los datos e intenta de nuevo., seguido de Código: ... cuando Viafirma devuelve un código de error.

Detalle en Emisión de certificados y Viafirma.

A tener en cuenta

Comportamientos de la API que conviene tener presentes al integrar:

Vigencia de los Personal Access Tokens

Todo Personal Access Token es válido 90 días desde su creación. expires_in_days (de 1 a 365 días) define la fecha expires_at que se muestra en la respuesta y en GET /tokens, y con ella si el token aparece en ese listado; la autenticación se rige por los 90 días. Planifica la rotación (POST /tokens/{id}/renew) antes de que se cumplan y, si necesitas invalidar un token antes, revócalo con DELETE /tokens/{id}. Detalle en Tokens.

Configuración general de la empresa

La configuración general se consulta con GET /company/settings (Empresa). PUT /company/settings no admite actualizaciones a través de la API: responde 500.

Documentación

• La referencia de la API se revisó operación por operación contra el funcionamiento real de la API y se corrigieron parámetros, cuerpos, códigos de estado, formatos de error y límites de peticiones. La API no cambia en la 1.19.1: solo su documentación.
• La versión de la referencia sigue la del backend y ahora es la 1.19.1.
• Algunas correcciones que pueden afectar tu integración:
  • POST /tokens admite 10 intentos de creación por usuario en 24 horas, contadas desde el primer intento. Cuentan también los intentos rechazados por validación.
  • En GET /quota/status, postpaid muestra solo el cupo pospago activo más reciente. Si tu empresa tiene varios activos a la vez, el saldo pospago total puede ser mayor que postpaid.remaining.
  • En la emisión por correo, el servidor no valida el tipo de archivo de los adjuntos. Se recomiendan PDF, JPG o PNG.
  • En el estado de la emisión, un certificado revocado se identifica por internal_state = REVOKED y revoked_at: su last_error_message puede venir vacío o con un error anterior.
  • Con Viafirma, GET /certificate-request/{id}/issuance devuelve siempre las 19 claves de dataRecords.data (null cuando no hay valor).
  • GET /certificate-request/{id}/kyc-link responde 500 mientras el trámite de Viafirma aún no existe (justo después de crear la solicitud). Un 422 no siempre se resuelve reintentando: el message indica el motivo.
  • En la emisión por correo, PUT /certificate-request/{id}/status con SENT solo cambia el estado: para enviar los soportes a emisión usa POST /certificate-request/{id}/issue.
  • En GET /webhooks/{id}/deliveries, status también puede valer pending (envío en curso o que no llegó a completarse).
• Las guías y la colección de Postman se actualizaron con estos cambios. En la colección, GET /pricing tiene ahora dos peticiones: Consultar tarifas (sin parámetros, devuelve los rangos de tarifas) y Calcular precio (con quantity y vigencia).

¿Vas a actualizar una integración existente? Revisa la guía paso a paso y la solución de problemas.