API de anulación de tickets `v1`

Este endpoint permite anular un ticket desde un cliente. El servidor concentra la autorización y todas las validaciones de la banca: estado del usuario, estado del ticket, ventana de tiempo permitida y cierre de sorteos. El cliente solo envía el identificador del ticket.

URL de producción:


/api/v1/store/cancel

Autenticación

La API requiere un usuario autenticado. Desde la web de esta aplicación se usa la sesión por cookies (no se envía el header Authorization). Para un cliente externo se usa un API token de taquilla, que el dueño genera, rota y revoca desde la web (/banca/taquillas/:id):


Authorization: Bearer tbk_<api-token>

El token empieza con el prefijo tbk_ y está vinculado a una sola taquilla: solo se pueden anular tickets de esa taquilla; en otro caso la API responde 403. El token solo se muestra una vez al generarlo o rotarlo: guárdalo de forma segura en el cliente. Si se pierde o se sospecha de fuga, revócalo y genera uno nuevo.

El usuario debe estar activo. Un token tbk_ inválido o revocado devuelve 401; una sesión web ausente o vencida devuelve 401 AUTHENTICATION_REQUIRED.

La ruta permite CORS para POST y OPTIONS. No envíes claves service_role ni otros secretos al cliente.

Anular un ticket

Envía únicamente el identificador del ticket (tid) como UUID.


POST /api/v1/store/cancel
Content-Type: application/json
Authorization: Bearer tbk_<api-token>


{
  "tid": "33333333-3333-3333-3333-333333333333"
}

Ejemplo con fetch:


const response = await fetch(`${API_URL}/api/v1/store/cancel`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${apiToken}`,
  },
  body: JSON.stringify({ tid }),
})
 
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
 
// result.data => { tid, cancel: true }

Respuesta exitosa (200):


{
  "data": {
    "tid": "33333333-3333-3333-3333-333333333333",
    "cancel": true
  }
}

Validaciones del servidor

Antes de anular el ticket, la API verifica, entre otras reglas:

Que el usuario esté autenticado y activo.
Que el ticket exista y no esté ya anulado.
Que el token de acceso (si se usa un API token) pertenezca a la taquilla del ticket.
Que ninguno de sus números esté jugado (estado distinto de default).
Que ninguno de sus números esté pagado (paid).
Que no se haya excedido la ventana de tiempo para anular desde la creación del ticket:
- 10 minutos para usuarios estándar.
- 25 minutos para usuarios admin.
- Sin límite para usuarios master.
Que ninguno de los sorteos asociados haya cerrado según la hora de Caracas del servidor.

El usuario super-master omite las validaciones de números jugados y de cierre de sorteos.

Errores

Estado	Código	Significado
`400`	`INVALID_REQUEST`	El body no cumple el contrato: `tid` ausente o UUID inválido.
`400`	`CANCEL_ERROR`	Una regla de negocio no pasó (ticket ya anulado, números jugados/pagados, tiempo excedido, sorteo cerrado, etc.). Muestra `error.message` al usuario.
`401`	`CANCEL_ERROR`	Falta el token de acceso o el API token `tbk_` es inválido, está revocado o vencido.
`401`	`AUTHENTICATION_REQUIRED`	El usuario no está activo.
`403`	`CANCEL_ERROR`	El token de acceso no pertenece a la taquilla del ticket.
`404`	`CANCEL_ERROR`	El ticket no existe.
`429`	`RATE_LIMIT_EXCEEDED`	Límite de solicitudes excedido. Aplica espera incremental antes de reintentar.
`500`	`CANCEL_ERROR`	Error inesperado al anular el ticket.
`503`	`CANCEL_ERROR`	La conexión a la base de datos no está disponible.

Formato común de error:


{
  "error": {
    "code": "CANCEL_ERROR",
    "message": "Tiempo para anular el ticket excedido"
  }
}

Recomendaciones de cliente

Usa el estado HTTP para el flujo de red y error.code para decisiones programáticas.
error.message está listo para presentarse al usuario.
Refresca el listado de tickets tras una anulación exitosa para reflejar el nuevo estado.

Límites de solicitudes

Límites predeterminados:

90 solicitudes por API key (o token) por minuto.
90 solicitudes por IP por minuto.

Cada respuesta incluye RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos restantes de la ventana). Al superar el límite, la API responde 429 RATE_LIMIT_EXCEEDED con Retry-After en segundos.

Evita consultar saldo en cada pulsación del usuario. Ante un 429, usa espera incremental con variación aleatoria y no ejecutes reintentos en bucle.

API de anulación de tickets v1