API 1.18.1 - Cambios desde la documentación de julio de 2026

Desde esta entrada, la referencia de la API sigue la versión del backend. Aquí resumimos lo que cambió para los integradores desde la documentación publicada en julio de 2026. Las rutas siguen bajo el prefijo /api/v1.

Cambios que requieren acción

• POST /certificate-request se envía en JSON (application/json), ya no en multipart/form-data. Los adjuntos van en attachments[], con el contenido del archivo en base64 y, de forma opcional, name, type y size.
• Nuevos campos obligatorios al crear una solicitud: country_id, accept_terms (debe venir aceptado, por ejemplo true) y terms_version_id, que es el id que devuelve GET /terms/current y debe corresponder a la versión vigente de los Términos y Condiciones. Si falta alguno, o la versión ya no es la vigente, la API responde 400 con el detalle por campo en errors.
• legal_representative solo es obligatorio si no envías legal_rep_first_name y legal_rep_last_name. Si tu empresa emite con Viafirma, debes enviar los nombres y apellidos por separado y legal_rep_email.
• POST /certificate-request/{id}/files también recibe JSON con attachments[] en Base64, en lugar del campo file en multipart/form-data.
• La revocación usa el UUID público de la solicitud: POST /certificate-request/{uuid}/revoke reemplaza a POST /certificate-request/{id}/revoke. Con un ID numérico, o con un UUID que no pertenece a tu empresa, la API responde 404.
• Solo se entregan certificados vigentes: GET /certificate-request/{uuid}/issuance/download, su variante /download/base64 y la descarga de archivos de tipo CERTIFICATE responden 409, con el estado actual en status, si la solicitud no está en PROCESSED (revocada, vencida, cancelada, rechazada o aún en trámite).

Nuevos endpoints

Autenticación y datos maestros

• GET /auth/user: devuelve el usuario dueño del token. Sirve para comprobar que un token sigue vigente (misma respuesta que GET /profile).
• GET /terms/current (público, sin token): versión vigente de los Términos y Condiciones. Su id es el terms_version_id que debes enviar al crear una solicitud.

Detalle en Autenticación y Datos maestros.

Empresa

• PUT /company/{id}: actualiza los datos de tu empresa. Los campos se envían como objeto JSON serializado en records, y solo puedes modificar tu propia empresa.

Detalle en Empresa.

Emisión, renovación y archivos

• GET /certificate-request/{id}/issuance/renewal: indica si el certificado se puede renovar hoy, el motivo cuando no (reason), las fechas de vencimiento comercial y de revocación, el precio (quote) y la orden de renovación pendiente (pending_order). Solo consulta: no crea órdenes.
• POST /certificate-request/{id}/issuance/reject: rechaza de forma definitiva un trámite Viafirma en curso que aún no tiene certificado emitido. La solicitud queda cancelada, se reintegra el cupo y debes crear una solicitud nueva. No sirve para anular certificados emitidos: para eso está la revocación.
• GET /certificate-request/{uuid}/files/{fileUuid}/download: devuelve una URL firmada (vigencia 24 h) para descargar un archivo de la solicitud. El certificado (CERTIFICATE) solo se entrega si la solicitud está en PROCESSED; si no, responde 409 con el estado actual en status (los administradores de la plataforma pueden descargarlo en cualquier estado).

Detalle en Emisión de certificados, Viafirma y Archivos.

Cambios de comportamiento

Solicitudes de certificado

• DELETE /certificate-request/{id} solo elimina solicitudes en DRAFT o REJECTED; en cualquier otro estado responde 409. Al eliminar se devuelve el cupo consumido.
• DELETE /certificate-request/{id}/files/{fileId} responde 409 si el archivo no se puede eliminar: los artefactos internos nunca; el certificado emitido (CERTIFICATE) solo lo puede eliminar un administrador de la plataforma; los adjuntos (ATTACHED) solo con la solicitud en DRAFT, PENDING o REJECTED. Los comprobantes de pago (PAYMENT) se pueden eliminar en cualquier estado.
• PUT /certificate-request/{id}/status: una empresa solo puede llevar sus solicitudes a DRAFT, SENT o CANCELLED (otro destino responde 403); una transición no permitida desde el estado actual responde 422.
• Los listados se paginan con el parámetro page: GET /certificate-request, GET /orders, GET /notifications, GET /webhooks y GET /webhooks/{id}/deliveries.
• Si la verificación de identidad no se completa dentro del plazo, la solicitud se cancela automáticamente y el cupo vuelve a quedar disponible. Mientras esté pendiente se envía un recordatorio diario por correo y WhatsApp, y un último aviso 24 horas antes del vencimiento.
• Cada empresa puede configurar a qué página se redirige al solicitante al terminar la verificación de identidad.
• Cuando una solicitud es rechazada, la cuenta principal de la empresa recibe un aviso por correo y WhatsApp con el motivo.
• El estado de las solicitudes en trámite se actualiza en pocos minutos (antes, hasta media hora).
• Al cancelar una solicitud se devuelve exactamente el cupo que había consumido.

