ZPK SMS

Conexión a la API

Servidor:	https://zpk.systems
Esquema:	HTTPS, solo conexiones seguras SSL.
Protocolo:	JSON recomendado Enviando un JSON en el body del request, y especificando una cabecera Content-Type: application/json en el request Si envia ficheros como imágenes o documentos, estos deberán estar codificados en base64. Form-Data no recomendado Formato usado en los formularios web, no recomendado. Al enviar una solicitud tipo form_data puede enviar todos los campos como parámetros POST separados. Sin embargo si la solicitud es muy grande recomendamos que envie el contenido de la peticion en un único campo de texto llamado _json (con un guión bajo). Este parametro especial sera procesado por nuestro backend como si se tratase de una solicitud JSON habitual.

POST /api/sms/send

Parámetro	Descripción
application_id	alfanumérico requerido Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación
messages	array requerido Max: 1000 Un array que contiene uno o mas mensajes SMS a enviar. Estructura de messages Prámetro Descripción from alfanumérico requerido El nombre de remitente, aparecerá como origen del sms en el dispositivo de destino. La longitud máxima es de 15 caracteres, y los caracteres no-ascii que puedan ser sustítuidos se sustituirán a su caracter ascii. Por ejemplo á » a phone alfanumérico teléfono válido requerido Un número de teléfono de destino, este debe traer incluido el prefijo internacional Algunos caracteres como espacios y retornos de línea, guiones de separación... serán eliminados directamente por la API. message alfanumérico requerido El cuerpo del mensaje, con una longitud máxima de 160 caracteres, o de 496 caracteres si se activó la concatenación de SMS. La longitud puede ser inferior a 160 caracteres si se usa un encoding diferente a GSM7, que es el encoding por defecto. send_at afanúmerico fecha opcional Una fecha en formato YYYY-MM-DD HH:MM:SS, como por ejemplo 2023-04-02 12:30:40 Si establece una fecha en el futuro el el envío se pospondrá a esa fecha, permitiendo programar la fecha de entrega del SMS. Fechas y zona horaria Tenga en cuenta que todas las fechas deben enviarse en horario UTC (tiempo universal coordinado). La fecha actual UTC es: 11/12/2024 19:18:29 reference alfanumérico opcional Una referencia que será devuelta por la API en la respuesta. Puede usar esta para gestionar que SMS se enviaron correctamente y cuales no.
concatenate	boleano opcional Por defecto false. Si se establece los mensajes que superen la longitud de texto máxima se enviarán como varios SMS concatenados.
encoding	alfanumérico opcional La codificación de caracteres del SMS. Por defecto se usará GSM7 , que permite un envío de 160 caracteres sin acentos ni caracteres especiales como emojis. La otra opción disponible es UCS2, que disminuirá la longitud máxima de sms a 70 caracteres pero permite enviar caracteres especiales.
callback_url	alfanumérico URL opcional Una URL de notificación, donde ZPK Systems informará del estado de entrega de los SMS La URL de notificacion recibe una lista de hasta 1000 envíos, su servidor deberá responder con un código de respuesta 200. Si su servidor no responde con un código 200 por problemas técnicos, nuestros servidores volverán a intentar notificar esta comunicación cada 30 minutos, durante un máximo de 72 horas.

El servidor retornará un JSON, con un boleano success si la solicitud de envío se procesó correctamente.

Adicionalmente en el JSON se retornará la lista de los SMS enviados, con un parámetro success indicando si ese mensaje en concreto pudo ser entregado o no.

Cada mensaje dispone además de un código sms_id que identifica ese SMS en concreto. Este código es usado posteriormente en los envíos de informes de estado.

Como en el resto de las peticiones a APIS de ZPK Systems, se dispone un parámetro cost indicando el coste total de la solicitud a la API.

Ejemplo de respuesta con envío correcto.

{
   "success": true,
   "messages": [
      {
         "from": "El sitio web",
         "phone": "+34 000000",
         "message": "El mensaje enviado",
         "success": true,
         "sms_id": "f205d6e838ec4110992a4a871a74d279"
      }
   ],
   "cost": 0.02485
}
				

Ejemplo de respuesta con algunos mensajes incorrectos.

Ejemplo con un envío correcto, que sin embargo contenía un número de destino incorrecto.

{
   "success": true,
   "messages": [
      {
         "from": "El sitio web",
         "phone": "+34 000000",
         "message": "El mensaje enviado",
         "success": true,
         "sms_id": "f205d6e838ec4110992a4a871a74d279"
      },
      {
         "from": "YourName",
         "phone": "+34 NotValidPhone :)",
         "message": "El mensaje a enviar...",
         "success": false,
         "sms_id": "",
         "error_id": "INVALID_DESTINATION",
         "error_msg": "SMS parameter 'to' must be a number in international format, between 7 and 15 digits."
      }
   ],
   "cost": 0.02485
}
				

