API Avisos Push — Notificaciones a la aplicación móvil (1.0)

Download OpenAPI specification:Download

INTRODUCCION

Envío de avisos push al móvil de sus usuarios a través de nuestra aplicación gratuita. Pensado para lo que no puede esperar: una alarma, una incidencia crítica, una autorización que hay que dar ahora.



A diferencia de un SMS o un email, el aviso puede sonar con el teléfono en reposo y, si lo marca como crítico, incluso con el modo No molestar activado. Y usted sabe si llegó, si lo abrieron y si lo aceptaron.

A QUIEN SE ENVIA: DISPOSITIVOS Y ALIAS

Los dispositivos se vinculan desde su panel (sección Avisos), no por API: ahí genera los códigos de vinculación —para usted o para cualquiera de sus autorizados, incluidos empleados que nunca entran al panel: les hace llegar el código y solo necesitan la aplicación—, ve todos los aparatos de su cuenta y puede revocarlos.



A cada dispositivo puede ponerle un alias (almacen-1, guardia-noche…): ese alias es el parámetro REF de EnviarPush. Sin REF, el aviso va a todos los dispositivos de la cuenta.



Además, sus envíos llevan un código de aplicación (parámetro APLICACION: alerta, aviso… el que usted invente). Cada aplicación aparece automáticamente en el panel como una fuente más, y el dueño de cada dispositivo elige qué fuentes recibe cada aparato: la aplicación alerta en el móvil 1 y 3, la aviso en el 1 y el 2… No hay que registrar las aplicaciones: la primera vez que envía con una, existe.

PUESTA EN MARCHA


1. En su panel, sección Avisos, genere un código de vinculación (para usted o para un autorizado).
2. La persona instala la aplicación de avisos y escribe ese código.
3. Póngale al dispositivo un alias en la lista del panel (opcional: sin alias también recibe los envíos a toda la cuenta).
4. Ya puede enviarle avisos con EnviarPush, con REF=alias para un aparato concreto o sin REF para todos.



En la aplicación no se escribe ninguna contraseña. El código dura unos minutos, sirve una sola vez y generar uno nuevo anula el anterior. No hay credenciales de sus usuarios que usted tenga que custodiar.

NIVELES DE ALERTA

Cada nivel es un canal de notificación distinto en el móvil, así que el destinatario puede silenciar los informativos y dejar sonando los críticos sin desactivar la aplicación entera.

NivelComportamiento en el móvil
CRITICOSuena aunque el volumen esté bajo y se salta el modo No molestar, si el destinatario le ha dado ese permiso a la aplicación. Resérvelo para lo que de verdad no puede esperar: si todo es crítico, nada lo es.
ALTOCon sonido y vibración, por el volumen de notificaciones.
NORMALCon el sonido habitual del teléfono. Es el valor por defecto.
BAJOSin sonido. Se queda en la barra de notificaciones.

ESTADOS

Cada aviso pasa por hasta cuatro estados. Los tres últimos se le envían a su servidor en cuanto ocurren (ver Recepción de cambios de estado):

EstadoQué significa exactamente
ENVIADOEl servicio de push lo aceptó en su cola. No dice nada sobre el móvil.
ENTREGADOLa aplicación confirma que lo ha mostrado. Esto sí depende del teléfono, y es la diferencia real entre «lo mandamos» y «apareció en su pantalla».
ABIERTOEl destinatario lo ha pulsado.
CONFIRMADOHa pulsado Aceptar. Sólo si lo pidió con CONFIRMAR=1.


No existe un estado «leído», y no es un olvido: una notificación se lee en la pantalla de bloqueo sin llegar a tocarla, y no hay forma técnica de saberlo. Llamar «leído» a «entregado» sería engañarle en un dato que usted va a usar para decidir si vuelve a avisar a alguien.



Los estados los marca el móvil del destinatario, no nosotros, así que llegan cuando esa persona coge el teléfono. Por eso se le envían en cuanto ocurren a un script de su servidor, igual que en el resto de nuestras APIs: actívelo en su panel y su sistema se entera al momento sin hacer una sola petición.

PRECIO

Se cobra por destinatario avisado, no por dispositivo: si esa persona tiene el móvil y la tableta vinculados, recibe un aviso en los dos y usted paga uno.



