Referencia · v1

Cada endpoint, entero

Qué pide, qué devuelve, qué cambia si mandas la clave y cómo falla. La portada cuenta la idea; esto es para tenerlo abierto en otra pestaña mientras escribes el fetch. Si lo tuyo es Node y Express —que es lo normal—, empieza por llamar a esto desde tu proyecto.

Todos los ejemplos apuntan al servidor de clase, https://nfc.multimediaudeb.com/api/v1. Si levantas una copia en tu máquina, cambia esa base por http://localhost:3000/api/v1 y lo demás es idéntico.

Base

https://nfc.multimediaudeb.com/api/v1

Formato

JSON en los dos sentidos

Fechas

ISO 8601 en UTC

Dinero

enteros de pesos (COP)

La forma de un error

Todos los errores traen un código en snake_case en el campo error, y algunos añaden lo que hace falta para arreglarlo sin adivinar: el rango que se pasó, lo que falta de saldo, los valores válidos. El código HTTP dice de qué tipo es; el error, cuál es.

{ "error": "monto_fuera_de_rango", "minimo": 100, "maximo": 500000 }
{ "error": "saldo_insuficiente", "saldo": 1200, "falta": 1750 }
{ "error": "perfil_desconocido", "validos": ["general", "estudiante", "adulto_mayor", "empleado"] }

Programa contra el campo error, nunca contra el texto de ayuda: el código es parte del contrato y la ayuda está escrita para una persona, así que puede cambiar de redacción cualquier día.

Los sellos de cada ficha

Arriba de cada endpoint hay uno o dos sellos con lo que hace falta para llamarlo. Significan esto:

• abierto Sin credenciales. Un fetch pelado desde cualquier sitio.
• + clave: más campos Se puede llamar sin nada, pero mandar la clave amplía lo que devuelve. Es donde está el email, el saldo y el uid.
• clave Obligatoria la cabecera X-API-Key. Sin ella, 401.
• clave dueña Además, tiene que ser la clave que creó ese usuario o esa tarjeta. Solo lo piden las rutas que modifican o borran; mover saldo no. Si no, 403 no_es_tuyo.
• token Obligatoria la cabecera Authorization: Bearer de un usuario que inició sesión.
• profesor Pide X-Admin-Token. No es para los proyectos.

Paginación

Las listas —usuarios, tarjetas, movimientos— aceptan siempre los dos mismos parámetros de consulta y responden con la misma envoltura. Los valores fuera de rango se recortan en silencio en vez de dar error: pedir limite=9999 devuelve 200, y limite=-4, uno.

{ "total": 128, "limite": 50, "desde": 0, "usuarios": [ … ] }

total cuenta todo lo que cumple el filtro, no lo que vino en esta página: es lo que se usa para saber si hay que pedir otra.

Credenciales

Qué cambia con la clave y qué cambia con el token

Son dos cosas distintas y responden preguntas distintas. La clave dice desde qué proyecto se está escribiendo. El token dice quién está usándolo. No se sustituyen: hay rutas que piden una, otras la otra, y mover saldo pide las dos.

Lo que se ve según lo que mandes

Leer es público en casi toda la API, pero público no es entero. Esta es la tabla que resuelve la mitad de las dudas:

Da igual de qué clave sea el usuario: cualquier clave válida abre los campos reservados y mueve el saldo de cualquier usuario. La clave no separa datos —la base es una y compartida—, decide si te enseñan la ficha completa y firma lo que escribes. De qué clave sea solo importa para una cosa: modificar o borrar un usuario o una tarjeta, que solo puede hacerlo la que lo creó.

Las dos cabeceras a la vez

curl -X POST https://nfc.multimediaudeb.com/api/v1/wallet/topup \
  -H "X-API-Key: $CLAVE" \
  -H "Authorization: Bearer $ACCESO" \
  -H "Content-Type: application/json" \
  -d '{"monto": 5000, "concepto": "Recarga"}'