Ejemplo de respuesta con error general

Ejemplo con un envío incorrecto que NO será procesado.

{
   "success": false,
   "errors": [
      {
         "id": "INVALID_PARAMETER",
         "message": "Messages array is empty.",
		 "on": "messages"
      }
	]
}
				

Los precios de envío de un SMS pueden ser consultados en este endpoint.

Podemos opcionalmente filtrar los precios por código ISO2 de país, o por extensión de teléfono.

Endpoint de consulta

GET /api/sms/pricing

Parámetro	Descripción
application_id	alfanumérico requerido Una ID de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación
country_code	alfanumérico opcional Si se facilita este parámetro opcional, se retornaran solo las tarifas cuyo país de destino coincida. Debe ser un código ISO2, por ejemplo es para España, o us para Estados Unidos.
prefix	alfanumérico opcional Si se facilita este parametro opcional, se retornarán solo las tarifas cuyo prefijo internacional coincida.

Respuesta

{
   "success": true,
   "prices": [
      {
         "country_code": "AB",
         "prefix": "7",
         "network_name": "Other",
         "price": 0.0652
      },
      {
         "country_code": "AB",
         "prefix": "7",
         "network_name": "Aquafon",
         "price": 0.0652
      },
      {
         "mas tarifas": "...."
      }
	],
   "cost": 0.02485

}

Solicitando notificación

Si al hacer una solicitud de envío se establece el parámetro callback_url ZPK notificará a su servidor el estado del envío de SMS cuando tenga una respuesta del operador.

Esta respuesta puede tardar entre unos pocos segundos, y hasta 48 horas, dependiendo del operador de destino.

El envío se realiza mediante una comunicación JSON.

{
	"application_id": "app234234",
	"api_key": "DSFJnn3JLdfdfs",
	"callback_url": "https://miservidor.com/zpk_sms_callback",
	"messages":[
		{
			"from": "TEST",
			"phone": "600568046",
			"message": "Test de envío con callback"
		}
	]
}

Recibiendo notificaciones

Cuando el SMS sea entregado o rechazado por el operador, ZPK enviará una notificación JSON a su servidor con un array de resultados de envío.

[
	{
		"sms_id":"537b7194d5804ad9b1afead36f3d5e16",
		"from":"YourName",
		"phone":"+34600000000",
		"message":"El mensaje a enviar...",
		"generated_at":"2023-07-16 06:59:49",
		"status":"delivered",
		"delivered_at":"2023-07-16 06:59:59"
	}
]

Posibles valores en status

sms_id	Un identificador único del SMS envíado
from	El origen que usted especificó al solicitar el envío.
phone	El número de teléfono del destinatario
message	El mensaje que solicitó enviar
generated_at	La fecha en que se solicitó el envío
status	El estado actual del mensaje, que puede ser: not_sent El mensaje no fue enviado aún por motivos desconocidos delivered El mensaje fue entregado al dispositivo destino accepted El mensaje fue aceptado por el operador, y debería ser entregado próximamente. expired El mensaje expiró sin haber podido ser entregado. deleted El mensaje fue eliminado por el operador por motivos desconocidos. undelivered El mensaje no fue entregado a discreción del SMSC, los motivos pueden incluir: red no disponible, problemas técnicos del operador, dispositivo fuera de alcance, o problemas de portabilidad temporales. unknown El mensaje se encuentra en un estado desconocido, el operador está intentando entregarlo. Este estado podría indicar que el dispositivo está apagado. rejected El operador según sus propios criterios, rechazó entregar este mensaje.
delivered_at	La fecha en que el mensaje de texto fue entregado al dispositivo destino

Su servidor debe responder con un código HTTP/200, cualquier otro código se interpretará como un error temporal en su servidor, y ZPK reintentará la notificación cada 25 minutos durante un máximo de 56 horas.

SDK en PHP para enviar mensajes de texto.

ZPK-PHP es una librería de código abierto instalable mediante composer que le permitirá integrar nuestras APIs en su proyecto PHP con un mínimo esfuerzo.

Documentación del SDK para PHP

Instalando ZPK-PHP con composer

composer require zpksystems/phpzpk

Ejemplo de request para enviar SMS

<?php

$smsRequest = new zpkSMS( new zpkApplication('appid','key') );

// Add SMS
$sms = new ZpkSms('+34600000000');
$sms->setMessage("Test SMS message");

$smsRequest->addSMS($sms);


// Add SMS with custom reference

$sms = new ZpkSms('+34600000000');
$sms->setMessage("Test SMS message");
$sms->setReference('my-reference');

$smsRequest->addSMS($sms);

// Send
$smsRequest->send();