Emisión y descarga

• El certificado se entrega como un .zip que contiene el .p12, junto con el PIN para abrirlo. En GET /certificate-request/{uuid}/issuance/download, si el archivo no está disponible la respuesta es 404.
• POST /certificate-request/{id}/issue: si otra emisión de la misma solicitud se está enviando en ese momento, responde 409 sin crear un trámite nuevo (consulta el estado con GET /certificate-request/{id}/issuance). Límite: 5 emisiones por minuto por usuario (429). Cada solicitud tiene una sola verificación de identidad.
• Si recibiste varios correos de "certificado listo" para el mismo certificado, la contraseña válida es la del correo más reciente.

Renovación

• Los certificados de 1 año emitidos con Viafirma se pueden renovar por un año más sin reemitirlos, desde la emisión y hasta 15 días después del vencimiento (periodo de gracia). Te avisamos por correo el día siguiente al vencimiento y 3 días antes del cierre del plazo. Si no se renueva a tiempo, el certificado se revoca.
• POST /certificate-request/{id}/issuance/renew: si ya existe una orden de renovación pendiente, devuelve esa misma en lugar de crear otra, así que no hay cobros duplicados. Si el certificado no es renovable responde 422 con reason (NOT_RENEWABLE_PROVIDER, NOT_ACTIVE, MAX_TERM o GRACE_EXPIRED). La orden se paga después con los endpoints de Órdenes.
• Si el certificado deja de ser renovable (por ejemplo, porque terminó el periodo de gracia), su orden de renovación pendiente se anula para que no se cobre. POST /orders/{uuid}/pay y POST /orders/{uuid}/retry responden 422 con reason en ese caso.

Cuenta, empresa y autenticación

• POST /auth/login acepta remember_me (booleano); por ahora no cambia la vigencia del token.
• La documentación de POST /register ahora incluye los campos opcionales que ya se aceptaban: country_id, identity_document_id, type_organization_id, address, location, postal_code y phone. No es un cambio de comportamiento.
• Los correos con tildes, eñes o espacios no pueden recibir mensajes, así que se rechazan al registrar la cuenta o al cambiar el correo del perfil o de la empresa.
• GET /company acepta el parámetro opcional uid; solo puedes consultar tu propia empresa (otra responde 404).
• PUT /profile/{id} y PUT /settings/reports/{id} exigen el campo records. PUT /company/settings no admite actualizaciones por la API: consulta A tener en cuenta.
• POST /orders responde 200 con la orden creada en PENDING (la documentación anterior indicaba 201).

Endpoints retirados o reubicados

Antes	Ahora
POST /certificate-request/{id}/revoke (ID numérico)	POST /certificate-request/{uuid}/revoke (UUID público de la solicitud)
GET /company, GET /company/settings y PUT /company/settings en el grupo «Configuración»	Grupo Empresa (sobre PUT /company/settings, consulta A tener en cuenta)

La referencia anterior incluía además algunas operaciones de uso interno de la plataforma: administración, monitoreo, autocompletado del formulario de la aplicación web, sincronización entre sistemas propios y notificaciones de la pasarela de pagos. Nunca formaron parte del contrato para integradores y se retiraron de la documentación pública. Si tu integración usaba alguna, cámbiala por los endpoints específicos de cada recurso.

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 versión de la especificación OpenAPI coincide ahora con la versión de la API (la del backend). La especificación anterior declaraba 3.0.0 por error: ese número no correspondía a ninguna versión de la API.
• Las entradas anteriores de este registro (1.0.0, 1.0.1 y 1.1.0) son versiones del portal de documentación. La 1.0.1 y la 1.1.0 solo cambiaron el portal, sin cambios en la API.
• La referencia declara las URL base públicas: producción https://api.maticerts.com/api/v1 y sandbox https://sandbox-api.maticerts.com/api/v1.
• Cada endpoint documenta con exactitud los datos que acepta y devuelve, los permisos que requiere y sus respuestas de error (400, 401, 402, 403, 404, 409, 422, 429, 500) con los mensajes reales.

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