await fetch("https://nfc.multimediaudeb.com/api/v1/wallet/topup", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TUNJA_CLAVE,
    Authorization: `Bearer ${acceso}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ monto: 5000, concepto: "Recarga" }),
});

Si se te olvida el Content-Type: application/json, el cuerpo llega vacío y la API responde como si no hubieras mandado nada —monto_invalido, típicamente—. Es el error más común de la primera tarde. En fetch pasa lo mismo si mandas el objeto sin JSON.stringify.

GET /api/v1/key
X-API-Key: tk_9fK2xQm…

{
  "prefijo": "tk_9fK2xQm",
  "estudiante": "Ana Ruiz",
  "usuarios": 14,
  "limite_usuarios": 200
}

Node y Express

Llamar a esto desde tu proyecto

Los ejemplos de cada endpoint están en curl y en HTTP crudo porque son la forma más corta de decir qué viaja por el cable. Pero lo que vas a escribir es Node, así que aquí está lo mismo con Express, que es lo que se copia y pega de verdad. No hace falta instalar nada para llamar: fetch viene dentro de Node desde la versión 18.

Dónde va la clave

Esta es la decisión que ordena todo lo demás. La clave es un secreto del proyecto: si la escribes en el JavaScript que baja al navegador, cualquiera que abra las herramientas de desarrollo la tiene, y con ella puede crear usuarios y mover saldo firmando con tu nombre. Así que la clave vive en tu servidor Express y nunca sale de ahí.

navegador  ──▶  tu Express          ──▶  TunjaAPI
(sin clave)     (X-API-Key aquí)         nfc.multimediaudeb.com

Del navegador a la API directamente solo van las cosas que no piden clave: el login, /users, /cards/:uid. El CORS está abierto justo para eso.

TUNJA_API=https://nfc.multimediaudeb.com/api/v1
TUNJA_CLAVE=tk_9fK2xQm7vN3pR8sT1uW5yZ0

# Node 20.6 o más nuevo: sin dotenv
node --env-file=.env server.js

Y .env al .gitignore antes del primer commit. Una clave subida a GitHub hay que revocarla y pedir otra; no se puede "borrar del historial" y quedarse tranquilo.

El cliente: un archivo, una función

Todo el proyecto llama a la API por aquí. Concentrarlo en una función evita repetir cabeceras en veinte sitios y, sobre todo, deja un solo lugar donde entender los errores: la API contesta con un código HTTP y un campo error, y eso se convierte en una excepción con esos dos datos dentro.

// api.js — el único archivo del proyecto que conoce la clave
const API = process.env.TUNJA_API ?? "https://nfc.multimediaudeb.com/api/v1";
const CLAVE = process.env.TUNJA_CLAVE;

export async function tunja(camino, { metodo = "GET", cuerpo, token } = {}) {
  const respuesta = await fetch(API + camino, {
    method: metodo,
    headers: {
      ...(cuerpo && { "Content-Type": "application/json" }),
      ...(CLAVE && { "X-API-Key": CLAVE }),
      ...(token && { Authorization: `Bearer ${token}` }),
    },
    body: cuerpo && JSON.stringify(cuerpo),
  });

  // Un 204 no trae cuerpo: pedirle .json() revienta.
  const datos = respuesta.status === 204 ? null : await respuesta.json();

  if (!respuesta.ok) {
    const fallo = new Error(datos?.error ?? "error_desconocido");
    fallo.estado = respuesta.status;   // 402, 409, 404…
    fallo.datos = datos;               // { error, falta, minimo… }
    throw fallo;
  }

  return datos;
}

Ojo con esto: fetch no lanza cuando la respuesta es un 402 o un 409 — solo si no hubo respuesta. Sin el if (!respuesta.ok), un cobro sin saldo pasa por bueno y tu torniquete abre la puerta gratis. Es el fallo clásico de la primera versión.

Una ruta de Express que registra gente

El formulario del navegador manda los datos a tu servidor, y es tu servidor —que tiene la clave— el que habla con TunjaAPI. De paso puedes traducir los errores al idioma de tu proyecto.

// server.js
import express from "express";
import { tunja } from "./api.js";

const app = express();
app.use(express.json());

app.post("/registro", async (req, res) => {
  const { email, contrasena, nombre } = req.body;

  try {
    const { usuario, acceso, refresco } = await tunja("/auth/register", {
      metodo: "POST",
      cuerpo: { email, contrasena, nombre, perfil: "estudiante" },
    });

    // El par de tokens es del usuario: se lo devuelves y tu servidor no lo guarda.
    res.status(201).json({ usuario, acceso, refresco });
  } catch (fallo) {
    if (fallo.message === "email_en_uso") {
      return res.status(409).json({ error: "Esa persona ya está en la base: que inicie sesión" });
    }
    if (fallo.message === "contrasena_debil") {
      return res.status(400).json({ error: `Contraseña débil: ${fallo.datos.motivo}` });
    }
    console.error(fallo);
    res.status(502).json({ error: "La API no respondió" });
  }
});

app.listen(3000);

Y otra que hace de torniquete

El caso completo en veinte líneas: llega un uid, se mira de quién es, se calcula la tarifa —que es tuya, no de la API— y se cobra.

const TARIFA = { general: 2950, estudiante: 1500, adulto_mayor: 0, empleado: 2500 };

app.post("/pasar", async (req, res) => {
  const uid = String(req.body.uid ?? "").toUpperCase();

  let tarjeta;
  try {
    tarjeta = await tunja(`/cards/${uid}`);
  } catch (fallo) {
    if (fallo.estado === 404) return res.json({ paso: false, motivo: "tarjeta_no_registrada" });
    throw fallo;
  }

  if (!tarjeta.activa) return res.json({ paso: false, motivo: "tarjeta_bloqueada" });

  const { id, perfil, descuento } = tarjeta.usuario;
  const monto = Math.round((TARIFA[perfil] ?? TARIFA.general) * (1 - descuento / 100));

  if (monto === 0) return res.json({ paso: true, monto: 0 });   // gratis: ni se apunta

  try {
    const cobro = await tunja(`/users/${id}/wallet/charge`, {
      metodo: "POST",
      cuerpo: { monto, concepto: "Pasaje" },
    });
    res.json({ paso: true, monto, saldo: cobro.saldo });
  } catch (fallo) {
    if (fallo.message === "saldo_insuficiente") {
      return res.json({ paso: false, motivo: "saldo_insuficiente", falta: fallo.datos.falta });
    }
    throw fallo;
  }
});

Fíjate en que saldo_insuficiente no se trata como un error del programa sino como un resultado posible: el torniquete no se rompe, no deja pasar. Lo mismo con el 404 de la tarjeta. Los throw que quedan son para lo que no esperabas — Express 5 recoge solo las promesas rechazadas y las lleva a su manejador de errores; si tu proyecto va con Express 4, envuelve el manejador en un try/catch o el proceso se cae.

Si prefieres axios

Funciona igual, con una diferencia que hay que tener presente: axios sí lanza con un 402 o un 409, y el cuerpo de la API llega en error.response.data.

import axios from "axios";

const tunja = axios.create({
  baseURL: process.env.TUNJA_API ?? "https://nfc.multimediaudeb.com/api/v1",
  headers: { "X-API-Key": process.env.TUNJA_CLAVE },
});

try {
  const { data } = await tunja.post(`/users/${id}/wallet/charge`, { monto: 1500 });
  console.log(data.saldo);
} catch (fallo) {
  const cuerpo = fallo.response?.data;          // { error: "saldo_insuficiente", falta: 1750 }
  if (cuerpo?.error === "saldo_insuficiente") console.log(`Faltan ${cuerpo.falta}`);
}

Guardar el token de cada usuario

Si tu proyecto tiene login, lo normal es que el navegador se quede con el par de tokens y los mande en cada llamada, y que tu Express los reenvíe cuando necesite actuar en nombre de esa persona. El acceso dura 15 minutos, así que hace falta refrescarlo: la tercera receta tiene ese trozo resuelto.

// El navegador manda su acceso; tu servidor solo lo pasa adelante.
app.post("/recargar", async (req, res) => {
  const acceso = req.get("Authorization")?.replace("Bearer ", "");
  if (!acceso) return res.status(401).json({ error: "inicia_sesion" });

  // Con token y clave a la vez: el usuario dice quién es, tu clave desde dónde.
  const movimiento = await tunja("/wallet/topup", {
    metodo: "POST",
    token: acceso,
    cuerpo: { monto: req.body.monto, concepto: "Recarga en línea" },
  });

  res.json(movimiento);
});

Guarda el refresco donde puedas, pero no lo trates como un dato más: quien lo tenga entra como esa persona durante 30 días. Y no guardes nunca contraseñas en tu proyecto — para eso está el login de la API.

Config

Lo que hay que saber antes de empezar

GET /api/v1/config

{
  "nombre": "TunjaAPI",
  "version": 1,
  "moneda": "COP",
  "perfiles": ["general", "estudiante",
               "adulto_mayor", "empleado"],
  "limites": {
    "montoMinimo": 100,
    "montoMaximo": 500000,
    "saldoMaximo": 2000000,
    "usuariosPorClave": 200,
    "peticionesPorMinuto": 120
  }
}

CORS y rutas que no existen

Todo /api/v1 responde con Access-Control-Allow-Origin: * y acepta Content-Type, Authorization, X-API-Key y X-Admin-Token. Puedes llamar desde localhost:5173, desde un Netlify o desde un index.html abierto a pelo. Las credenciales viajan en cabeceras y no hay cookies, que es justo lo que hace seguro el comodín.

Una ruta que no existe bajo la base responde 404 con { "error": "ruta_desconocida", "ayuda": "Ver /api/v1/config" }. Si te sale eso, casi siempre es una barra de más, un /api/users sin el /v1, o un método que esa ruta no acepta.

Autenticación

Registro, sesión y tokens

Un usuario se crea aquí y solo aquí: no hay POST /users, porque la contraseña es obligatoria y sin ella nadie podría entrar a su propia cuenta. Registro y login devuelven exactamente lo mismo —el usuario completo y un par de tokens—, así que después de registrar a alguien no hace falta iniciarle sesión.

POST /api/v1/auth/register
X-API-Key: tk_9fK2xQm…
Content-Type: application/json

{
  "email": "ana@ejemplo.com",
  "contrasena": "tunja2026",
  "nombre": "Ana Ruiz",
  "documento": "1.020.334.881",
  "perfil": "estudiante",
  "descuento": 0
}

{
  "usuario": {
    "id": 7,
    "nombre": "Ana Ruiz",
    "iniciales": "AR",
    "perfil": "estudiante",
    "descuento": 0,
    "activo": true,
    "creado": "2026-07-31T06:31:26.988Z",
    "email": "ana@ejemplo.com",
    "documento": "1.020.334.881",
    "saldo": 0,
    "actualizado": "2026-07-31T06:31:26.988Z",
    "sin_credenciales": false
  },
  "acceso": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOjcsInR2IjoxfQ…",
  "refresco": "x_70BjCLPw_bnx1bWspfZgTqbE4AJBEePZ3Kcr6lX4k",
  "expira_en": 900
}

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "ana@ejemplo.com",
  "contrasena": "tunja2026" }

{
  "usuario": { "id": 7, "nombre": "Ana Ruiz", … },
  "acceso": "eyJhbGciOiJIUzI1NiJ9…",
  "refresco": "x_70BjCLPw_bnx1bWspfZ…",
  "expira_en": 900
}

POST /api/v1/auth/refresh
Content-Type: application/json

{ "refresco": "x_70BjCLPw_bnx1bWspfZ…" }

{
  "usuario": { "id": 7, … },
  "acceso": "eyJhbGciOiJIUzI1NiJ9…",   ← nuevo
  "refresco": "y_9dTkQ1sM_pw82…",      ← nuevo
  "expira_en": 900
}

POST /api/v1/auth/logout
Content-Type: application/json

{ "refresco": "x_70BjCLPw_bnx1bWspfZ…" }

(sin cuerpo)

GET /api/v1/auth/me
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

{
  "id": 7, "nombre": "Ana Ruiz", "iniciales": "AR",
  "perfil": "estudiante", "descuento": 0,
  "activo": true, "creado": "2026-07-31T06:31:26.988Z",
  "email": "ana@ejemplo.com",
  "documento": "1.020.334.881",
  "saldo": 47050,
  "actualizado": "2026-07-31T18:02:11.401Z",
  "sin_credenciales": false
}

POST /api/v1/auth/password
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…
Content-Type: application/json

{ "actual": "tunja2026",
  "nueva": "boyaca-2027!" }

{
  "usuario": { "id": 7, … },
  "acceso": "eyJ…",     ← guarda estos
  "refresco": "z_1pQ…",
  "expira_en": 900
}

GET /api/v1/auth/sessions
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

{
  "sesiones": [
    {
      "id": 41,
      "creada": "2026-07-31T18:02:11.401Z",
      "expira": "2026-08-30T18:02:11.401Z",
      "usada_en": null,
      "agente": "Mozilla/5.0 (Linux; Android 14)…",
      "ip": "::1"
    }
  ]
}

DELETE /api/v1/auth/sessions/41
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

{ "error": "sesion_no_encontrada" }

DELETE /api/v1/auth/sessions
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

{ "cerradas": 3 }

Usuarios

La gente

Es la parte donde más se nota que la base es compartida: leer está abierto a todo el mundo y devuelve a los usuarios de todos los proyectos, pero los campos reservados piden clave y escribir pide la clave que los creó. Aquí no hay POST: las altas van por /auth/register, donde la contraseña es obligatoria.

GET /api/v1/users?limite=2&perfil=estudiante

{
  "total": 34,
  "limite": 2,
  "desde": 0,
  "usuarios": [
    {
      "id": 7,
      "nombre": "Ana Ruiz",
      "iniciales": "AR",
      "perfil": "estudiante",
      "descuento": 0,
      "activo": true,
      "creado": "2026-07-31T06:31:26.988Z"
    },
    { "id": 9, "nombre": "Luis Pérez", … }
  ]
}

GET /api/v1/users?limite=2&perfil=estudiante
X-API-Key: tk_9fK2xQm…

{
  "total": 34,
  "limite": 2,
  "desde": 0,
  "usuarios": [
    {
      "id": 7,
      "nombre": "Ana Ruiz",
      "iniciales": "AR",
      "perfil": "estudiante",
      "descuento": 0,
      "activo": true,
      "creado": "2026-07-31T06:31:26.988Z",
      "email": "ana@ejemplo.com",        ← nuevo
      "documento": "1.020.334.881",      ← nuevo
      "saldo": 47050,                    ← nuevo
      "actualizado": "2026-07-31T18:02:11.401Z",
      "sin_credenciales": false
    },
    { "id": 9, … }
  ]
}

GET /api/v1/users/me
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

{
  "id": 7, "nombre": "Ana Ruiz", "iniciales": "AR",
  "perfil": "estudiante", "descuento": 0,
  "activo": true, "creado": "2026-07-31T06:31:26.988Z",
  "email": "ana@ejemplo.com",
  "documento": "1.020.334.881",
  "saldo": 47050,
  "actualizado": "2026-07-31T18:02:11.401Z",
  "sin_credenciales": false
}

PUT /api/v1/users/me
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…
Content-Type: application/json

{ "documento": "1020334881" }

{
  "id": 7, "nombre": "Ana Ruiz", …,
  "documento": "1020334881",
  "actualizado": "2026-07-31T19:14:02.115Z"
}

GET /api/v1/users/7

{
  "id": 7,
  "nombre": "Ana Ruiz",
  "iniciales": "AR",
  "perfil": "estudiante",
  "descuento": 0,
  "activo": true,
  "creado": "2026-07-31T06:31:26.988Z"
}

GET /api/v1/users/7
X-API-Key: tk_9fK2xQm…

{
  "id": 7,
  "nombre": "Ana Ruiz",
  "iniciales": "AR",
  "perfil": "estudiante",
  "descuento": 0,
  "activo": true,
  "creado": "2026-07-31T06:31:26.988Z",
  "email": "ana@ejemplo.com",
  "documento": "1.020.334.881",
  "saldo": 47050,
  "actualizado": "2026-07-31T18:02:11.401Z",
  "sin_credenciales": false
}

GET /api/v1/users/7/cards

{
  "tarjetas": [
    {
      "activa": true,
      "creada": "2026-07-31T06:40:02.310Z",
      "usuario": null
    }
  ]
}

GET /api/v1/users/7/cards
X-API-Key: tk_9fK2xQm…

{
  "tarjetas": [
    {
      "uid": "04A1B2C3",     ← nuevo
      "admin": false,        ← nuevo
      "activa": true,
      "creada": "2026-07-31T06:40:02.310Z",
      "usuario": null
    }
  ]
}

PUT /api/v1/users/7
X-API-Key: tk_9fK2xQm…
Content-Type: application/json

{ "perfil": "adulto_mayor",
  "descuento": 100 }

{
  "id": 7, "nombre": "Ana Ruiz", "iniciales": "AR",
  "perfil": "adulto_mayor",
  "descuento": 100,
  "activo": true,
  "creado": "2026-07-31T06:31:26.988Z",
  "email": "ana@ejemplo.com",
  "documento": "1.020.334.881",
  "saldo": 47050,
  "actualizado": "2026-07-31T19:20:44.902Z",
  "sin_credenciales": false
}

DELETE /api/v1/users/7
X-API-Key: tk_9fK2xQm…

(sin cuerpo)

Tarjetas

Las tarjetas NFC

Una tarjeta es una llave, no una cuenta: el saldo vive en el usuario. De ahí salen dos cosas que conviene tener claras antes de escribir nada — una persona puede llevar varias, y perder una no le cuesta el dinero, porque se le vincula otra y el saldo ni se entera.

El uid es lo que suelta el chip: hexadecimal, de 4 a 32 caracteres. Da igual en qué caso lo mandes —en la URL o en el cuerpo—, se guarda y se compara en mayúsculas, así que 04a1b2c3 y 04A1B2C3 son la misma tarjeta.

GET /api/v1/cards?limite=1

{
  "total": 96,
  "limite": 1,
  "desde": 0,
  "tarjetas": [
    {
      "activa": true,
      "creada": "2026-07-31T06:40:02.310Z",
      "usuario": {
        "id": 7,
        "nombre": "Ana Ruiz",
        "iniciales": "AR",
        "perfil": "estudiante",
        "descuento": 0,
        "activo": true,
        "creado": "2026-07-31T06:31:26.988Z"
      }
    }
  ]
}

GET /api/v1/cards?limite=1
X-API-Key: tk_9fK2xQm…

{
  "total": 96,
  "limite": 1,
  "desde": 0,
  "tarjetas": [
    {
      "uid": "04A1B2C3",   ← nuevo
      "admin": false,      ← nuevo
      "activa": true,
      "creada": "2026-07-31T06:40:02.310Z",
      "usuario": {
        "id": 7,
        "nombre": "Ana Ruiz",
        …,
        "email": "ana@ejemplo.com",
        "documento": "1.020.334.881",
        "saldo": 47050,
        "actualizado": "2026-07-31T18:02:11.401Z",
        "sin_credenciales": false
      }
    }
  ]
}

GET /api/v1/cards/04a1b2c3

{
  "activa": true,
  "creada": "2026-07-31T06:40:02.310Z",
  "usuario": {
    "id": 7,
    "nombre": "Ana Ruiz",
    "iniciales": "AR",
    "perfil": "estudiante",
    "descuento": 0,
    "activo": true,
    "creado": "2026-07-31T06:31:26.988Z"
  }
}

GET /api/v1/cards/04a1b2c3
X-API-Key: tk_9fK2xQm…

{
  "uid": "04A1B2C3",
  "admin": false,
  "activa": true,
  "creada": "2026-07-31T06:40:02.310Z",
  "usuario": {
    "id": 7,
    "nombre": "Ana Ruiz",
    …,
    "email": "ana@ejemplo.com",
    "saldo": 47050,
    "sin_credenciales": false
  }
}

POST /api/v1/cards
X-API-Key: tk_9fK2xQm…
Content-Type: application/json

{ "uid": "04A1B2C3",
  "usuario_id": 7 }

{
  "uid": "04A1B2C3",
  "admin": false,
  "activa": true,
  "creada": "2026-07-31T06:40:02.310Z",
  "usuario": {
    "id": 7, "nombre": "Ana Ruiz", …,
    "email": "ana@ejemplo.com",
    "saldo": 47050
  }
}

PATCH /api/v1/cards/04A1B2C3
X-API-Key: tk_9fK2xQm…
Content-Type: application/json

{ "activa": false }

{
  "uid": "04A1B2C3",
  "admin": false,
  "activa": false,
  "creada": "2026-07-31T06:40:02.310Z",
  "usuario": { "id": 7, … }
}

DELETE /api/v1/cards/04A1B2C3
X-API-Key: tk_9fK2xQm…

(sin cuerpo)

Billetera

El saldo y sus movimientos

La API no sabe lo que valen las cosas. Le pasas un número de pesos y lo mueve; cuánto cuesta un pasaje, un café o una entrada es cosa de tu proyecto, y concepto es texto libre para que apuntes qué era. Los montos son enteros: nada de decimales, que en pesos no hacen falta.

Hay dos maneras de mover saldo. Con el token del usuario (/wallet/…), que es la persona autorizándolo ella misma. Y con la clave, sobre un usuario concreto (/users/:id/wallet/…), que es lo que hace un torniquete o una ventanilla, con esa persona delante pero sin sesión iniciada.

Qué es un movimiento

GET /api/v1/wallet
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

{
  "saldo": 47050,
  "moneda": "COP",
  "movimientos": [
    {
      "id": 341,
      "operacion": "cobro",
      "monto": 2950,
      "saldo": 47050,
      "concepto": "Pasaje",
      "uid": null,
      "fecha": "2026-07-31T18:02:11.401Z"
    },
    {
      "id": 338,
      "operacion": "recarga",
      "monto": 50000,
      "saldo": 50000,
      "concepto": "Recarga",
      "uid": null,
      "fecha": "2026-07-31T06:44:55.020Z"
    }
  ]
}

GET /api/v1/wallet/movements?limite=2&desde=20
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

{
  "total": 63,
  "limite": 2,
  "desde": 20,
  "movimientos": [
    {
      "id": 210,
      "operacion": "pasaje",
      "monto": 1500,
      "saldo": 28300,
      "concepto": "Línea 1 · Plaza de Bolívar",
      "uid": "04A1B2C3",
      "fecha": "2026-07-28T13:05:41.882Z"
    },
    { "id": 208, … }
  ]
}

POST /api/v1/wallet/topup
X-API-Key: tk_9fK2xQm…
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…
Content-Type: application/json

{ "monto": 50000,
  "concepto": "Recarga en ventanilla" }

{
  "operacion": "recarga",
  "monto": 50000,
  "saldo": 97050,
  "usuario_id": 7
}

POST /api/v1/wallet/charge
X-API-Key: tk_9fK2xQm…
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…
Content-Type: application/json

{ "monto": 2950, "concepto": "Pasaje" }

{
  "operacion": "cobro",
  "monto": 2950,
  "saldo": 44100,
  "usuario_id": 7
}

// 402 Payment Required
{
  "error": "saldo_insuficiente",
  "saldo": 1200,
  "falta": 1750
}

GET /api/v1/users/7/wallet?limite=1
X-API-Key: tk_9fK2xQm…

{
  "usuario_id": 7,
  "saldo": 47050,
  "moneda": "COP",
  "movimientos": [
    {
      "id": 341,
      "operacion": "cobro",
      "monto": 2950,
      "saldo": 47050,
      "concepto": "Pasaje",
      "uid": null,
      "fecha": "2026-07-31T18:02:11.401Z"
    }
  ]
}

POST /api/v1/users/7/wallet/topup
X-API-Key: tk_9fK2xQm…
Content-Type: application/json

{ "monto": 20000,
  "concepto": "Recarga en ventanilla" }

{
  "operacion": "recarga",
  "monto": 20000,
  "saldo": 67050,
  "usuario_id": 7
}

POST /api/v1/users/7/wallet/charge
X-API-Key: tk_9fK2xQm…
Content-Type: application/json

{ "monto": 1500,
  "concepto": "Pasaje · estudiante" }

{
  "operacion": "cobro",
  "monto": 1500,
  "saldo": 65550,
  "usuario_id": 7
}

Claves · profesor

De dónde salen las claves

Esta parte no es para los proyectos: pide X-Admin-Token, que solo tiene quien administra el servidor. Está documentada porque entender de dónde sale tu clave —y qué puede hacer el profesor con ella— explica media API. Si eres estudiante, lo tuyo es GET /key.

El camino normal no es HTTP sino la máquina donde vive la base:

npm run clave -- "Nombre Apellido"   # crea una y la imprime, una sola vez
npm run clave                        # lista las que hay, con su uso

De la clave solo se guarda su hash. Si un estudiante la pierde no hay forma de recuperarla: se le crea otra y se revoca la anterior. Sin TOKEN_ADMIN en el entorno del servidor, todo lo de abajo responde 401 a todo el mundo, también desde localhost.

POST /api/v1/keys
X-Admin-Token: …
Content-Type: application/json

{ "estudiante": "Ana Ruiz",
  "limite_usuarios": 200 }

{
  "id": 4,
  "clave": "tk_9fK2xQm7vN3pR8sT1uW5yZ0aB2cD4eF",
  "prefijo": "tk_9fK2xQm",
  "estudiante": "Ana Ruiz",
  "limite_usuarios": 200,
  "aviso": "Guárdala: no se puede volver a consultar."
}

GET /api/v1/keys
X-Admin-Token: …

{
  "claves": [
    {
      "id": 4,
      "prefijo": "tk_9fK2xQm",
      "estudiante": "Ana Ruiz",
      "activa": true,
      "sistema": false,
      "limite_usuarios": 200,
      "usuarios": 14,
      "creada": "2026-07-20T15:02:00.000Z",
      "revocada": null
    }
  ]
}

DELETE /api/v1/keys/4
X-Admin-Token: …

{ "revocada": true, "purgada": false }

DELETE /api/v1/keys/4?purgar=true
X-Admin-Token: …

{
  "revocada": true,
  "purgada": true,
  "borrado": {
    "movimientos": 812,
    "tarjetas": 31,
    "sesiones": 44,
    "usuarios": 26
  }
}

Lo que el token de administrador se salta

Además de estas tres rutas, X-Admin-Token sirve como comodín en toda la API: pasa por donde se pide clave, se salta la regla de propiedad —edita o borra usuarios y tarjetas de cualquiera— y es el único que ve las tarjetas de administrador, en la lista y por uid. Por eso no se reparte: no es una clave más con más cuota, es la que no tiene reglas.

Errores

Todos los códigos, en una tabla

Lo que devuelve la API cuando algo va mal, junto. Los de arriba pueden salir en cualquier ruta; los de abajo, solo donde dice su ficha.

Qué significa cada código HTTP

Los que pueden salir en cualquier ruta

Los 404 tienen dos redacciones y no es descuido: usuario_no_encontrado y tarjeta_no_registrada salen de las rutas de lectura, mientras que las que exigen ser dueño responden el genérico no_encontrado. Si contestaran distinto según de quién sea la fila, ese 404 pasaría a ser una forma de averiguar qué existe.

Recetas

Tres flujos enteros

Endpoints sueltos ya están arriba. Esto es cómo se encadenan en lo que de verdad monta la gente.

1 · De cero a un saldo que se mueve

Para probar que tu clave funciona y dejar un usuario con saldo con el que trastear. En la terminal:

API=https://nfc.multimediaudeb.com/api/v1
CLAVE=tk_…    # la tuya

# 1. Registrar a alguien
RESP=$(curl -s -X POST $API/auth/register \
  -H "X-API-Key: $CLAVE" -H 'Content-Type: application/json' \
  -d '{"email":"ana@ejemplo.com","contrasena":"tunja2026","nombre":"Ana Ruiz","perfil":"estudiante"}')

ACCESO=$(echo "$RESP" | jq -r .acceso)
ID=$(echo "$RESP" | jq -r .usuario.id)

# 2. Recargarle la billetera
curl -s -X POST $API/wallet/topup \
  -H "X-API-Key: $CLAVE" -H "Authorization: Bearer $ACCESO" \
  -H 'Content-Type: application/json' -d '{"monto":50000,"concepto":"Recarga"}'

# 3. Darle una tarjeta
curl -s -X POST $API/cards \
  -H "X-API-Key: $CLAVE" -H 'Content-Type: application/json' \
  -d "{\"uid\":\"04A1B2C3\",\"usuario_id\":$ID}"

# 4. Cobrarle algo (el precio lo pones tú)
curl -s -X POST $API/wallet/charge \
  -H "X-API-Key: $CLAVE" -H "Authorization: Bearer $ACCESO" \
  -H 'Content-Type: application/json' -d '{"monto":2950,"concepto":"Pasaje"}'

# 5. Ver cómo quedó
curl -s $API/wallet -H "Authorization: Bearer $ACCESO"

Lo mismo como script de Node, para dejarlo en el repositorio y repetirlo:

// sembrar.js — node --env-file=.env sembrar.js
import { tunja } from "./api.js";

const { usuario, acceso } = await tunja("/auth/register", {
  metodo: "POST",
  cuerpo: {
    email: `prueba${Date.now()}@ejemplo.com`,   // único en cada corrida
    contrasena: "tunja2026",
    nombre: "Ana Ruiz",
    perfil: "estudiante",
  },
});

await tunja("/wallet/topup", {
  metodo: "POST",
  token: acceso,
  cuerpo: { monto: 50000, concepto: "Recarga inicial" },
});

await tunja("/cards", {
  metodo: "POST",
  cuerpo: { uid: "04A1B2C3", usuario_id: usuario.id },
});

const billetera = await tunja("/wallet", { token: acceso });
console.log(`Usuario ${usuario.id} listo con ${billetera.saldo} ${billetera.moneda}`);

El email tiene que ser distinto en cada corrida: la base es única y compartida, así que ana@ejemplo.com lo cogió alguien hace tres semanas. Un Date.now() dentro del email evita el 409 email_en_uso eterno. Y borra tus usuarios de prueba cuando termines: la cuota son 200.

2 · Leer la tarjeta en el celular y cobrar

La otra mitad del torniquete —el servidor está más arriba—: un teléfono Android con Chrome lee el uid por Web NFC y se lo manda a tu Express. No hace falta lector USB ni aplicación: el carné estudiantil suelta su uid tal cual.

// En el navegador. Web NFC solo existe en Chrome sobre Android y pide HTTPS.
const boton = document.getElementById("activar");

boton.addEventListener("click", async () => {
  if (!("NDEFReader" in window)) return alert("Este navegador no lee NFC");

  const lector = new NDEFReader();
  await lector.scan();          // pide permiso: tiene que salir de un clic

  lector.addEventListener("reading", async ({ serialNumber }) => {
    // Android lo entrega como "04:1a:2b:3c" y la API lo quiere en hex plano.
    const uid = (serialNumber ?? "").replace(/[^0-9a-fA-F]/g, "").toUpperCase();
    if (uid.length < 4) return;

    // A TU servidor, que es el que tiene la clave.
    const res = await fetch("/pasar", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ uid }),
    });

    const veredicto = await res.json();
    pintar(veredicto);          // { paso: true, monto: 1500, saldo: 45550 }
  });
});

Mientras no tengas tarjetas a mano, tu Express puede recibir el uid de un <input> escrito a mano: 04A1B2C3 vale igual que uno leído. El NFC es la última pieza que hay que enchufar, no la primera.

3 · Un cliente que refresca solo

El acceso dura 15 minutos, así que cualquier sesión que dure más de eso necesita esto. La regla: un 401, un refresco, un reintento — y si el refresco tampoco vale, al login.

const API = "https://nfc.multimediaudeb.com/api/v1";

let acceso = localStorage.getItem("acceso");
let refresco = localStorage.getItem("refresco");

function guardar(par) {
  acceso = par.acceso;
  refresco = par.refresco;              // el anterior ya no vale: se pisa
  localStorage.setItem("acceso", acceso);
  localStorage.setItem("refresco", refresco);
}

async function llamar(camino, opciones = {}, reintento = true) {
  const respuesta = await fetch(API + camino, {
    ...opciones,
    headers: {
      "Content-Type": "application/json",
      ...(acceso && { Authorization: `Bearer ${acceso}` }),
      ...opciones.headers,
    },
  });

  if (respuesta.status === 401 && reintento && refresco) {
    const nueva = await fetch(`${API}/auth/refresh`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ refresco }),
    });

    if (!nueva.ok) {          // el refresco tampoco vale: a iniciar sesión otra vez
      localStorage.clear();
      throw new Error("sesion_caducada");
    }

    guardar(await nueva.json());
    return llamar(camino, opciones, false);
  }

  return respuesta.json();
}

Fíjate en que la clave no aparece: este código corre en el navegador, y ahí no se escribe un secreto. El login y las lecturas van directas a la API —el CORS está abierto para eso—; lo que pide clave pasa por tu Express, que es el único sitio donde el secreto está a salvo. Es una API de laboratorio y nadie va a perder dinero de verdad, pero conviene saber cuál de las dos cosas estás haciendo.