Manual de API

Guía práctica para integrar Push PalMath con scripts, tareas automáticas, servicios web y sistemas externos usando HTTP sobre https://push.palmath.net/api/v1, con un enfoque simple, directo y listo para producción.

Base

Conceptos clave

La API se apoya en dos modelos de acceso distintos:

Clave API por tenant para integraciones que envían alertas.
JWT + refresh token para aplicaciones móviles y sesiones autenticadas de usuario.

Severidades admitidas:

Normal: información visible en histórico, sin ruido innecesario.
High: incidencia operativa que debe llegar destacada.
Critical: problema de ejecución o situación de máxima prioridad.

Buenas prácticas recomendadas:

Usar títulos cortos y muy descriptivos.
Reservar el cuerpo para contexto técnico útil.
Identificar el origen del evento en el campo source.
No reutilizar claves API entre espacios o entornos distintos.

Endpoint principal

POST /push/send

Envía un mensaje a un usuario del tenant asociado a la API key.

URL completa: https://push.palmath.net/api/v1/push/send

Body JSON esperado:

{
  "apiKey": "TU_API_KEY",
  "email": "usuario@dominio.com",
  "severity": "High",
  "source": "Tarea Automática",
  "title": "Placas solares - Sin generación",
  "body": "No se alcanza el umbral esperado de producción en horario solar."
}

Ejemplo con PowerShell:

$body = @{
  apiKey = "TU_API_KEY"
  email = "usuario@dominio.com"
  severity = "Critical"
  source = "Monitor Externo"
  title = "Servidor - Error de ejecución"
  body = "No se pudo completar la comprobación programada."
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://push.palmath.net/api/v1/push/send" `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

Sesiones de usuario

Registro, login y refresh

Endpoints disponibles:

POST /auth/register
POST /auth/verify-email
POST /auth/login
POST /auth/refresh
POST /auth/resend-verification

Tras el login correcto, la API devuelve:

accessToken
refreshToken
expiresAtUtc

Para llamadas autenticadas, añade el encabezado:

Authorization: Bearer TU_ACCESS_TOKEN

La app móvil usa este flujo para:

consultar mensajes
registrar el dispositivo para notificaciones
ocultar mensajes en la vista del usuario
generar una API key móvil cuando corresponde

Operaciones autenticadas

Mensajes y dispositivos

Endpoints disponibles:

GET /messages
GET /messages/{id}
POST /messages/{id}/read
DELETE /messages/{id}
POST /devices/register
POST /account/mobile-api-key
POST /account/delete-request

Uso típico:

registrar el token push del dispositivo tras el login
recuperar el listado de mensajes del usuario
marcar lectura o eliminar mensajes en la vista móvil
pedir una API key móvil para copiarla desde la app