Kuska IoT
Volver a documentación

Uso de la API REST

La API permite autenticar usuarios, administrar proyectos y dispositivos, consultar mensajes MQTT almacenados, revisar uso del plan y conectar el flujo de billing con PayPal.

Base URL

Usa la URL según el entorno donde esté corriendo Nuxt.

Desarrollo: http://127.0.0.1:3002
Docker:     http://localhost:3000
Producción: https://tu-dominio.com

Autenticación

Inicia sesión para obtener un JWT. En las peticiones protegidas envía ese valor en Authorization: Bearer. 

curl -X POST http://127.0.0.1:3002/api/auth/login \
  -H "content-type: application/json" \
  -d '{"email":"usuario@example.com","password":"tu-password"}'
{
  "token": "eyJ..."
}
Authorization: Bearer TU_TOKEN

Tokens API generados por admin

Un administrador puede crear tokens desde /admin/users. Esos tokens son JWT de larga duración y se usan igual que el token de login. 

curl http://127.0.0.1:3002/api/messages \
  -H "Authorization: Bearer TOKEN_GENERADO"

Cuenta

POST

Registrar usuario

Crea una cuenta con plan Free por defecto.

/api/auth/register

Body

{"name":"Ada Maker","email":"ada@example.com","password":"tu-password"}
GET

Cuenta actual

Devuelve el usuario autenticado sin passwordHash.

/api/auth/me

cURL

curl http://127.0.0.1:3002/api/auth/me \
  -H "Authorization: Bearer TU_TOKEN"
PATCH

Actualizar perfil

Actualiza nombre y email de la cuenta autenticada.

/api/auth/profile

Body

{"name":"Ada Lovelace","email":"ada@kuska.dev"}

cURL

curl -X PATCH http://127.0.0.1:3002/api/auth/profile \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"Ada Lovelace","email":"ada@kuska.dev"}'

Proyectos

GET

Listar proyectos

/api/projects

cURL

curl http://127.0.0.1:3002/api/projects \
  -H "Authorization: Bearer TU_TOKEN"
POST

Crear proyecto

Genera automáticamente el slug y el topic raíz MQTT del proyecto.

/api/projects

Body

{"name":"Planta piloto","description":"Sensores ESP32"}

cURL

curl -X POST http://127.0.0.1:3002/api/projects \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"Planta piloto","description":"Sensores ESP32"}'
GET

Consultar proyecto

/api/projects/{id}
PATCH

Actualizar proyecto

/api/projects/{id}

Body

{"name":"Planta piloto 2","description":"Nueva descripción"}
DELETE

Eliminar proyecto

Elimina el proyecto y sus dispositivos asociados.

/api/projects/{id}

Dispositivos

POST

Crear dispositivo

La respuesta incluye la contraseña MQTT una sola vez. Respeta el límite de dispositivos del plan.

/api/projects/{projectId}/devices

Body

{"name":"ESP32 Sala 1"}

cURL

curl -X POST http://127.0.0.1:3002/api/projects/PROJECT_ID/devices \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"ESP32 Sala 1"}'
GET

Listar dispositivos

/api/devices | /api/devices?projectId=PROJECT_ID | /api/projects/{projectId}/devices

cURL

curl "http://127.0.0.1:3002/api/devices?projectId=PROJECT_ID" \
  -H "Authorization: Bearer TU_TOKEN"
GET

Consultar dispositivo

/api/devices/{id}
PATCH

Actualizar dispositivo

Permite cambiar nombre y estado manual.

/api/devices/{id}

Body

{"name":"ESP32 Oficina","status":"online"}
DELETE

Eliminar dispositivo

/api/devices/{id}

Mensajes MQTT

Devuelve hasta 50 mensajes recientes del usuario autenticado. La consulta respeta la retención del plan: Free 7 días, Starter 90 días, Pro 365 días, Business 730 días y Enterprise sin límite configurado. 

GET /api/messages
GET /api/messages?projectId=PROJECT_ID
GET /api/messages?projectId=PROJECT_ID&deviceId=DEVICE_ID
curl "http://127.0.0.1:3002/api/messages?projectId=PROJECT_ID&deviceId=DEVICE_ID" \
  -H "Authorization: Bearer TU_TOKEN"

Plan, uso y billing

GET

Uso del plan

Devuelve límites, uso del ciclo actual, porcentajes y flags para saber si puede crear dispositivos o guardar mensajes.

/api/billing/usage

Respuesta ejemplo

{
  "plan": { "id": "pro", "name": "Pro", "maxDevices": 100, "maxMessagesMonthly": 25000000 },
  "usage": { "devices": 12, "messagesThisMonth": 5300 },
  "allowed": { "createDevice": true, "storeMessage": true }
}

cURL

curl http://127.0.0.1:3002/api/billing/usage \
  -H "Authorization: Bearer TU_TOKEN"
GET

Suscripción actual

Devuelve el plan efectivo del usuario y, si existe, la suscripción local vinculada a PayPal.

/api/billing/subscription

cURL

curl http://127.0.0.1:3002/api/billing/subscription \
  -H "Authorization: Bearer TU_TOKEN"
POST

Crear checkout PayPal

Crea una suscripción PayPal para un plan pago y devuelve approvalUrl. Requiere PAYPAL_*_PLAN_ID reales en el entorno.

/api/billing/paypal/create-subscription

Body

{"plan":"pro","interval":"month"}

Respuesta ejemplo

{
  "provider": "paypal",
  "subscriptionId": "I-...",
  "status": "APPROVAL_PENDING",
  "approvalUrl": "https://www.sandbox.paypal.com/..."
}
POST

Webhook PayPal

Endpoint público para PayPal. Verifica la firma con PAYPAL_WEBHOOK_ID, guarda eventos idempotentes y actualiza users.plan cuando la suscripción se activa, suspende, cancela o expira.

/api/billing/paypal/webhook

Ejemplo con JavaScript

const token = 'TU_TOKEN'

const messages = await fetch('http://127.0.0.1:3002/api/messages?projectId=PROJECT_ID', {
  headers: {
    Authorization: `Bearer ${token}`
  }
}).then((response) => response.json())

console.log(messages)

Endpoints admin

Requieren usuario con rol admin. Se usan desde el dashboard admin, no desde dispositivos. 

GET  /api/admin/stats
GET  /api/admin/users
PATCH /api/admin/users/{id}/plan
GET  /api/admin/tokens?userId=USER_ID
POST /api/admin/tokens
POST /api/admin/bootstrap

Notas de seguridad

  • No compartas tokens en repositorios, firmware público o capturas.
  • Los endpoints filtran datos por el usuario autenticado.
  • Los tokens generados desde admin deben tratarse como credenciales de producción.
  • Para producción, usa HTTPS y rota tokens comprometidos.
  • El plan efectivo se actualiza por webhook verificado de PayPal o por acción admin.
  • Los IDs PayPal de sandbox no funcionan en live y viceversa.