← Volver a la portada

VST

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

Base https://firma.vard.cloud

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 la portada y esta página.
Las fechas viajan en ISO 8601 con zona horaria explícita.
El dinero 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://firma.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://firma.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.