Generar códigos, recibir los cambios de estado y gestionar dispositivos no cuesta créditos.

AUTENTICACION

Igual que el resto de nuestras APIs: autenticación Basic con su usuario y su API Token, que encontrará en su panel en Sus datos → Configurar → Seguridad. Recuerde autorizar ahí también la IP pública desde la que llamará.

Enviar aviso

/EnviarPush

Envía un aviso push. Con REF va a los dispositivos con ese alias; sin REF, a todos los de su cuenta que tengan la aplicación activada. Si no hay ningún destinatario se devuelve -6 y no se cobra nada: vincule el dispositivo desde su panel (sección Avisos) y póngale el alias ahí.

Authorizations:
basicAuth
query Parameters
Ref
required
string
Example: Ref=usuario-4471

Alias del dispositivo destino, tal y como lo puso en su panel (lista de dispositivos de la sección Avisos). Opcional: sin él, el aviso va a todos los dispositivos de la cuenta. Máximo 64 caracteres.

Titulo
required
string
Example: Titulo=Alarma en la nave 2

Título del aviso. Es lo que se lee en la notificación, así que conviene que se entienda solo. Máximo 120 caracteres.

Mensaje
string
Example: Mensaje=Sensor de temperatura por encima de 45 grados desde las 03:12.

Texto del aviso. Máximo 300 caracteres. Texto plano: va a la barra de notificaciones del móvil, no admite HTML.

Nivel
string
Enum: "CRITICO" "ALTO" "NORMAL" "BAJO"
Example: Nivel=CRITICO

Nivel de alerta.
CRITICO - Suena aunque el volumen esté bajo y se salta el No molestar.
ALTO - Con sonido y vibración.
NORMAL - Sonido habitual del teléfono.
BAJO - Sin sonido.

Confirmar
string
Enum: 0 1
Example: Confirmar=1

Indique 1 si quiere que el aviso lleve un botón Aceptar y quede registrado quién lo pulsa y cuándo. El destinatario puede aceptarlo desde la propia notificación, sin abrir la aplicación.

Referenciausuario
string
Example: Referenciausuario=INC-99213

Referencia libre suya para cruzar el aviso con su sistema (un número de incidencia, de pedido…). Vuelve en cada report de cambio de estado, y le permite cruzarlo con su sistema sin guardar nuestro idAviso. Máximo 50 caracteres.

Aplicacion
string
Example: Aplicacion=alerta

Código de aplicación con el que agrupa sus avisos (alerta, aviso… minúsculas, números y guiones, máximo 20). No hay que registrarlo: la primera vez que envía con uno, aparece en el panel del destinatario como una fuente que puede activar o desactivar en cada dispositivo. Si no lo indica, se usa api.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Ref
required
string
Titulo
required
string
Mensaje
string
Nivel
string
Confirmar
string
Referenciausuario
string
Aplicacion
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Resultado de la llamada
>0 Número de destinatarios avisados.
-1 Error de autenticación o IP no autorizada.
-2 No dispone de créditos suficientes.
-3 Error en los parámetros. Obtendrá el detalle en Error.
-6 Ningún dispositivo con ese alias (o ninguno con esta aplicación activada). No se ha cobrado nada.

idAviso
integer

Identificador del aviso. Guárdelo: es el que viaja en cada report de cambio de estado, para que pueda relacionarlo con el envío.

Cred
number

Créditos que le quedan tras el envío.

Error
string

Descripción del problema cuando Res es negativo.

Request samples

Content type
{
  • "Ref": "usuario-4471",
  • "Titulo": "Alarma en la nave 2",
  • "Mensaje": "Sensor de temperatura por encima de 45 grados desde las 03:12.",
  • "Nivel": "CRITICO",
  • "Confirmar": "1",
  • "Referenciausuario": "INC-99213",
  • "Aplicacion": "alerta",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]

Recepción de cambios de estado

https://{SuDominio}/path/de/su/script/de/recepción/de/reports

RECEPCIÓN EN TIEMPO REAL DE LOS CAMBIOS DE ESTADO EN UN SCRIPT DE SU SERVIDOR.

Active en su panel de usuario la opción de recibir los reports en un script de su servidor y le enviaremos una petición POST cada vez que uno de sus avisos cambie de estado: cuando se entrega, cuando se abre y cuando se confirma.



