VST

by Levant

API de emisión de certificados de firma electrónica en Ecuador, sobre la infraestructura de FirmaSegura.

Base https://firmas.vard.cloud

Qué resuelve

En Ecuador, facturar electrónicamente exige un certificado de firma (.p12) emitido por una entidad autorizada. Conseguirlo implica recoger documentos del titular, validar su identidad y seguir el trámite hasta que el certificado se emite. Esta API hace ese trabajo por ti.

Validación local antes de gastar una llamada. Cédula y RUC con los tres algoritmos de verificador, edad mínima, código dactilar y el catálogo geográfico exacto que acepta el proveedor. Los errores se detectan en tu integración, no doce minutos después.
Dos flujos. El regular, que admite representante legal y el vídeo de tercera edad; y el simplificado, en el que el titular completa la prueba de vida por su cuenta.
Estado sin sondeo por tu parte. Nosotros consultamos al proveedor y te avisamos por webhook. Si el evento llega antes que el trámite, se difiere y se reintenta en vez de perderse.
Nada se pierde en un fallo transitorio. Toda salida pasa por una cola con reintentos, deduplicación y rescate de trabajos atascados.
Datos personales cifrados en reposo. Cédula, código dactilar, correo, teléfono y dirección se guardan cifrados; las evidencias, fuera de cualquier árbol servible.

Estado de la API

Esto es lo que hay hoy, sin adornos. Solo se documentan endpoints que responden de verdad.

Sonda de salud disponible

Acceso al back office disponible

Receptor de webhooks disponible

Alta y consulta de solicitudes implementado y probado, pendiente de exponer

Cobros, lotes y gestión de usuarios en construcción

Convenciones

Todo es application/json, salvo esta página.
Las fechas viajan en ISO 8601 con zona horaria explícita.
El dinero, cuando lo haya, viaja como cadena decimal. Nunca como número en coma flotante.
Los errores comparten forma: { "codigo": "...", "mensaje": "..." }. El codigo es estable y es contra lo que debes programar; el mensaje está escrito para que lo lea una persona y puede cambiar.

Endpoints

GET/healthpública

Comprueba que el servicio vive y alcanza su base de datos. Es la sonda que usan Docker y el balanceador; no consume cuota del limitador.

curl https://firmas.vard.cloud/health

200 → {"estado":"ok"}
503 → {"estado":"degradado"}

No comprueba a FirmaSegura ni a la pasarela de pago a propósito: si el proveedor está caído, este servicio sigue sano y debe seguir aceptando tráfico.

POST/auth/accesopública

Primer paso del ingreso al back office. Devuelve un token de sesión y el paso siguiente: el segundo factor es obligatorio para todos los roles.

curl -X POST https://firmas.vard.cloud/auth/acceso \
  -H 'content-type: application/json' \
  -d '{"correo":"persona@ejemplo.ec","clave":"..."}'

200 → {
  "token": "eyJhbGciOi...",
  "expiraAt": "2026-08-31T18:46:30.000Z",
  "rol": "ADMINISTRADOR",
  "nombreCompleto": "...",
  "siguientePaso": "ENROLAR_MFA"
}

Estado	Código	Cuándo
`400`	`ENTRADA_INVALIDA`	El cuerpo no cumple el formato
`401`	`CREDENCIALES_INVALIDAS`	Correo desconocido, cuenta inactiva o contraseña incorrecta
`429`	`DEMASIADAS_PETICIONES`	Más de 5 intentos por minuto

Los tres motivos del 401 devuelven la misma respuesta y tardan lo mismo, a propósito: distinguirlos permitiría averiguar qué correos tienen cuenta.

POST/webhooks/firmasegurasecreto compartido

Recibe los eventos del proveedor en formato CloudEvents 1.0 y actualiza el trámite. Está pensado para que lo llame FirmaSegura, no tu integración.

POST /webhooks/firmasegura
x-vast-secret: <secreto acordado>
content-type: application/json

{"specversion":"1.0","id":"evt-001",
 "type":"ec.firmasegura.signature.session.completed",
 "subject":"<id de sesión>","data":{}}

200 → {"received":true,"message":"Evento aplicado a la solicitud."}
401 → {"received":false}

Sin secreto configurado, rechaza. Nunca acepta por defecto.
Idempotente por id. Un reenvío devuelve 200 sin repetir efectos.
Tolerante al desorden. Un evento que llega antes que su sesión se archiva y se reintenta.

Límites de peticiones

Ruta	Límite	Por qué
`/auth/acceso`	5 / minuto	Frena el probado de contraseñas
`/webhooks/firmasegura`	120 / minuto	Holgado para el proveedor, acotado para el resto
Resto	300 / minuto	Techo general
`/health`	sin límite	Las sondas no deben recibir 429

Al superarlo llega un 429 con la cabecera Retry-After en segundos.

En construcción

Lo que sigue existe en el código y está probado, pero todavía no se expone. Se documentará aquí cuando responda, no antes:

Alta, consulta, corrección y anulación de solicitudes.
Cobros, saldos a favor y devoluciones.
Carga de lotes para estudios contables.
Gestión de usuarios e invitaciones del back office.

Contacto

La API la opera LEVANTNET CONSULTING S.A.S. desde Quito, Ecuador. Para credenciales, integraciones o el secreto del webhook, escríbenos.

V ST