Saltar al contenido principal

API 1.19.5 - 404 en recursos inexistentes y errores sin detalles internos

· 7 min de lectura

Aquí resumimos lo que cambió para los integradores desde la entrada 1.19.1. Incluye las versiones 1.19.2 y 1.19.3, con cambios en las respuestas de error, la emisión con Viafirma y los pagos de órdenes, y las versiones 1.19.4 y 1.19.5, que revisan la referencia de la API sin cambiar su funcionamiento. Las rutas siguen bajo el prefijo /api/v1.

Cambios que requieren acción
  • Un recurso inexistente responde 404 en lugar de 500: en las operaciones que se listan más abajo, en «Recursos inexistentes», la API responde 404 con {"success":false,"message":"Recurso no encontrado."}. Antes respondía 500 y el mensaje incluía detalles internos. Si tu integración trataba ese 500 como "aún no existe" o como error del servidor, trata ahora el 404.
  • Corrección a la entrada 1.19.1: allí indicamos que 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). Desde la 1.19.2 responde 404 con message = Recurso no encontrado.: si la emisión con Viafirma está por iniciarse, reintenta más tarde.
  • POST /certificate-request/{id}/issue puede responder 503: lo hace cuando no se puede proteger la llave del certificado en el servidor (ver «Emisión con Viafirma» más abajo). Antes ese fallo respondía 422. Es un error temporal: reintenta más tarde.

Cambios de comportamiento​

Recursos inexistentes: 404 en lugar de 500​

Cuando el recurso que pides no existe, o pertenece a otra empresa, estas operaciones responden 404 con {"success":false,"message":"Recurso no encontrado."}. Antes respondían 500.

  • GET /certificate-request/{id}/kyc-link: la solicitud existe pero todavía no tiene trámite de Viafirma (su emisión con Viafirma aún no se ha iniciado) o se emite con otro proveedor.
  • POST /certificate-request/{uuid}/revoke: la solicitud existe pero no tiene trámite de Viafirma (por ejemplo, se tramitó por correo).
  • GET /orders/{uuid}: la orden no existe, es de otra empresa o el uuid no tiene formato UUID.
  • POST /orders/{uuid}/pay, POST /orders/{uuid}/retry y DELETE /orders/{uuid}: además de los casos anteriores, la orden no está en PENDING. Una orden de renovación que pasó a FAILED tras un 422 de /pay o /retry responde 404 en las llamadas siguientes.
  • PUT /certificate-request/{id}: la solicitud no existe o es de otra empresa.

Los demás 404 no cambian. Si la solicitud no existe o es de otra empresa, kyc-link y revoke siguen respondiendo Solicitud de certificado no encontrada.. Si tu usuario no tiene empresa asociada, las órdenes siguen respondiendo No se encontró la empresa asociada al usuario..

Detalle en Viafirma, Órdenes y Solicitudes de certificado.

Mensajes de error sin detalles internos​

  • Errores de Viafirma en GET /certificate-request/{id}/kyc-link y POST /certificate-request/{uuid}/revoke: cuando Viafirma responde con error, la API sigue respondiendo 422, pero message es ahora uno de estos textos fijos, sin el detalle técnico del servicio:
    • Error de comunicación con Viafirma RA. Intente nuevamente.: fallo de comunicación o error temporal. Puedes reintentar.
    • Viafirma no admite la operación en el estado actual de la solicitud.
    • Viafirma no encuentra la solicitud asociada.
    • El servicio de Viafirma rechazó la operación. Revisa los datos e intenta de nuevo.: puede terminar en Código: ... cuando Viafirma devuelve un código de error.
  • Estado de la emisión: en GET /certificate-request/{id}/issuance, last_error_message trae un texto fijo en dos casos. Con last_error_code = ASSEMBLE_FAILED trae No se pudo generar el archivo del certificado. Se reintentará automáticamente. y con REQUEST_NOT_FOUND trae La solicitud ya no existe en Viafirma..
  • Si tu integración analizaba el texto de estos errores, guíate por el código HTTP y por last_error_code.

Emisión con Viafirma​

  • POST /certificate-request/{id}/issue: si no se puede proteger la llave privada del certificado en el servidor, la API responde 503 (No se pudo proteger la llave del certificado. Intente de nuevo más tarde.) con provider = viafirma. Antes respondía 422 con el detalle técnico. No se registra ningún trámite, así que puedes reintentar la emisión más tarde, sin superar el límite de 5 emisiones por minuto.

Detalle en Emisión de certificados.

Pagos de órdenes​

  • Notificaciones repetidas o fuera de orden de la pasarela de pagos: ya no hacen retroceder el estado de un pago. Una orden PAID no vuelve a PENDING ni pasa a FAILED. Una transacción en estado final (APPROVED, DECLINED o VOIDED) tampoco cambia, salvo APPROVED → VOIDED.
  • Pago aprobado y anulado después en la pasarela: la transacción pasa a VOIDED y la orden conserva su estado.
  • Cupos y renovaciones: los cupos PREPAID o la renovación de un pago aprobado se aplican una sola vez, aunque la notificación llegue repetida.

Consulta el resultado con GET /orders/{uuid} (status de la orden y latest_transaction.status). Detalle en Órdenes.

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.

Campo comments al cambiar el estado de una solicitud

En PUT /certificate-request/{id}/status, comments es obligatorio y debe ser texto no vacío. Si se omite, o llega null, vacío o solo con espacios, la API responde 400 (Falta un dato obligatorio.) y el estado no cambia. Con un tipo distinto de texto (por ejemplo, un número o un arreglo JSON) responde 500. Detalle en Solicitudes de certificado.

Documentación​

  • La referencia de la API se revisó de nuevo operación por operación contra el funcionamiento real de la API 1.19.x. La API no cambia en la 1.19.4 ni en la 1.19.5: solo su documentación.
  • La versión de la referencia sigue la del backend y ahora es la 1.19.5.
  • Algunas correcciones que pueden afectar tu integración:
    • Las operaciones de «Recursos inexistentes» documentan el 404 (Recurso no encontrado.) donde antes figuraba un 500.
    • La respuesta 429 del límite general (60 peticiones por minuto por usuario o, sin sesión, por IP) incluye las cabeceras Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (marca de tiempo Unix del momento en que se libera el límite). POST /register documenta también este 429.
    • Los ejemplos de la respuesta 401 muestran el cuerpo exacto que devuelve la API.
    • En POST /register, envía dni solo con dígitos, sin puntos, guiones, espacios ni DV, y con 15 cifras como máximo. Hoy otros valores no responden 422: algunos responden 500 y otros se aceptan y se guardan tal cual. Detalle en Autenticación.
    • POST /certificate-request/{id}/issue documenta el nuevo 503, y kyc-link y revoke documentan los textos fijos de los errores de Viafirma.
  • Las guías y la colección de Postman se actualizaron con el 404 de los recursos inexistentes, incluido el caso de kyc-link justo después de crear la solicitud.

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