Es la forma recomendada de seguir sus avisos. Los estados no los marcamos nosotros sino el móvil del destinatario, así que consultarlos en bucle no adelanta nada: llegan cuando esa persona coge el teléfono. Con el report, su sistema se entera en el momento y sin hacer una sola petición.



Se envía un POST por cada cambio, no uno con el estado final: si un aviso se entrega y se abre casi a la vez, recibirá los dos, y así conserva las marcas de tiempo de cada paso. Si su servidor no responde se reintenta en las siguientes pasadas; tras varios intentos fallidos se abandona ese aviso, de modo que un servidor caído no le atasca la cola de los demás.



Responda 2xx. Es el mismo script y el mismo formato que usa para los reports de SMS, Email o RCS: distinga por el campo Servicio, que aquí vale PUSH.

Authorizations:
basicAuth
Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Tipo de report que está recibiendo, para distinguirlo de los de otros servicios en el mismo script.

PUSH Cambio de estado de un aviso push

Resultado
required
string

Nuevo estado del aviso.

ESTADOSIGNIFICADO
`ENTREGADO`La aplicación confirma que ha mostrado el aviso en la pantalla del destinatario.
`ABIERTO`El destinatario lo ha pulsado.
`CONFIRMADO`Ha pulsado Aceptar. Sólo en los avisos enviados con CONFIRMAR=1.
idAviso
required
integer

Identificador del aviso, el mismo que devolvió EnviarPush.

Ref
required
string

Referencia del destinatario en su sistema.

Referencia
string

La REFERENCIAUSUARIO que indicó al enviar, para cruzarlo con su sistema sin guardar nuestro idAviso.

Titulo
string

Título del aviso, para identificarlo en su log sin consultar nada.

Nivel
string

Nivel con el que se envió: CRITICO, ALTO, NORMAL o BAJO.

Fecha
required
string

Momento en que se produjo ESTE cambio de estado (hora peninsular española).

FechaEnvio
string

Momento en que se envió el aviso. La diferencia con Fecha es lo que tardó el móvil en reaccionar.

Dispositivos
integer

Número de dispositivos a los que salió el aviso.

Request samples

Content type
{
  • "Servicio": "PUSH",
  • "Resultado": "ENTREGADO",
  • "idAviso": "84213",
  • "Ref": "usuario-4471",
  • "Referencia": "INC-99213",
  • "Titulo": "Alarma en la nave 2",
  • "Nivel": "CRITICO",
  • "Fecha": "2026-08-05 03:14:06",
  • "FechaEnvio": "2026-08-05 03:14:02",
  • "Dispositivos": "2"
}

Dispositivos

/DispositivosPush

Consulta los dispositivos de su cuenta (todos, o los de un alias concreto con REF), o desvincula los de un alias. Útil para saber si alguien puede recibir avisos antes de enviárselos, y para dar de baja a quien deja de trabajar con usted. La BAJA exige REF: desvincular toda la cuenta de una llamada sería demasiado fácil de hacer sin querer. No cuesta créditos.

Authorizations:
basicAuth
query Parameters
Ref
required
string
Example: Ref=usuario-4471

Identificador del usuario en SU sistema.

Accion
string
Enum: "CONSULTAR" "BAJA"
Example: Accion=CONSULTAR

Qué hacer.
CONSULTAR - Devuelve los dispositivos vinculados.
BAJA - Desvincula los dispositivos de esa REF (obligatoria). Dejarán de recibir avisos de inmediato.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Ref
required
string
Accion
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Resultado de la llamada
>=0 Número de dispositivos devueltos (CONSULTAR) o desvinculados (BAJA). Un 0 en CONSULTAR significa que esa persona aún no ha vinculado ningún móvil.
-1 Error de autenticación o IP no autorizada.
-3 Error en los parámetros.

Dispositivos
Array of arrays

Dispositivos vinculados. RetrasoSeg es lo que tardó el último aviso en aparecer de verdad en la pantalla desde que salió: un retraso alto delata un teléfono con el ahorro de energía apretado, y es el dato que explica por qué a esa persona los avisos le llegan tarde.

Desvinculados
integer

Dispositivos dados de baja, cuando ACCION es BAJA.

Request samples

Content type
{
  • "Ref": "usuario-4471",
  • "Accion": "CONSULTAR",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]