Índice
Integra la centralita, los SMS, las llamadas automáticas (VozPush), la verificación de números y WhatsApp de MundoSMS en tu CRM, ERP o aplicación. Es una API REST: cada cosa tiene su ruta y cada ruta, su verbo HTTP.
- Dirección:
https://api.mundosms.es/v3/seguida de la ruta. Por ejemplo,GET https://api.mundosms.es/v3/calls. - Petición: en
GETyDELETE, los parámetros en la query; enPOSTyPATCH, en un cuerpo JSON. Las credenciales, en las cabecerasAuthorization: Bearer <token>,X-TimestampyX-Signature. - Respuesta: siempre JSON, con su código HTTP (200 si todo fue bien),
status,status_codeymessage, y los datos endata. Cada respuesta lleva la cabeceraX-Request-Id, con la que encuentras esa petición en Logs API. - Fechas: hora de Madrid con milisegundos, y cada una con su gemela en ISO 8601 con zona.
- SDK: un fichero que copias en tu proyecto, en PHP, Python o Node.js, y que firma solo.
Especificación OpenAPI 3.1 (JSON)Colección de Postman
Inicio rápido#
Tu primera llamada a la API en dos minutos.
- En el panel, entra en API y Soporte → Claves de API y pulsa Crear API Key: se abre su ficha. En Permisos deja «Solo consultas», en Caducidad elige «No caduca», deja activadas Firmar cada petición y Rechazar peticiones repetidas, y guarda.
- Copia el Token (empieza por
eyJ) y, con el botón Mostrar, la clave privada (20 letras y números). - Pega los dos en este script y ejecútalo en un terminal con
bash,curlyopenssl. Pide las cinco últimas llamadas entrantes de tu centralita:
TOKEN='PEGA_AQUI_EL_TOKEN' PRIVATE_KEY='PEGA_AQUI_LA_CLAVE_PRIVADA' RUTA='/v3/calls?type=in&limit=5' TS=$(date +%s) SIG=$(printf '%s' "$TOKEN.$TS.GET $RUTA." | openssl dgst -sha256 -hmac "$PRIVATE_KEY" -binary | base64 | tr '+/' '-_' | tr -d '=\n') curl -sS "https://api.mundosms.es$RUTA" \ -H "Authorization: Bearer $TOKEN" \ -H "X-Timestamp: $TS" \ -H "X-Signature: $SIG"
Si todo va bien, la API contesta con HTTP 200 y algo así:
{ "status": "success", "status_code": "0", "message": "5 results", "data": { "results": 5, "calls": [ { "id": 8812345, "client_id": null, "type": "in", "from": "34600123456", "from_name": null, "to": "34910123456", "to_type": "landline", "state": "answered", "state_code": 1, "date_start": "2026-11-20 10:15:03.250", "date_start_iso": "2026-11-20T10:15:03.250+01:00", "date_answer": "2026-11-20 10:15:09.118", "date_answer_iso": "2026-11-20T10:15:09.118+01:00", "date_end": "2026-11-20 10:18:41.902", "date_end_iso": "2026-11-20T10:18:41.902+01:00", "duration": 213, "duration_ring": 6, "pickup_extension": "recepcion", "credits": 0.0, "credits_total": 0.0, "bundle_id": null, "callingcard_id": null, "parent_type": null, "parent_id": null } ], "has_more": true, "next_from_id": null, "next_cursor": null } }
has_more es true y next_cursor es null porque, sin cursor ni from_datetime, el orden es desc (las últimas),
que no tiene página siguiente. Para recorrer o sincronizar, usa order=asc con cursor o from_datetime
(Paginación con cursor).
Si no, el message dice qué falla (lo explica Catálogo de errores). Lo más habitual al empezar:
Authentication failure (la firma no casa: revisa que el token y la clave privada sean de la misma clave de API, y que
firmas la ruta con su query tal cual la envías) y Signed requests must include the X-Timestamp header… (falta
X-Timestamp o el reloj de tu equipo va desfasado).
Pruébalo desde esta página#
En la página de esta referencia, www.mundosms.es/api-v3, tienes un formulario para lanzar
peticiones de verdad a tu cuenta sin escribir código: pegas tu token y tu clave privada, eliges una ruta de consulta y
editas sus parámetros. La petición se firma en tu navegador y va directamente de tu navegador a la API. La clave
privada no se envía a ningún sitio ni se guarda. Solo están las rutas que consultan (GET): ninguna envía, cambia ni
borra nada.
Peticiones reales sobre tu cuenta, solo de consulta. La petición se firma en tu navegador y va
directamente de tu navegador a api.mundosms.es. Tu clave privada no se envía a ningún sitio ni se
guarda: ni en este navegador ni en nuestros servidores; se borra al salir de la página. Para probar, mejor una clave
de solo lectura.
Petición (sin la clave privada, que nunca viaja; el token, recortado)
Respuesta
La misma petición con curl (bash y openssl; firma con un X-Timestamp nuevo cada vez)
Rutas#
Todas las rutas de la API. Cada una enlaza a su referencia; el permiso es el que necesita la clave (ver Permisos).
| Ruta | Qué hace | Permiso |
|---|---|---|
GET /v3/calls |
historial de llamadas | read, voip o list_voipcalls |
GET /v3/calls/{type}/{id} |
una llamada por su id | read, voip o list_voipcalls |
POST /v3/calls |
llamar desde una extensión (click2dial) | write, voip o click2dial |
GET /v3/calls/missed |
llamadas perdidas por devolver | read, voip o list_voipmissedcalls |
GET /v3/calls/live |
llamadas en curso | read, voip o list_voiplivecalls |
POST /v3/calls/live/{type}/{id}/hangup |
colgar una llamada en curso | write, voip o action_voiplivecalls |
GET /v3/calls/{type}/{id}/recording |
grabación de una llamada | read, voip o getrecording_voipcalls |
GET /v3/numbers |
tus números | read, voip o get_voipdids |
GET /v3/numbers/{did} |
uno de tus números | read, voip o get_voipdids |
PATCH /v3/numbers/{did} |
cambiar un número | write, voip o set_voipdids |
GET /v3/extensions |
tus extensiones | read, voip o get_voipextensions |
GET /v3/extensions/{extension} |
una de tus extensiones | read, voip o get_voipextensions |
POST /v3/extensions |
crear una extensión | write, voip o new_voipextensions |
PATCH /v3/extensions/{extension} |
cambiar una extensión | write, voip o set_voipextensions |
GET /v3/diagrams |
tus diagramas | read, voip, vozpush o getdiagrams_voip |
GET /v3/diagrams/{id} |
uno de tus diagramas | read, voip, vozpush o getdiagrams_voip |
POST /v3/callerid-validations |
verificar un número para presentarlo | write, voip, vozpush o callerid_validation |
POST /v3/voicefiles |
subir una locución | write, voip, vozpush o upload_voicefile |
GET /v3/voicefiles/{id} |
descargar una locución | read, voip, vozpush o get_voicefile |
DELETE /v3/voicefiles/{id} |
borrar una locución | write, voip, vozpush o delete_voicefile |
POST /v3/campaigns |
lanzar una campaña de VozPush | write, vozpush o sendcall |
GET /v3/campaigns |
la campaña con tu referencia (client_id) |
read, vozpush o getreport_call |
GET /v3/campaigns/{id} |
estado de una campaña | read, vozpush o getreport_call |
POST /v3/campaigns/{id}/pause |
pausar una campaña | write, vozpush o getreport_call |
POST /v3/campaigns/{id}/resume |
reanudarla | write, vozpush o getreport_call |
POST /v3/campaigns/{id}/cancel |
cancelarla | write, vozpush o getreport_call |
GET /v3/campaigns/{id}/calls/{to}/recording |
grabación de una llamada de VozPush | read, vozpush o getrecording_vozpush |
POST /v3/sms |
enviar SMS | write, sms o sendsms |
GET /v3/sms |
SMS enviados, uno por destinatario | read, sms o getreport |
POST /v3/sms/certified |
enviar un SMS certificado | write, sms o sendsms_cert |
POST /v3/sms/quote |
calcular el coste antes de enviar | read, sms o quotesms |
GET /v3/sms/replies |
respuestas a tus SMS | read, sms o getreport |
GET /v3/sms/sends |
varios envíos, o el de tu referencia | read, sms o getreport |
GET /v3/sms/sends/{id} |
estado de un envío | read, sms o getreport |
POST /v3/sms/sends/{id}/send-now |
enviar ya un envío programado | write, sms o scheduled_sendings |
POST /v3/sms/sends/{id}/cancel |
cancelar un envío programado | write, sms o scheduled_sendings |
POST /v3/numchecks |
comprobar un número de móvil | write, numcheck o numcheck |
GET /v3/whatsapp/numbers |
tus números de WhatsApp | whatsapp o whatsapp_numbers |
GET /v3/whatsapp/templates |
las plantillas de un número y su estado | whatsapp o whatsapp_templates |
POST /v3/whatsapp/messages |
enviar un WhatsApp | whatsapp o whatsapp_send |
GET /v3/whatsapp/messages/{message_id} |
el estado de un WhatsApp | whatsapp o whatsapp_status |
POST /v3/whatsapp/campaigns |
crear un envío masivo de WhatsApp | whatsapp o whatsapp_campaign |
GET /v3/whatsapp/campaigns/{campaign_id} |
el estado de un envío masivo | whatsapp o whatsapp_campaign |
POST /v3/whatsapp/campaigns/{campaign_id}/pause |
pausarlo | whatsapp o whatsapp_campaign |
POST /v3/whatsapp/campaigns/{campaign_id}/resume |
reanudarlo | whatsapp o whatsapp_campaign |
POST /v3/whatsapp/campaigns/{campaign_id}/cancel |
cancelarlo | whatsapp o whatsapp_campaign |
all vale para todas. Una ruta que no existe da 404 Route not found; una que existe con otro verbo, 405 Method not
allowed con la cabecera Allow (los verbos que admite).
Autenticación y firma#
La clave de API#
Las claves se crean en el panel, en API y Soporte → Claves de API. Cada una tiene:
- el token, que va en la cabecera
Authorization: Bearer <token>. Empieza poreyJy son tres trozos separados por puntos; - la clave privada (botón «Mostrar»): 20 letras y números. No se envía nunca: solo sirve para calcular la firma;
- sus permisos (ver Permisos), su caducidad (vacía = no caduca), su lista de IPs (vacía =
cualquiera) y si exige firma y
ts.
Una clave nueva nace con permiso de lectura, firma con ts y una hora de caducidad, a propósito: para una prueba rápida
basta, y no se queda abierta para siempre. Para una integración, dale los permisos que necesite y deja vacía la
caducidad. Quitarle la firma pide una confirmación en el panel: sin firma, quien vea el token puede usarlo.
La petición#
Una consulta (GET): los parámetros en la query.
GET /v3/calls?type=in&from_datetime=2026-11-01 HTTP/1.1 Host: api.mundosms.es Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxMjMifQ.c2lnbmF0dXJh X-Timestamp: 1795100000 X-Signature: 3bQkX0m7y6l9Jx3f0cQyq8l2m5Gk1Vb0wzq6c8u4t1E
Un envío o un cambio (POST, PATCH): los datos en un cuerpo JSON.
POST /v3/sms HTTP/1.1 Host: api.mundosms.es Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxMjMifQ.c2lnbmF0dXJh X-Timestamp: 1795100000 X-Signature: Qk9JRk5wM2xKZzZ2b0xUcXBZcHN5Z3BtQ1VxQmZ3ZE0 Content-Type: application/json {"to":"34600123456","text":"Tu cita es mañana a las 10:00","from":"MiClinica","client_id":"cita-4521"}
Las reglas, que la API comprueba:
- Cada cosa va en un solo sitio. En
GETyDELETEno se admite cuerpo (400 Body not allowed); enPOSTyPATCH, no se admite query (400 Query not allowed) y el cuerpo tiene que ser un objeto JSON (400 Body not valid). - Lo que va en la ruta (
{id},{did}…) manda: si lo repites en la query o en el cuerpo con otro valor,400 Parameter <nombre> not valid. - Las credenciales van siempre en las cabeceras. No pongas el token ni la firma en la URL: lo que va en una URL acaba en registros (de tu sistema, de proxies, del navegador) y en las vistas previas de chats y correos, que abren el enlace y repiten la petición.
La firma#
X-Signature = base64url( HMAC-SHA256( clave_privada,
token + "." + X-Timestamp + "." + MÉTODO + " " + ruta_con_query + "." + cuerpo ) ) # sin relleno "="MÉTODOen mayúsculas (GET,POST,PATCH,DELETE) y un espacio.ruta_con_query: desde/v3/, con la query tal cual la envías (mismo orden y mismos escapes):/v3/calls?type=in&from_datetime=2026-11-01. Sin query, solo la ruta.cuerpo: el texto exacto del JSON que envías. EnGETyDELETE, vacío: la cadena acaba en..X-Timestamp: la hora actual en segundos (epoch Unix) o en milisegundos, a menos de 5 minutos de la de nuestro servidor.base64urles base64 con-en vez de+,_en vez de/y sin los=del final. La clave privada es la clave del HMAC, tal cual (como texto, no decodificada).
Así la firma cubre qué pides (verbo y ruta), con qué datos (query y cuerpo) y cuándo: una petición firmada no sirve para otra ruta ni para otros datos, y caduca a los 5 minutos.
Hay tres modos, que se eligen en la clave:
| Modo | En «Claves de API» | Qué exige |
|---|---|---|
firma con ts (recomendado, el de una clave nueva) |
«Firmar cada petición» y «Rechazar peticiones repetidas» | la firma y X-Timestamp, y cada petición firmada vale una sola vez: repetida, 409 Duplicated request |
| firma | «Firmar cada petición» | la firma y X-Timestamp (a menos de 5 minutos). En las rutas de WhatsApp, además, cada petición firmada vale una sola vez, como con ts |
| sin firma | «Firmar cada petición» desactivado | solo el token. Desaconsejado: quien vea el token puede usarlo |
Para reintentar una petición firmada con ts, fírmala de nuevo con un X-Timestamp nuevo (ver
Reintentos seguros). Con milisegundos en X-Timestamp, dos peticiones iguales seguidas no chocan.
Ejemplos completos#
Los cuatro definen la misma función, mundosms(método, ruta, datos), que firma y envía cualquier petición (en GET y
DELETE pone los datos en la query y en POST y PATCH, en el cuerpo), y piden las llamadas entrantes de hoy. Valen igual
con una clave que no exija firma (deja la clave privada vacía). Si prefieres no escribir esto, el
SDK lo hace por ti.
#!/bin/bash # API de MundoSMS con bash, curl y openssl TOKEN='PEGA_AQUI_EL_TOKEN' # Claves de API: «Token» (empieza por eyJ) PRIVATE_KEY='PEGA_AQUI_LA_CLAVE_PRIVADA' # «Mostrar»; déjala vacía ('') si la clave no exige firma # mundosms MÉTODO RUTA [JSON]: firma y escribe la respuesta (con el código HTTP en la última línea). En GET y DELETE, la # query va ya en la RUTA (escapada); en POST y PATCH, el JSON es el cuerpo mundosms() { local metodo="$1" ruta="$2" cuerpo="${3:-}" ts firma=() datos=() ts=$(date +%s) if [ -n "$PRIVATE_KEY" ]; then firma=(-H "X-Signature: $(printf '%s' "$TOKEN.$ts.$metodo $ruta.$cuerpo" | openssl dgst -sha256 -hmac "$PRIVATE_KEY" -binary | base64 | tr '+/' '-_' | tr -d '=\n')") fi [ -n "$cuerpo" ] && datos=(-H 'Content-Type: application/json' --data-raw "$cuerpo") curl -sS -X "$metodo" "https://api.mundosms.es$ruta" \ -H "Authorization: Bearer $TOKEN" -H "X-Timestamp: $ts" "${firma[@]}" "${datos[@]}" -w '\nHTTP %{http_code}\n' } mundosms GET "/v3/calls?type=in&from_datetime=$(date +%F)"
<?php // API de MundoSMS con PHP 7.4 o superior y la extensión curl $token = "PEGA_AQUI_EL_TOKEN"; $private_key = "PEGA_AQUI_LA_CLAVE_PRIVADA"; // "" si la clave no exige firma function mundosms($metodo, $ruta, array $datos, $token, $private_key = "") { $query = ""; $cuerpo = ""; if ($metodo === "GET" || $metodo === "DELETE") { foreach ($datos as $k => $v) { // listas separadas por comas; sí/no como true/false (los null, fuera) if (is_array($v)) $datos[$k] = implode(",", $v); elseif (is_bool($v)) $datos[$k] = $v ? "true" : "false"; } if ($datos) $query = "?" . http_build_query($datos, "", "&", PHP_QUERY_RFC3986); } elseif ($datos) { $cuerpo = json_encode($datos, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); // se firma y se envía EXACTAMENTE esto } $ts = (string) time(); $cabeceras = ["Authorization: Bearer " . $token, "X-Timestamp: " . $ts]; if ($private_key !== "") { $firmado = $token . "." . $ts . "." . $metodo . " " . $ruta . $query . "." . $cuerpo; $cabeceras[] = "X-Signature: " . rtrim(strtr(base64_encode(hash_hmac("sha256", $firmado, $private_key, true)), "+/", "-_"), "="); } if ($cuerpo !== "") $cabeceras[] = "Content-Type: application/json"; $ch = curl_init("https://api.mundosms.es" . $ruta . $query); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => $metodo, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $cabeceras, CURLOPT_TIMEOUT => 60, ]); if ($cuerpo !== "") curl_setopt($ch, CURLOPT_POSTFIELDS, $cuerpo); $respuesta = curl_exec($ch); $http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); if ($respuesta === false) return ["http" => 0, "status" => "error", "message" => "No se pudo conectar: " . curl_error($ch)]; $r = json_decode($respuesta, true); return is_array($r) ? ["http" => $http] + $r : ["http" => $http, "status" => "error", "status_code" => "2", "message" => "Respuesta inesperada"]; } $r = mundosms("GET", "/v3/calls", ["type" => "in", "from_datetime" => date("Y-m-d")], $token, $private_key); if ($r["status"] === "success") foreach ($r["data"]["calls"] as $c) echo $c["date_start"], " ", $c["from"], " ", $c["state"], "\n"; else echo "Error HTTP ", $r["http"], ": ", $r["message"], "\n";
# API de MundoSMS con Python 3.8 o superior, sin librerías externas import base64, hashlib, hmac, json, time, urllib.error, urllib.parse, urllib.request TOKEN = "PEGA_AQUI_EL_TOKEN" PRIVATE_KEY = "PEGA_AQUI_LA_CLAVE_PRIVADA" # "" si la clave no exige firma def mundosms(metodo, ruta, datos=None, token=TOKEN, private_key=PRIVATE_KEY): datos = datos or {} query, cuerpo = "", b"" if metodo in ("GET", "DELETE"): if datos: # listas separadas por comas; sí/no como true/false; sin None q = {k: ",".join(map(str, v)) if isinstance(v, (list, tuple)) else ("true" if v is True else "false" if v is False else v) for k, v in datos.items() if v is not None} query = "?" + urllib.parse.urlencode(q, quote_via=urllib.parse.quote) elif datos: cuerpo = json.dumps(datos, ensure_ascii=False, separators=(",", ":")).encode() # se firma y se envía EXACTAMENTE esto ts = str(int(time.time())) cabeceras = {"Authorization": "Bearer " + token, "X-Timestamp": ts} if private_key: firmado = (token + "." + ts + "." + metodo + " " + ruta + query + ".").encode() + cuerpo cabeceras["X-Signature"] = base64.urlsafe_b64encode(hmac.new(private_key.encode(), firmado, hashlib.sha256).digest()).decode().rstrip("=") if cuerpo: cabeceras["Content-Type"] = "application/json" peticion = urllib.request.Request("https://api.mundosms.es" + ruta + query, data=cuerpo or None, headers=cabeceras, method=metodo) try: with urllib.request.urlopen(peticion, timeout=60) as r: http, texto = r.status, r.read() except urllib.error.HTTPError as e: # 4xx y 5xx también traen JSON http, texto = e.code, e.read() try: return http, json.loads(texto) except ValueError: # p. ej. un proxy intermedio que contesta HTML return http, {"status": "error", "status_code": "2", "message": "Respuesta inesperada"} http, r = mundosms("GET", "/v3/calls", {"type": "in", "from_datetime": time.strftime("%Y-%m-%d")}) if http == 200: for c in r["data"]["calls"]: print(c["date_start"], c["from"], c["state"]) else: print("Error HTTP", http, r["status_code"], r["message"], r.get("detail", ""))
// API de MundoSMS con Node.js 18 o superior, sin dependencias const crypto = require("crypto"); const TOKEN = "PEGA_AQUI_EL_TOKEN"; const PRIVATE_KEY = "PEGA_AQUI_LA_CLAVE_PRIVADA"; // "" si la clave no exige firma async function mundosms(metodo, ruta, datos = {}) { let query = "", cuerpo = ""; if (metodo === "GET" || metodo === "DELETE") { const q = new URLSearchParams(); for (const [k, v] of Object.entries(datos)) { // listas separadas por comas; sin null ni undefined if (v !== null && v !== undefined) q.append(k, Array.isArray(v) ? v.join(",") : String(v)); } if (q.toString()) query = "?" + q.toString(); } else if (Object.keys(datos).length) { cuerpo = JSON.stringify(datos); // se firma y se envía EXACTAMENTE esto } const ts = String(Math.floor(Date.now() / 1000)); const cabeceras = { "Authorization": "Bearer " + TOKEN, "X-Timestamp": ts }; if (PRIVATE_KEY) { cabeceras["X-Signature"] = crypto.createHmac("sha256", PRIVATE_KEY) .update(TOKEN + "." + ts + "." + metodo + " " + ruta + query + "." + cuerpo).digest("base64url"); } if (cuerpo) cabeceras["Content-Type"] = "application/json"; const r = await fetch("https://api.mundosms.es" + ruta + query, { method: metodo, headers: cabeceras, body: cuerpo || undefined, signal: AbortSignal.timeout(60000) }); const texto = await r.text(); try { return { http: r.status, ...JSON.parse(texto) }; } catch (e) { // p. ej. un proxy intermedio que contesta HTML return { http: r.status, status: "error", status_code: "2", message: "Respuesta inesperada" }; } } mundosms("GET", "/v3/calls", { type: "in", from_datetime: new Date().toISOString().slice(0, 10) }).then((r) => { if (r.http === 200) r.data.calls.forEach((c) => console.log(c.date_start, c.from, c.state)); else console.log("Error HTTP", r.http, r.status_code, r.message, r.detail || ""); });
Lo que hay que respetar en cualquier lenguaje:
- Se firma el texto del cuerpo y se envía ese mismo texto. Si tu herramienta vuelve a montar el JSON (otro orden de campos, espacios, saltos de línea), la firma ya no vale. En n8n o similares, manda el cuerpo como texto ya hecho.
- La query se firma tal cual va en la URL: si tu librería la reordena o la escapa de otra forma al enviarla, fírmala después de montarla, no antes.
- La firma va en base64url sin
=. El base64 normal no vale.
Errores de autenticación#
Todos llevan status_code "3"; el código HTTP dice de qué tipo son.
| HTTP | message |
Qué pasa |
|---|---|---|
| 401 | Missing Authorization header… |
no llega la cabecera Authorization |
| 401 | The Authorization header must be "Bearer <token>" … |
lo que va tras Bearer no es un token: vacío, cortado o la clave privada en su lugar |
| 401 | Token invalid |
el token no es de una clave nuestra, o tiene algún carácter cambiado |
| 401 | Token expired |
la clave ha caducado (se alarga en «Claves de API») |
| 401 | Authentication failure |
la firma no casa: falta X-Signature, se firmó con otra clave, en base64 normal, otra ruta, otra query u otro cuerpo |
| 401 | Signed requests must include the X-Timestamp header… |
falta X-Timestamp, o tu reloj va desfasado más de 5 minutos |
| 403 | Not allowed |
la clave no tiene permiso para esa ruta: detail dice cuáles sirven |
| 403 | IP not allowed |
la petición no llega desde una IP de la lista de la clave |
| 409 | Duplicated request |
esa misma petición firmada (mismo X-Timestamp, ruta y cuerpo) ya había llegado |
Permisos#
Cada ruta pide un nivel (lectura o escritura) y pertenece a una o varias categorías. Una clave puede usar una ruta si tiene cualquiera de los permisos que dice su columna en Rutas:
all(todo);- el permiso de la ruta, por ejemplo
click2dialparaPOST /v3/calls; - una de sus categorías:
voip(centralita),vozpush(llamadas automáticas),sms,numcheckowhatsapp; - su nivel:
read(todas las de lectura) owrite(todas las de escritura). WhatsApp es la excepción:readywritea secas no entran (ver WhatsApp).
Las locuciones, los diagramas y la verificación de números están en voip y en vozpush.
El permiso de la ruta vale para todo lo que hace ese método: getreport_call deja consultar las campañas de VozPush
y pausarlas, reanudarlas o cancelarlas. Para una clave que solo consulte campañas, usa read.
Dale a cada integración solo lo que necesita: un CRM que sincroniza el historial se arregla con read; uno que además
llama, con read y click2dial. En la ficha de la clave, «Todo», o marcar a la vez «Todas las consultas» y «Todas las
acciones», guarda la clave como all.
Convenciones#
Petición#
- En
GETyDELETE, los parámetros en la query (?type=in&limit=20), escapados como en una URL. EnPOSTyPATCH, en un cuerpo JSON (Content-Type: application/json), codificado en UTF-8. - Los nombres de los parámetros, en minúsculas y con
_. Un parámetro que la ruta no conoce se ignora. - Sí/no:
trueofalse(en la query, el textotrue/false). Se aceptan también1/0. - Listas (destinatarios, ids): en JSON, una lista (
["34600123456","34600123457"]); en la query, separadas por comas (ids=101,102). - Números de teléfono: como texto, en formato internacional y solo cifras:
"34600123456". Un+delante se acepta y se quita. - Fechas de entrada:
AAAA-MM-DD,AAAA-MM-DD hh:mm,AAAA-MM-DD hh:mm:ssoAAAA-MM-DD hh:mm:ss.mmm, en hora de Madrid. También se acepta ISO 8601 con zona (2026-11-20T09:00:00Z) endate_scheduledy en los filtrosfrom_datetimeyto_datetime. Una fecha que no vale da400 Parameter <nombre> not valid.AAAA-MM-DDsola es ese día a las00:00:00.
Respuesta#
Siempre JSON (Content-Type: application/json; charset=utf-8) con su código HTTP:
| Campo | Tipo | Qué es |
|---|---|---|
status |
texto | success o error |
status_code |
texto | "0" si fue bien; si no, el tipo de error (tabla siguiente) |
message |
texto | OK, N results en los listados, o la frase del error, en inglés y estable: puedes compararla |
detail |
texto | solo en algunos errores: más contexto (qué valor se espera, qué contestó el servidor de voz) |
data |
objeto | los datos, cuando los hay |
| HTTP | status_code |
Significado |
|---|---|---|
| 200 | "0" |
bien |
| 400 | "3" |
falta un parámetro o no vale |
| 401 | "3" |
autenticación: token, firma o X-Timestamp |
| 402 | "5" |
saldo insuficiente |
| 403 | "3" |
sin permiso para la ruta, IP no admitida o número no verificado |
| 404 | "4" |
no existe (en tu cuenta), o la ruta no existe |
| 405 | "3" |
la ruta existe, pero no con ese verbo (cabecera Allow) |
| 409 | "3" |
conflicto: petición repetida, o no se puede en el estado actual (ya enviado, ya cancelado, ya existe) |
| 429 | "7" |
demasiadas peticiones o intentos |
| 500 | "2" |
error interno o el servidor de voz no responde: reintenta más tarde |
WhatsApp usa además sus propios códigos ("6" a "12", ver WhatsApp). status_code es texto ("0",
no 0): es un código, no una cantidad. En JavaScript, "0" !== 0.
Cada respuesta lleva la cabecera X-Request-Id (26 letras y cifras). Guárdala cuando algo falle: con ella encuentras la
petición en Logs API y, si nos escribes, la encontramos nosotros.
Ejemplo de error:
{ "status": "error", "status_code": "3", "message": "Parameter from_datetime not valid", "detail": "formato AAAA-MM-DD[ hh:mm[:ss[.mmm]]], hora de Madrid" }
Fechas y zona horaria#
Cada fecha de la respuesta sale dos veces:
date_x:AAAA-MM-DD hh:mm:ss.mmm, hora de Madrid, con milisegundos. Es la forma cómoda para guardar en una base de datos que trabaje en hora de España.date_x_iso: la misma en ISO 8601 con su zona (+01:00en invierno,+02:00en verano). Es la que hay que usar para convertir a otra zona o a UTC sin ambigüedad (la hora repetida del cambio de horario de octubre solo la distingue esta).
{ "date_start": "2026-11-20 10:15:03.250", "date_start_iso": "2026-11-20T10:15:03.250+01:00" }
Las horas que guardamos sin fracción salen con .000. Si no hay fecha (una llamada que no se descolgó no tiene
date_answer), las dos son null.
Las fechas que mandas (from_datetime, to_datetime, date_scheduled) valen de las dos formas:
AAAA-MM-DD hh:mm:ss, en hora de Madrid (los segundos, los minutos y la hora se pueden omitir; la fracción, también);- ISO 8601 con su zona:
2026-11-20T09:15:03Zo2026-11-20T10:15:03+01:00. Las convertimos a hora de Madrid. Sin zona (2026-11-20T10:15:03) cuenta como hora de Madrid.
Así puedes mandar tal cual una fecha date_x_iso que te hayamos devuelto.
null, números y textos#
- Un dato que no existe o no aplica es
null, nunca"". Los campos salen siempre, aunque valgannull, salvo los que dependen de un parámetroinclude_*o del tipo de objeto (por ejemplo,extensionsolo en las llamadas salientes): cada ruta lo dice. - Las cantidades son números JSON:
credits: 0.0125,duration: 213. Los ids, enteros. - Los teléfonos, los DID y los códigos son texto:
"34600123456","0". - Las duraciones van en segundos y no llevan sufijo (
duration,duration_ring); los campos en otra unidad lo dicen en el nombre (latency_ms,retry_delay_min).
Identificadores: id y client_id#
ides nuestro identificador del objeto (una llamada, un envío, una extensión). Es un entero y no cambia.- Un SMS a un destinatario se identifica por su envío y su número:
send_id+to. client_ides tu referencia, la que mandas al crear algo (un SMS, una campaña de VozPush, una consulta de NumCheck, un WhatsApp). Sale en las respuestas y sirve para buscar por ella. En los objetos que no la admiten (llamadas, números, extensiones, locuciones) es siemprenull.- Topes de
client_id: 50 caracteres en SMS y SMS certificados, 30 en NumCheck, 20 en campañas de VozPush y 100 en WhatsApp. client_idno impide duplicados: dos envíos con la misma referencia son dos envíos. Para no duplicar al reintentar, mira Reintentos seguros.
Paginación con cursor#
GET /v3/calls, GET /v3/sms, GET /v3/sms/replies, GET /v3/numbers y GET /v3/diagrams devuelven como mucho limit
elementos, en data.<lista>, con:
| Campo | Qué es |
|---|---|
results |
cuántos elementos trae esta página |
has_more |
true si hay más después de esta página |
next_cursor |
la posición desde la que pedir la página siguiente: pásala tal cual como cursor. Es texto y no hay que interpretarlo; null en orden desc |
next_from_id |
en las listas que avanzan por id, lo mismo como número (pásalo como from_id). Sigue por compatibilidad: usa next_cursor |
Cómo se recorre un listado:
- El mismo mecanismo en todas las listas: pide la primera página, y la siguiente con
cursor= elnext_cursorque te devolvimos, mientrashas_moreseatrue. No hace falta saber cómo avanza cada lista por dentro. cursoryfrom_idson la misma posición en las listas que avanzan porid. No mandes los dos distintos: da 400.from_ides exclusivo: devuelve los elementos conidmayor que él.order:asc(del más antiguo al más nuevo) odesc(los últimos primero). Por defecto,ascsi pasascursor,from_idofrom_datetime, ydescsi no (las últimas).- Para recorrer todo o sincronizar, usa
order=ascy avanza concursor=next_cursormientrashas_moreseatrue. Guarda el últimonext_cursor: es tu marca para la siguiente sincronización. Enascllega también conhas_more: false(es la posición del último): con él, más tarde, pides solo lo nuevo. - El orden
descsirve para «las últimas N»; no tiene página siguiente: traehas_more: truesi hay más antiguas, peronext_cursor: null. Un bucle que siga mientrashas_moreseatruetiene que ir enasc, o no avanzará nunca. GET /v3/numbersyGET /v3/diagramsvan siempre en orden deid(sinorder).GET /v3/callscontype=all(el valor por defecto) mezcla tres tablas, cada una con su numeración, así que no avanza porid: solo tienenext_cursor(ynext_from_idsalenull). Por eso conviene usar siemprecursor.- No te salta ni te repite ninguna llamada.
- Si no hay nada nuevo, devuelve 0 resultados y el mismo cursor.
- En cada página repite los mismos filtros: el cursor solo lleva la posición.
- Los SDK lo hacen por ti:
todos()recorre las páginas y te da los elementos uno a uno.
Nombres anteriores (alias)#
Algunos parámetros aceptan también el nombre que tenían en /APIv3/ (por ejemplo destination por to, o message por
text, en POST /v3/sms). En la respuesta solo sale el nombre nuevo. Usa siempre el nuevo: los alias son para
migrar, y la tabla está en Equivalencias de nombres.
Llamadas en curso e historial#
Estados de una llamada#
state es una palabra estable. Los grupos del filtro status de GET /v3/calls son answered y missed; las llamadas en
curso no entran en ninguno.
En las entrantes, state no dice si alguien la atendió. La centralita descuelga para el menú o la cola, así que una
entrante que nadie coge acaba answered. Para saber si la atendió una persona, mira attended_by, o filtra con status: en
las entrantes, status va por quién atendió, no por state.
state |
Qué pasó | Grupo de status |
|---|---|---|
ringing |
está sonando | en curso |
talking |
descolgada, en conversación | en curso |
forwarding |
desviándose | en curso |
ending |
terminando | en curso |
answered |
se descolgó y ya terminó | answered |
ended |
una llamada de función (menú, buzón, locución) que terminó | — |
no_answer |
sonó y nadie la cogió | missed |
busy |
comunicando | missed |
unreachable |
no se llegó al teléfono (apagado, sin cobertura, extensión no conectada) | missed |
cancelled |
quien llamaba colgó mientras sonaba | missed |
rejected |
rechazada | missed |
do_not_disturb |
el destino tenía «no molestar» | missed |
failed |
error: número inexistente, destino no admitido… | missed |
forwarded |
se desvió a otro destino (la llamada desviada va aparte, enlazada con parent_id) |
— |
unknown |
cualquier otro | — |
En GET /v3/calls, state_code lleva además el código numérico de la versión anterior (0-11, -1 si no tiene), para quien
lo necesite: distingue, por ejemplo, entre una llamada terminada por quien llamó o desde la centralita, que en state son
las dos answered.
Tipos de llamada#
type |
Qué es |
|---|---|
in |
entrante: alguien llama a uno de tus números |
out |
saliente: una extensión llama fuera, o una pata que crea la centralita (un desvío a un móvil) |
func |
de función: el tramo que la llamada pasa en un menú, un buzón, una locución o una cola |
Cada tipo tiene su propia serie de id: la llamada in 8812345 y la out 8812345 son dos distintas. Por eso las rutas de
llamadas piden type junto al id.
Una llamada con desvíos o transferencias son varias filas enlazadas: la entrante, la saliente que la desvió a un móvil y
el tramo del menú llevan parent_type/parent_id apuntando a la que las originó, y con include_related: true cada
llamada trae sus relacionadas dentro, en related.
GET /v3/calls/live — llamadas en curso#
GET https://api.mundosms.es/v3/calls/live Pruébalo
Las llamadas que están sonando o en conversación ahora mismo. Sirve para un panel de recepción («¿con quién habla cada extensión?»), para mostrar la ficha del cliente cuando suena el teléfono o para saber si un número está ya al teléfono.
Permiso: read, voip o list_voiplivecalls.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
type |
texto | no | all (por defecto), in, out o func |
extension |
texto | no | solo las llamadas en las que participa esta extensión. Con ella, cada llamada lleva other_party: con quién habla la extensión |
number |
texto | no | solo las llamadas en las que aparece este número (origen, destino o alguna pata) |
from_datetime |
fecha | no | solo las que empezaron desde esta hora |
all_legs |
sí/no | no | true: también las llamadas que ya van como pata de otra, sueltas. Por defecto, solo las principales (como en GET /v3/calls) |
limit |
entero | no | 1-500, 100 por defecto |
Petición:
GET /v3/calls/live?extension=recepcionRespuesta (200):
{ "status": "success", "status_code": "0", "message": "1 results", "data": { "results": 1, "calls": [ { "id": 8812399, "client_id": null, "type": "in", "from": "34600123456", "to": "34910123456", "party": "recepcion", "state": "talking", "date_start": "2026-11-20 11:02:10.031", "date_start_iso": "2026-11-20T11:02:10.031+01:00", "date_answer": "2026-11-20 11:02:14.540", "date_answer_iso": "2026-11-20T11:02:14.540+01:00", "date_bridged": "2026-11-20 11:02:14.602", "date_bridged_iso": "2026-11-20T11:02:14.602+01:00", "legs": [ { "id": 5511203, "client_id": null, "type": "out", "from": "34910123456", "to": "recepcion", "party": "recepcion", "state": "talking", "date_start": "2026-11-20 11:02:10.412", "date_start_iso": "2026-11-20T11:02:10.412+01:00", "date_answer": "2026-11-20 11:02:14.540", "date_answer_iso": "2026-11-20T11:02:14.540+01:00", "date_bridged": null, "date_bridged_iso": null } ], "other_party": "34600123456" } ], "has_more": false } }
Campos de cada llamada (y de cada pata de legs, que tienen la misma forma salvo legs y other_party):
| Campo | Tipo | Qué es |
|---|---|---|
id, type |
entero, texto | la llamada; el mismo id que dará GET /v3/calls con ese type cuando termine |
client_id |
null | siempre null |
from, to |
texto | origen y destino |
party |
texto o null | la llamada vista desde tu búsqueda: sin extension, el participante actual; con extension, esa extensión |
state |
texto | ringing (sin descolgar) o talking (descolgada) |
date_start, date_answer, date_bridged |
fecha o null | inicio, descuelgue y cuándo quedaron conectados los dos lados |
legs |
lista | las patas de la llamada (desvíos, grupos que suenan a la vez, transferencias) |
other_party |
texto o null | solo con extension: el otro lado de la conversación visto desde esa extensión. Si hay más de dos partes, el principal; el resto está en legs |
Las llamadas en curso son pocas y cambian a cada segundo: este listado no tiene cursor (next_from_id). Si has_more es
true, hay más de limit: afina el filtro o sube limit.
Errores propios: 400 Parameter limit not valid, 400 Parameter number not valid.
POST /v3/calls/live/{type}/{id}/hangup — colgar una llamada en curso#
POST https://api.mundosms.es/v3/calls/live/{type}/{id}/hangup
Cuelga una llamada que está en curso.
Permiso: write, voip o action_voiplivecalls.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
type |
texto | sí | in, out o func (en la ruta) |
id |
entero | sí | el id de la llamada (de GET /v3/calls/live) (en la ruta) |
Petición:
POST /v3/calls/live/in/8812399/hangupRespuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":8812399,"type":"in","changed":true}}
changed: false quiere decir que la llamada ya había terminado: no es un error, y message lo dice (Call already terminated).
Errores propios: 404 Call not found, 400 Parameter type not valid.
GET /v3/calls — historial de llamadas#
GET https://api.mundosms.es/v3/calls Pruébalo
El historial de llamadas terminadas (y, si no pides lo contrario, también las que siguen en curso), con sus horas, estado,
duración, coste y desvíos. Es la ruta para sincronizar las llamadas con un CRM (ver
Sincronizar llamadas sin perder ninguna). Sin type, trae todas:
entrantes, salientes y funciones que empiezan solas, ordenadas por hora de inicio, así que una sola petición basta.
Permiso: read, voip o list_voipcalls.
También: GET /v3/calls/{type}/{id} — una llamada por su id (sin paginación; si no existe, 404 Call not found).
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
type |
texto | no | all (por defecto): entrantes, salientes y funciones sin padre (las que empiezan solas, no las que son un paso de una llamada; esas salen con include_related), ordenadas por hora de inicio. O solo in, out o func |
cursor |
texto | no | el next_cursor de la página anterior, tal cual (con cualquier type) |
from_id |
entero | no | con type in, out o func: lo mismo que cursor, como número (por compatibilidad) |
limit |
entero | no | 1-100, 20 por defecto |
order |
texto | no | asc o desc (ver Paginación con cursor) |
from_datetime |
fecha | no | desde esta hora de inicio (incluida) |
to_datetime |
fecha | no | hasta esta hora de inicio (sin incluir) |
stop_at_ongoing |
sí/no | no | true: la página se corta antes de la primera llamada que siga en curso (no la quita: se para ahí), para que no te saltes ninguna a medias. Una que lleve más de 12 horas «en curso» (un registro que no se cerró) no la corta: sale con su estado. Exige order: "asc" |
number |
texto | no | las llamadas en las que este número es el origen o el destino |
status |
texto | no | answered o missed. Entrantes: answered = la atendió alguien (attended_by); missed = no la atendió nadie y ya colgó, aunque la centralita la descolgara para el menú o la cola. Salientes: por el estado, answered = contestó el destino (ver Estados de una llamada). Solo con type in u out |
extension |
texto | no | salientes: la extensión que llamó; entrantes: la que descolgó. Solo con type in u out |
did |
texto | no | entrantes: tu número al que llamaron; salientes: el número que se presentó. Solo con type in u out |
all_legs |
sí/no | no | true: también las patas internas de cada llamada (por defecto solo las principales) |
include_related |
sí/no | no | true: cada llamada trae sus relacionadas (desvíos, transferencias, funciones) en related |
include_xml |
sí/no | no | true: en las de función, el plan XML entero en xml_plan (es grande) |
Petición: las llamadas perdidas de un número desde el día 1:
GET /v3/calls?type=in&number=34600123456&status=missed&from_datetime=2026-11-01Respuesta (200):
{ "status": "success", "status_code": "0", "message": "1 results", "data": { "results": 1, "calls": [ { "id": 8812001, "client_id": null, "type": "in", "from": "34600123456", "from_name": null, "to": "34910123456", "to_type": "landline", "state": "no_answer", "state_code": 3, "date_start": "2026-11-18 17:40:22.113", "date_start_iso": "2026-11-18T17:40:22.113+01:00", "date_answer": null, "date_answer_iso": null, "date_end": "2026-11-18 17:40:52.907", "date_end_iso": "2026-11-18T17:40:52.907+01:00", "duration": 0, "duration_ring": 30, "pickup_extension": null, "attended_by": null, "last_attended_by": null, "followup": { "state": "called_back", "id": 8812950, "type": "out", "date": "2026-11-18 17:52:10.120", "date_iso": "2026-11-18T17:52:10.120+01:00", "extension": "recepcion", "callback_attempts": 1 }, "credits": 0.0, "credits_total": 0.0, "bundle_id": null, "callingcard_id": null, "parent_type": null, "parent_id": null } ], "has_more": false, "next_from_id": 8812001, "next_cursor": "8812001" } }
Campos de cada llamada. Según type salen unos u otros:
- todas:
id,client_id,type,from,to,state,state_code,date_start,date_answer,date_end,duration,credits,credits_total,bundle_id,callingcard_id,parent_typeyparent_id; inyout, además:from_name,to_typeyduration_ring;out(salientes):extension,bridge_typeydate_bridged;in(entrantes):pickup_extension,attended_by,last_attended_byyfollowup;- las que nos llegaron desviadas: los
redirected_*; func(de función):trace_steps,trace_ivr,result_ivr,result_record,result_subivry, coninclude_xml,xml_plan.
| Campo | Tipo | Qué es |
|---|---|---|
id, type |
entero, texto | la llamada |
client_id |
null | siempre null |
from |
texto o null | quien llama. En las de función, null |
from_name |
texto o null | el nombre que se presentó con el número, si lo hubo |
to |
texto o null | el destino |
to_type |
texto o null | extension, landline (fijo), mobile, special, function o unknown. No sale en las de función |
state, state_code |
texto, entero | ver Estados de una llamada |
date_start, date_answer, date_end |
fecha o null | inicio, descuelgue y fin (en las de función, date_answer es la entrada en la función) |
date_bridged |
fecha o null | solo salientes: cuándo quedaron conectados los dos lados |
duration |
entero o null | segundos de conversación |
duration_ring |
entero o null | segundos sonando (no en las de función) |
extension |
texto o null | solo salientes: la extensión que llamó |
bridge_type |
texto o null | solo salientes: cómo se conectó (por ejemplo, attended_transfer) |
pickup_extension |
texto o null | solo entrantes: la extensión que la cogió |
attended_by, last_attended_by |
texto o null | solo entrantes: quién la atendió primero y último. null si no la atendió nadie (es una perdida, aunque state diga answered) |
followup |
objeto o null | solo entrantes, y solo en las perdidas (en las demás, null): qué pasó después. Ver abajo |
redirected_from, redirected_reason, redirected_count, redirected_chain, redirected_headers |
solo si la llamada nos llegó desviada desde otro número: quién la desvió (anonymous si lo ocultó), por qué y la cadena completa |
|
credits, credits_total |
número o null | coste de esta llamada y con sus relacionadas |
bundle_id |
entero o null | el bono de minutos que se usó |
callingcard_id |
entero o null | la tarjeta de llamadas, si la hubo |
trace_steps, trace_ivr, result_ivr, result_record, result_subivr |
texto o null | solo las de función: el recorrido por el plan, las teclas pulsadas y lo grabado, separados por barras verticales |
xml_plan |
texto o null | solo las de función y con include_xml |
parent_type, parent_id |
texto, entero o null | la llamada que originó esta (un desvío, una transferencia) |
related |
lista | solo con include_related: las llamadas relacionadas, con esta misma forma |
En una llamada que nos llega desviada, from es quien llamó, to es tu número y quien desvió va en redirected_from.
En la pata que crea tu centralita al desviar a un móvil, from es el número que se presenta, to es el móvil y
parent_id apunta a la entrante.
Llamadas perdidas. Cada perdida entrante (nadie la atendió y ya colgó) lleva siempre followup, con lo primero que pasó
después con ese número:
followup.state |
Qué pasó |
|---|---|
called_back |
alguien de tu cuenta le llamó y contestó (más de 5 segundos, o sigue hablando) |
called_again |
volvió a llamar y le atendieron (más de 5 segundos, o sigue hablando) |
pending |
nada de lo anterior: está por devolver |
no_number |
llamó con el número oculto: no se puede devolver |
id,type,dateyextensionson de esa llamada (de quién la devolvió o de quién le atendió). Conpending,null.callback_attemptscuenta las llamadas que se le hicieron sin que contestara, hasta resolverse.- El seguimiento se calcula al pedirlo: una perdida
pendinghoy puede sercalled_backmañana. - Para saber a quién llamar (las perdidas pendientes, una por número), usa
GET /v3/calls/missed.
Errores propios: 400 Parameter type not valid, 400 Parameter <nombre> not valid (con detail: qué se espera),
404 Call not found (con id).
GET /v3/calls/missed — llamadas perdidas por devolver#
GET https://api.mundosms.es/v3/calls/missed Pruébalo
A quién llamar: los números con llamadas perdidas que nadie ha atendido después, uno por número, la más reciente primero.
- Perdida: una entrante que no atendió nadie, aunque la centralita la descolgara para el menú o la cola.
- Atendida después: volvió a llamar y le atendieron, o alguien de tu cuenta le llamó y contestó (más de 5 segundos, o sigue hablando).
Es una foto, sin cursor: un número sale de la lista en cuanto se le atiende. Pídela entera cada vez.
Permiso: read, voip o list_voipcalls.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
from_datetime |
fecha | no | desde (incluida). Por defecto, hace 7 días; como mucho, hace 31 |
to_datetime |
fecha | no | hasta (sin incluir). Por defecto, ahora |
number |
texto | no | un número que llamó |
did |
texto | no | tu número al que llamaron |
include_returned |
sí/no | no | true: también los números ya atendidos, con quién y cómo. Por defecto, solo los pendientes |
limit |
entero | no | 1-500, 100 por defecto |
Petición (sin parámetros: los números con llamadas perdidas sin devolver de los últimos 7 días, en todos tus números):
GET /v3/calls/missedRespuesta (200):
{ "status": "success", "status_code": "0", "message": "1 results", "data": { "results": 1, "numbers": [ { "number": "34600123456", "did": "34910123456", "missed_count": 2, "first_missed": "2026-11-20 09:58:02.410", "first_missed_iso": "2026-11-20T09:58:02.410+01:00", "last_missed": "2026-11-20 10:31:15.002", "last_missed_iso": "2026-11-20T10:31:15.002+01:00", "last_call_id": 8812001, "followup": { "state": "pending", "id": null, "type": null, "date": null, "date_iso": null, "extension": null, "callback_attempts": 1 } } ], "has_more": false, "anonymous": 3 } }
| Campo | Qué es |
|---|---|
number |
quien llamó |
did |
tu número al que llamó la última vez |
missed_count |
perdidas desde la última vez que se le atendió (dentro de la ventana) |
first_missed, last_missed |
la primera y la última de esas perdidas |
last_call_id |
la última perdida, por si la quieres ver en GET /v3/calls (type in, id) |
followup |
como en GET /v3/calls: pending o, con include_returned, called_back / called_again con la llamada, su hora y la extensión. callback_attempts: las veces que se le llamó sin que contestara |
anonymous |
perdidas con el número oculto en la ventana: no se pueden devolver, así que no salen en la lista |
Errores propios: 400 Parameter from_datetime not valid (más de 31 días atrás), 400 Parameter <nombre> not valid.
GET /v3/calls/{type}/{id}/recording — grabación de una llamada#
GET https://api.mundosms.es/v3/calls/{type}/{id}/recording
Descarga la grabación de una llamada (si la llamada se grabó).
Permiso: read, voip o getrecording_voipcalls.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
type |
texto | sí | in, out o func (en la ruta) |
id |
entero | sí | el id de la llamada (en la ruta) |
mode_out |
texto | no | inline (por defecto: el audio en la respuesta), download (el audio como descarga) o base64 (JSON con el audio en base64) |
format |
texto | no | mp3: convertido a MP3, que reproduce cualquier navegador. Sin él, el formato original (normalmente OGG/Opus) |
filename |
texto | no | el nombre del fichero, sin extensión |
Con inline y download la respuesta es el audio (con su Content-Type, por ejemplo audio/ogg o audio/mpeg), y
admite peticiones parciales (Range) para reproducirlo a saltos. Los errores son JSON, como en el resto.
Petición:
GET /v3/calls/in/8812345/recording?mode_out=base64&format=mp3Respuesta (200):
{ "status": "success", "status_code": "0", "message": "OK", "data": { "id": 8812345, "type": "in", "client_id": null, "filename": "llamada_8812345.mp3", "content_type": "audio/mpeg", "size": 845120, "base64": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjYxLjcuMTAw..." } }
Errores propios: 404 Call not found, 404 Recording not found (la llamada existe pero no tiene grabación),
500 Internal error (no se pudo leer la grabación: reintenta más tarde).
Números y extensiones#
GET /v3/numbers — tus números#
GET https://api.mundosms.es/v3/numbers Pruébalo
Tus números de teléfono (DID) con su configuración y su coste.
Permiso: read, voip o get_voipdids.
También: GET /v3/numbers/{did} — uno de tus números.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
did |
texto | no | un número concreto |
include_xml |
sí/no | no | true: el plan de llamadas XML de cada número en xml_plan (es grande) |
cursor |
texto | no | el next_cursor de la página anterior: la página siguiente |
from_id |
entero | no | lo mismo que cursor, como número (por compatibilidad) |
limit |
entero | no | 1-500, 100 por defecto |
Devuelve tus números en orden de id, con cursor (Paginación con cursor). Con did, solo ese
número y sin cursor (has_more false y next_from_id null).
Petición:
GET /v3/numbers?limit=100Respuesta (200):
{ "status": "success", "status_code": "0", "message": "1 results", "data": { "results": 1, "dids": [ { "id": 4410, "client_id": null, "did": "34910123456", "name": "Centralita Madrid", "date_created": "2025-03-02 12:30:00.000", "date_created_iso": "2025-03-02T12:30:00.000+01:00", "date_expire": null, "date_expire_iso": null, "date_last_activity": "2026-11-20 11:02:10.000", "date_last_activity_iso": "2026-11-20T11:02:10.000+01:00", "calls_enabled": true, "fax_enabled": false, "sms_enabled": false, "diagram_id": 3120, "sms_url": null, "sms_email": null, "fax_url": null, "fax_email": null, "fax_extension": null, "monthly_cost_euro": 1.95, "monthly_cost_credits": 39.0, "minute_cost_landline": 0.0, "minute_cost_mobile": 0.0, "sms_cost": 0.0, "record_calls": true } ], "has_more": false, "next_from_id": 4410, "next_cursor": "4410" } }
date_expire es null si el número no caduca. diagram_id es el diagrama (plan de llamadas) que atiende el número; lo
describe GET /v3/diagrams.
Errores propios: 404 DID not found (con did).
PATCH /v3/numbers/{did} — cambiar un número#
PATCH https://api.mundosms.es/v3/numbers/{did}
Cambia uno o varios datos de la configuración de uno de tus números, de una vez: se comprueba todo antes de guardar, y si un campo no vale no se cambia ninguno. Manda solo los campos que quieres cambiar.
Permiso: write, voip o set_voipdids.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
did |
texto | sí | el número (en la ruta) |
name |
texto | no | el nombre del número, de 5 a 45 caracteres |
diagram_id |
entero | no | el diagrama (de tu cuenta, con plan) que atiende las llamadas. Deja de usar xml_plan |
xml_plan |
texto | no | el plan en XML (se comprueba antes de guardar). Deja de usar diagram_id. diagram_id y xml_plan a la vez dan 400 |
record_calls |
sí/no | no | grabar las llamadas |
sms_url |
texto | no | URL http:// o https:// (hasta 100) a la que reenviar los SMS que lleguen al número; "" o null la quita. Hoy ningún número recibe SMS: se guarda, pero no se usa |
sms_email |
texto | no | correo (hasta 45) al que reenviar esos SMS; "" o null lo quita. Como sms_url, hoy no se usa |
fax_url |
texto | no | URL a la que reenviar los faxes; "" o null la quita |
fax_email |
texto | no | correo al que reenviar los faxes; "" o null lo quita |
fax_extension |
texto | no | extensión que recibe los faxes; "" o null la quita |
Petición:
PATCH /v3/numbers/34910123456 Content-Type: application/json {"record_calls":false,"diagram_id":3120,"sms_email":"recepcion@ejemplo.com"}
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":4410,"did":"34910123456","changed":true,"fields":["record_calls","diagram_id","sms_email"]}}
fields son los campos que mandaste. changed: false quiere decir que ya tenían esos valores: no es un error, y message
lo dice (DID parameter was already set).
Errores propios: 404 DID not found, 400 Parameter <campo> not valid (con detail: qué se espera; en xml_plan, qué
falla en el XML), 400 Body not valid (nada que cambiar).
GET /v3/extensions — tus extensiones#
GET https://api.mundosms.es/v3/extensions Pruébalo
Las extensiones de tu centralita y, si lo pides, si están conectadas ahora y desde dónde.
Permiso: read, voip o get_voipextensions.
También: GET /v3/extensions/{extension} — una de tus extensiones.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
extension |
texto | no | una extensión concreta |
include_status |
sí/no | no | true: el registro de cada extensión en registration. Por defecto, true con extension y false sin ella |
Devuelve todas tus extensiones de una vez, sin cursor, las más nuevas primero.
Petición:
GET /v3/extensions?extension=recepcionRespuesta (200):
{ "status": "success", "status_code": "0", "message": "1 results", "data": { "results": 1, "extensions": [ { "id": 20431, "client_id": null, "extension": "recepcion", "date_created": "2025-03-02 12:41:07.000", "date_created_iso": "2025-03-02T12:41:07.000+01:00", "date_last_activity": "2026-11-20 11:02:14.000", "date_last_activity_iso": "2026-11-20T11:02:14.000+01:00", "caller_id": "\"Recepción\" <34910123456>", "caller_id_name": "Recepción", "caller_id_number": "34910123456", "comment": null, "record_calls": true, "password": null, "registration": { "state": "registered", "max_latency_ms": 31.4, "connections_count": 1, "keepalive": "ok", "connections": [ { "type": "sip", "state": "reachable", "host": "203.0.113.25", "port": 5060, "local_host": "192.168.1.30", "local_port": 5060, "server_host": null, "server_port": null, "protocol": "udp", "latency_ms": 31.4, "user_agent": "Yealink SIP-T54W 96.86.0.70", "date_last_keepalive": "2026-11-20 11:05:00.000", "date_last_keepalive_iso": "2026-11-20T11:05:00.000+01:00", "outbound_proxy": null } ] } } ] } }
Campos destacados:
| Campo | Qué es |
|---|---|
caller_id, caller_id_name, caller_id_number |
el número (y el nombre) que presenta la extensión al llamar fuera |
password |
la contraseña SIP. Solo al pedir una extension concreta y con una clave que pueda modificar extensiones; si no, null |
registration.state |
registered (conectada), unregistered (desconectada), unknown o pbx_unreachable (la centralita no respondió: reintenta) |
registration.connections[] |
cada aparato o app conectado: type sip (teléfono o softphone) o push (app móvil en reposo), y state reachable, unreachable o pending (recién conectado) |
Errores propios: 404 Extension not found (con extension).
PATCH /v3/extensions/{extension} — cambiar una extensión#
PATCH https://api.mundosms.es/v3/extensions/{extension}
Cambia uno o varios datos de una extensión, de una vez: se comprueba todo antes de guardar, y si un campo no vale no se cambia ninguno. Manda solo los campos que quieres cambiar.
Permiso: write, voip o set_voipextensions.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
extension |
texto | sí | la extensión (en la ruta) |
caller_id |
texto | no | lo que presenta al llamar, entero: "Texto" <número>. O este, o sus partes |
caller_id_number |
texto | no | solo el número que presenta (el texto se conserva) |
caller_id_name |
texto | no | solo el texto que presenta (hasta 40, sin comillas ni < >; el número se conserva) |
comment |
texto | no | un comentario, hasta 45 caracteres |
record_calls |
sí/no | no | grabar sus llamadas |
Petición:
PATCH /v3/extensions/recepcion Content-Type: application/json {"caller_id_number":"34910123456","record_calls":true}
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":20431,"extension":"recepcion","changed":true,"fields":["caller_id_number","record_calls"]}}
changed: false quiere decir que ya tenía esos valores: no es un error, y message lo dice (Extension parameter was
already set).
El número que presenta una extensión tiene que ser tuyo: uno de tus números (DID) o uno verificado con
POST /v3/callerid-validations. Si no, 403 Caller ID not verified. El texto y el número juntos caben en 50 caracteres.
Errores propios: 404 Extension not found, 400 Parameter <campo> not valid, 400 Body not valid (nada que cambiar),
403 Caller ID not verified.
POST /v3/extensions — crear una extensión#
POST https://api.mundosms.es/v3/extensions
Crea una extensión y devuelve su contraseña SIP para configurar el teléfono o la app.
Permiso: write, voip o new_voipextensions.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
extension |
texto | sí | el nombre de la extensión |
caller_id |
texto | no | el número que presenta, como "Texto" <número>; o, por separado, caller_id_name y caller_id_number |
comment |
texto | no | una nota |
record_calls |
sí/no | no | grabar sus llamadas (true por defecto) |
Petición:
POST /v3/extensions Content-Type: application/json {"extension":"ventas2","caller_id_name":"Ventas","caller_id_number":"34910123456","record_calls":false}
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":20577,"client_id":null,"extension":"ventas2","password":"q8Rk2mXz7LwP"}}
Guarda la contraseña en un sitio seguro: es la de la extensión.
Errores propios: 400 Parameter extension not valid, 400 Parameter caller_id not valid, 403 Caller ID not verified,
409 Extension already exists.
POST /v3/callerid-validations — verificar un número para presentarlo#
POST https://api.mundosms.es/v3/callerid-validations
Para presentar como remitente un número que no es de MundoSMS (el fijo de tu oficina, un móvil), hay que verificar que es tuyo: llamamos a ese número y una locución dicta un código que hay que introducir en el panel.
Permiso: write, voip, vozpush o callerid_validation.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
number |
texto | sí | el número que se verifica |
url_callback |
texto | no | URL tuya (https://, pública, hasta 250 caracteres) a la que avisamos cuando termina la llamada de verificación (qué llega) |
Petición:
POST /v3/callerid-validations Content-Type: application/json {"number":"34981123456"}
Respuesta (200):
{ "status": "success", "status_code": "0", "message": "OK", "data": {"number":"34981123456","state":"in_progress","relaunched":false,"code":"4821","attempts":1,"vozpush_id":991203,"cost":0.05,"balance":120.35} }
state es in_progress (la llamada está en marcha) o verified (el número ya estaba verificado: entonces no se llama).
relaunched: true quiere decir que había una verificación pendiente y se ha vuelto a llamar. vozpush_id se consulta con
GET /v3/campaigns/{id}.
Errores propios: 400 Parameter number not valid, 402 Insufficient credit, 429 Too many attempts (como mucho 10
intentos por número).
Click2dial#
POST /v3/calls — llamar desde una extensión#
POST https://api.mundosms.es/v3/calls
Hace sonar una extensión y, cuando la descuelgan, llama al destino y los conecta. Es el botón «Llamar» de un CRM.
Permiso: write, voip o click2dial.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
extension |
texto | sí | la extensión que suena primero |
to |
texto | sí | el número al que se llama |
from |
texto | no | el número que verá el destino. Tiene que ser tuyo (un DID o un número verificado); si no, se presenta el de la extensión |
extension_caller_id |
texto | no | lo que ve la extensión en su pantalla mientras suena (por defecto, «Click2dial» y el destino) |
url_callback |
texto | no | se acepta (https://, pública, hasta 150 caracteres), pero hoy no se envía ningún aviso: consulta la llamada en GET /v3/calls |
Petición:
POST /v3/calls Content-Type: application/json {"extension":"recepcion","to":"34600123456","from":"34910123456"}
Respuesta (200):
{"status":"success","status_code":"0","message":"OK"}
La respuesta quiere decir que la llamada se ha lanzado; la llamada en sí aparece en GET /v3/calls/live y, al terminar, en
GET /v3/calls como saliente (type: "out") con from igual al número presentado.
Errores propios:
| HTTP | message |
Qué pasa |
|---|---|---|
| 404 | Extension not found |
la extensión no es de tu cuenta |
| 409 | Extension not registered |
la extensión no está conectada (ningún teléfono ni app): no puede sonar. detail lo explica |
| 400 | Parameter extension not valid |
|
| 400 | Parameter to not valid |
falta el destino o no vale |
| 500 | Voice server unavailable / Voice server error |
la centralita no respondió: reintenta |
Grabaciones, locuciones y diagramas#
Las grabaciones de las llamadas se descargan con GET /v3/calls/{type}/{id}/recording,
y las de VozPush con GET /v3/campaigns/{id}/calls/{to}/recording. Aquí están las
locuciones (los audios que suenan en tus menús y campañas) y los diagramas (los planes de llamada).
GET /v3/voicefiles/{id} — descargar una locución#
GET https://api.mundosms.es/v3/voicefiles/{id}
Permiso: read, voip, vozpush o get_voicefile.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
id |
entero | sí | la locución (en la ruta) |
mode_out |
texto | no | inline (por defecto), download o base64 |
format |
texto | no | mp3: convertida a MP3. Sin él, el formato en que se guardó |
filename |
texto | no | el nombre del fichero, sin extensión |
Petición:
GET /v3/voicefiles/77120?mode_out=base64Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":77120,"client_id":null,"filename":"bienvenida.mp3","content_type":"audio/mpeg","size":48210,"base64":"SUQzBAAAAAAA..."}}
Errores propios: 404 Voice file not found (también si se borró: detail lo dice).
POST /v3/voicefiles — subir una locución#
POST https://api.mundosms.es/v3/voicefiles
Permiso: write, voip, vozpush o upload_voicefile.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
filetype |
texto | sí | base64 (el audio va en file) o url (en file va una URL pública de la que lo descargamos) |
file |
texto | sí | el audio en base64, o su URL |
filename |
texto | no | el nombre con el que se guarda |
Con url, la dirección tiene que ser pública, sin redirecciones, y el fichero de 16 MB como mucho.
Petición:
POST /v3/voicefiles Content-Type: application/json {"filetype":"url","file":"https://www.ejemplo.com/audios/bienvenida.mp3","filename":"bienvenida"}
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":77121,"client_id":null}}
Errores propios: 400 Parameter file not valid (con detail: URL not valid, URL not allowed, URL not downloadable,
File too large o Empty file).
DELETE /v3/voicefiles/{id} — borrar una locución#
DELETE https://api.mundosms.es/v3/voicefiles/{id}
Permiso: write, voip, vozpush o delete_voicefile.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
id |
entero | sí | la locución (en la ruta) |
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":77121,"deleted":true}}
Errores propios: 404 Voice file not found, 409 Voice file cannot be deleted (tiene un coste asociado: una locución
generada), 409 Voice file cannot be deleted yet (recién usada: reintenta en unos minutos).
GET /v3/diagrams — tus diagramas#
GET https://api.mundosms.es/v3/diagrams
Los diagramas (planes de llamada) de tu cuenta: los que atienden tus números y los que usan tus campañas de VozPush.
Permiso: read, voip, vozpush o getdiagrams_voip.
También: GET /v3/diagrams/{id} — uno de tus diagramas.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
id |
entero | no | un diagrama concreto |
cursor |
texto | no | sin id: el next_cursor de la página anterior |
from_id |
entero | no | lo mismo que cursor, como número (por compatibilidad) |
limit |
entero | no | sin id: 1-500, 50 por defecto |
mode_out |
texto | no | con id: image_base64 (por defecto: la imagen del diagrama en image_base64), image_inline (la imagen tal cual) o xml (el plan en xml_plan) |
Respuesta (200):
{ "status": "success", "status_code": "0", "message": "1 results", "data": { "results": 1, "diagrams": [ {"id":3120,"client_id":null,"date_created":"2025-03-02 12:35:10.000","date_created_iso":"2025-03-02T12:35:10.000+01:00","date_updated":"2026-10-14 09:12:44.000","date_updated_iso":"2026-10-14T09:12:44.000+02:00","name":"Horario oficina","comment":null,"snapshot_width":1280,"snapshot_height":720} ], "has_more": false, "next_from_id": 3120, "next_cursor": "3120" } }
Sin id, devuelve tus diagramas en orden de id, con cursor (Paginación con cursor). Con
id, solo ese y sin cursor (has_more false y next_from_id null).
Errores propios: 404 Diagram not found (con id).
VozPush: llamadas automáticas#
VozPush lanza llamadas automáticas a una lista de números siguiendo un plan (una locución, un menú de teclas, una transferencia a un agente…). Una campaña es un lanzamiento a uno o varios destinatarios.
POST /v3/campaigns — lanzar una campaña#
POST https://api.mundosms.es/v3/campaigns
Permiso: write, vozpush o sendcall.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
to |
texto o lista | sí | los destinatarios |
diagram_id |
entero | sí, o xml_plan |
el diagrama que siguen las llamadas |
xml_plan |
texto | sí, o diagram_id |
el plan en XML (el que exporta el editor de diagramas del panel) |
from |
texto | no | el número que se presenta. Tiene que ser tuyo (un DID o un número verificado) |
client_id |
texto | no | tu referencia (hasta 20 caracteres) |
name, description |
texto | no | para reconocerla en el panel |
date_scheduled |
fecha | no | cuándo lanzarla. Sin ella, ahora. (date_start, el nombre anterior, da 400: ahora date_* es la ventana) |
date_window_start, date_window_end |
fecha | no | días entre los que se puede llamar, AAAA-MM-DD |
time_window_start, time_window_end |
hh:mm |
no | horas entre las que se puede llamar |
weekdays |
lista | no | qué días de la semana se puede llamar: siete true/false, de lunes a domingo. También vale el texto del panel, siete 1 o 0 separados por barras verticales |
max_concurrent |
entero | no | llamadas a la vez |
delay_calls |
entero | no | segundos entre llamada y llamada |
retry_delay_min |
entero | no | minutos antes de reintentar un destinatario |
max_no_answer, max_busy, max_unreachable, max_answering_machine, max_fax, max_total_retries |
entero | no | reintentos por motivo y en total |
replace_vars, var1 … var8 |
no | personalización del plan por destinatario | |
url_callback |
texto | no | URL tuya (https://, pública, hasta 250 caracteres) a la que avisamos cuando la campaña termina o se cancela (qué llega) |
url_callback_single_failed |
texto | no | URL tuya (hasta 250 caracteres) a la que avisamos cuando un destinatario falla del todo (por ejemplo, para mandarle un SMS) (qué llega) |
skip_errors, show_errors |
sí/no | no | seguir aunque el plan tenga avisos; devolverlos en xml_errors |
Las llamadas salen siempre por la ruta 1 (route se acepta y se ignora).
Petición:
POST /v3/campaigns Content-Type: application/json {"to":["34600123456","34600123457"],"diagram_id":3120,"from":"34910123456","client_id":"recordatorio-1120","time_window_start":"09:00","time_window_end":"20:00","weekdays":[true,true,true,true,true,false,false]}
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":991250,"client_id":"recordatorio-1120","state":"in_progress","cost":0.0,"balance":120.35}}
state es in_progress o scheduled (con date_scheduled). Una campaña grande puede partirse en varias: entonces id es
la primera y ids, la lista de todas. Con show_errors, los avisos del plan van en xml_errors.
Errores propios: 400 Parameters not valid (con detail), 400 Parameter xml_plan not valid (con detail: los avisos del
plan), 403 Caller ID not verified, 404 Diagram not found, 402 Insufficient credit.
GET /v3/campaigns/{id} — estado de una campaña#
GET https://api.mundosms.es/v3/campaigns/{id}
Permiso: read, vozpush o getreport_call. Para pausar, reanudar o cancelar: write, vozpush o getreport_call
(con read se consulta, pero no se controla; getreport_call deja las dos cosas).
También: GET /v3/campaigns — la campaña con tu referencia (?client_id=…); POST /v3/campaigns/{id}/pause — pausarla; POST /v3/campaigns/{id}/resume — reanudarla; POST /v3/campaigns/{id}/cancel — cancelarla.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
id |
entero | sí | la campaña (en la ruta) |
client_id |
texto | no | en GET /v3/campaigns: tu referencia, para buscar la campaña sin saber su id |
Petición:
GET /v3/campaigns/991250Respuesta (200):
{ "status": "success", "status_code": "0", "message": "OK", "data": { "id": 991250, "client_id": "recordatorio-1120", "state": "finished", "cost": 0.18, "answered_count": 1, "failed_count": 1, "date_last_update": "2026-11-20 09:04:51.000", "date_last_update_iso": "2026-11-20T09:04:51.000+01:00", "duration_total": 74, "duration_functions": 74, "duration_mobile": 74, "duration_landline": 0, "duration_sip": 0, "results": [ {"to":"34600123456","state":"answered","recording_id":null,"ivr_keys":"1"}, {"to":"34600123457","state":"no_answer","recording_id":null,"ivr_keys":null} ] } }
Estados de la campaña (state): scheduled, in_progress, paused, finished, cancelled, failed. Estados de cada
destinatario (results[].state): los de una llamada (ringing, talking, answered, no_answer, busy, unreachable,
cancelled, rejected, failed…) más scheduled, paused, answering_machine y fax. recording_id es la grabación
de esa llamada, si la hubo, e ivr_keys, las teclas que pulsó el destinatario.
Al pausar, reanudar o cancelar (POST /v3/campaigns/{id}/pause, /resume, /cancel, sin cuerpo), la respuesta es
data: {id, client_id, state} con el estado nuevo.
Errores propios: 404 Campaign not found, 409 Not possible in the current state (por ejemplo, reanudar una terminada),
403 Not allowed (pausar, reanudar o cancelar con una clave de solo lectura).
GET /v3/campaigns/{id}/calls/{to}/recording — grabación de una llamada de VozPush#
GET https://api.mundosms.es/v3/campaigns/{id}/calls/{to}/recording
Permiso: read, vozpush o getrecording_vozpush.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
id |
entero | sí | la campaña (en la ruta) |
to |
texto | sí | el destinatario (en la ruta) |
mode_out |
texto | no | inline (por defecto), download o base64 |
filename |
texto | no | el nombre del fichero, sin extensión |
Con base64, data es {id, client_id, to, filename, content_type, size, base64}, como en GET /v3/calls/{type}/{id}/recording.
Errores propios: 404 Call not found, 404 Recording not found.
SMS#
Estados de un SMS#
Cada envío (POST /v3/sms) puede ir a varios destinatarios. El envío tiene un estado y cada destinatario, el suyo.
Estado del envío (GET /v3/sms/sends/{id}) |
Qué es |
|---|---|
scheduled |
programado para más tarde |
in_progress |
enviándose, o esperando los informes de entrega |
completed |
terminado: todos los destinatarios tienen resultado (o pasaron 15 días) |
failed |
falló entero |
cancelled |
se canceló antes de salir |
Estado de un destinatario (GET /v3/sms) |
Qué es |
|---|---|
pending |
aún no ha salido hacia el operador |
sent |
salió y el operador no ha mandado todavía el informe de entrega. Algunas rutas no dan informe: entonces se queda en sent |
delivered |
entregado en el teléfono |
failed |
no se entregó; el motivo, en error_code |
POST /v3/sms — enviar SMS#
POST https://api.mundosms.es/v3/sms
Permiso: write, sms o sendsms.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
to |
texto o lista | sí | los destinatarios |
text |
texto | sí | el mensaje |
from |
texto | no | el remitente: de 1 a 11 caracteres |
client_id |
texto | no | tu referencia, hasta 50 caracteres |
date_scheduled |
fecha | no | cuándo enviarlo; sin ella, ahora. Una fecha que no vale da 400 (no se envía) |
url_callback |
texto | no | URL tuya (https://, pública, hasta 150 caracteres) a la que avisamos del informe de entrega de cada destinatario (qué llega). Sin ella, la URL de avisos de tu cuenta, si la tienes |
route |
entero | no | la ruta: 1, 2, 3 o 4 |
concatenated |
sí/no | no | permitir mensajes de más de 160 caracteres (varias partes) |
unicode |
sí/no | no | enviar en Unicode (emojis, alfabetos no latinos; 70 caracteres por parte) |
keep_sms_size |
sí/no | no | no partir el mensaje: recortarlo a una parte |
expire_secs |
entero | no | segundos tras los que el operador deja de intentarlo |
type |
texto | no | sms (por defecto) o rcs_simple |
replace_vars, var1 … var8 |
texto | no | un texto distinto para cada destinatario (abajo) |
gsmcharset_table, gsmcharset_extension |
no | tabla de caracteres |
Petición:
POST /v3/sms Content-Type: application/json {"to":["34600123456","34600123457"],"text":"Tu cita es mañana a las 10:00. Responde NO para anularla.","from":"Clinica","client_id":"cita-88123"}
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":71234567,"client_id":"cita-88123","state":"in_progress","cost":0.14,"balance":120.21}}
id es nuestro identificador del envío, para GET /v3/sms/sends/{id}, GET /v3/sms y POST /v3/sms/sends/{id}/send-now. state es in_progress o
scheduled (con date_scheduled).
Un texto distinto para cada destinatario (replace_vars y var1 … var8):
- En
replace_varsvan los marcadores que quieras sustituir, separados por|. El marcador es el texto que tú elijas ([NOMBRE],#CITA#…): se busca tal cual entext. - En
var1van los valores del primer marcador, uno por destinatario y en el mismo orden queto, separados por|; envar2, los del segundo, y así hasta ocho marcadores. - Cada destinatario paga según la longitud de su texto, ya sustituido.
{"to":["34600123456","34600123457"],"text":"Hola [NOMBRE], te esperamos el [DIA].","from":"MiClinica", "replace_vars":"[NOMBRE]|[DIA]","var1":"Ana|Luis","var2":"lunes|martes"}
Ana recibe «Hola Ana, te esperamos el lunes.» y Luis, «Hola Luis, te esperamos el martes.».
Errores propios: 400 Parameter to not valid, 400 Parameter from not valid, 400 Parameter client_id not valid,
400 Parameter date_scheduled not valid, 400 Parameter route not valid, 402 Insufficient credit,
403 RCS not enabled for this account.
POST /v3/sms/certified — enviar un SMS certificado#
POST https://api.mundosms.es/v3/sms/certified
Un SMS con certificado de envío y entrega con validez como prueba. Mismos parámetros y respuesta que POST /v3/sms, más:
Permiso: write, sms o sendsms_cert.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
cert_name |
texto | sí | a nombre de quién se emite el certificado |
cert_type |
texto | no | el tipo de certificado (D por defecto) |
cert_tax_id |
texto | no | NIF/CIF del titular |
cert_language |
texto | no | idioma del certificado (ES por defecto) |
cert_email |
texto | no | correo al que se envía el certificado |
Va siempre por la ruta 1 (route se ignora). Ojo: el id de un SMS certificado es de otra serie que el de POST /v3/sms;
GET /v3/sms/sends/{id} y GET /v3/sms no lo encuentran. Por la API no se puede consultar: el certificado se envía al correo de
cert_email.
POST /v3/sms/quote — calcular el coste antes de enviar#
POST https://api.mundosms.es/v3/sms/quote
Mismos parámetros que POST /v3/sms; no envía nada.
Permiso: read, sms o quotesms.
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"cost":0.14,"balance":120.35}}
cost es lo que costaría el envío y balance, tu saldo. Errores propios: 400 Parameter to not valid (también si algún destino no
tiene precio).
GET /v3/sms/sends — estado de tus envíos#
GET https://api.mundosms.es/v3/sms/sends Pruébalo
Permiso: read, sms o getreport.
También: GET /v3/sms/sends/{id} — uno solo, por su id.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
id |
lista | sí, o client_id |
nuestros ids de envío, uno o varios, separados por comas |
client_id |
lista | sí, o id |
tus referencias, una o varias, separadas por comas |
Hasta 100 ids y referencias por petición.
Petición:
GET /v3/sms/sends?id=71234567,71234568Respuesta (200):
{ "status": "success", "status_code": "0", "message": "OK", "data": { "results": 2, "sms": [ {"id":71234567,"client_id":"cita-88123","state":"completed","delivered":["34600123456"],"failed":["34600123457"]}, {"id":71234568,"client_id":null,"error":{"status_code":"4","message":"SMS not found"}} ] } }
Cada envío que no existe lleva su error y la respuesta sigue siendo 200. Con uno solo
(GET /v3/sms/sends/71234567), si no existe: 404 SMS not found. El detalle por destinatario, con sus horas, lo da
GET /v3/sms con send_id.
Estados del envío (state): scheduled, in_progress, completed, failed y cancelled.
Errores propios: 400 Parameter id not valid (tu referencia va en client_id), 400 Too many ids, 404 SMS not found.
POST /v3/sms/sends/{id}/send-now — enviar ya un envío programado#
POST https://api.mundosms.es/v3/sms/sends/{id}/send-now
Adelanta a ahora un envío programado (date_scheduled) que aún no ha salido.
Permiso: write, sms o scheduled_sendings.
También: POST /v3/sms/sends/{id}/cancel — cancelarlo: no sale y se devuelve el saldo.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
id |
entero | sí | nuestro id del envío (en la ruta). Si solo tienes tu referencia, búscalo antes con GET /v3/sms/sends?client_id=… |
Petición:
POST /v3/sms/sends/71234570/send-nowRespuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":71234570,"client_id":"campana-black-friday","state":"in_progress"}}
Con /cancel, state es cancelled.
Errores propios: 404 SMS not found, 409 SMS already sent, 409 SMS already cancelled.
GET /v3/sms — SMS enviados, uno por destinatario#
GET https://api.mundosms.es/v3/sms Pruébalo
Los SMS enviados, un elemento por destinatario, con su estado y las horas de cada paso. Sirve para «los SMS de este contacto», para ver qué pasó con un envío o para sincronizar los SMS con un CRM.
Cada elemento es un SMS de un envío a un destinatario: se identifica por send_id + to.
Si un SMS no se entrega, a veces se reintenta por otra ruta sin coste para ti. Sale una sola vez:
- con las horas de creación y envío de cuando lo mandaste;
- con el estado del intento que mejor fue (
delivered, luegosent, luegopending, luegofailed; si empatan, el primero); - con la hora real del informe de entrega.
state filtra por ese estado: un SMS que falló y se entregó al reintentar es delivered.
Permiso: read, sms o getreport.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
cursor |
texto | no | el next_cursor de la página anterior: la página siguiente |
from_id |
entero | no | lo mismo que cursor, como número (por compatibilidad) |
limit |
entero | no | 1-500, 50 por defecto |
order |
texto | no | asc o desc |
from_datetime, to_datetime |
fecha | no | por hora de creación: desde (incluida) y hasta (sin incluir) |
number |
texto | no | un destinatario |
send_id |
entero | no | los de un envío (el id que devolvió POST /v3/sms) |
client_id |
texto | no | los del envío con esa referencia tuya |
state |
texto | no | pending, sent, delivered o failed |
include_text |
sí/no | no | true (por defecto): con el texto de cada mensaje |
Petición:
GET /v3/sms?number=34600123456&order=desc&limit=10Respuesta (200):
{ "status": "success", "status_code": "0", "message": "1 results", "data": { "results": 1, "messages": [ { "send_id": 71234567, "client_id": "cita-88123", "from": "Clinica", "to": "34600123456", "text": "Tu cita es mañana a las 10:00. Responde NO para anularla.", "parts": 1, "credits": 0.07, "state": "delivered", "error_code": null, "date_created": "2026-11-20 09:00:00.412", "date_created_iso": "2026-11-20T09:00:00.412+01:00", "date_sent": "2026-11-20 09:00:01.030", "date_sent_iso": "2026-11-20T09:00:01.030+01:00", "date_accepted": "2026-11-20 09:00:01.311", "date_accepted_iso": "2026-11-20T09:00:01.311+01:00", "date_report": "2026-11-20 09:00:04.870", "date_report_iso": "2026-11-20T09:00:04.870+01:00", "date_operator": "2026-11-20 09:00" } ], "has_more": false, "next_from_id": null, "next_cursor": null } }
| Campo | Qué es |
|---|---|
send_id, to |
el envío al que pertenece y el destinatario: juntos identifican el SMS |
client_id |
tu referencia del envío |
parts, credits |
en cuántas partes salió y lo que costó (los reintentos no se cobran) |
state, error_code |
ver Estados de un SMS; error_code solo si falló |
date_created |
cuándo lo recibimos |
date_sent |
cuándo salió hacia el operador |
date_accepted |
cuándo lo aceptó el operador |
date_report |
cuándo llegó el informe de entrega |
date_operator |
la hora de entrega que pone el operador en su informe, a minuto (AAAA-MM-DD hh:mm, hora de Madrid) |
Errores propios: 400 Parameter <nombre> not valid (con detail).
GET /v3/sms/replies — respuestas a tus SMS#
GET https://api.mundosms.es/v3/sms/replies Pruébalo
Los SMS que te contestan los destinatarios, con el envío al que responden.
Hoy no hay SMS de vuelta: ningún número recibe SMS, así que la lista sale vacía. La ruta se mantiene por compatibilidad.
Permiso: read, sms o getreport.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
cursor |
texto | no | el next_cursor de la página anterior: la página siguiente |
from_id |
entero | no | lo mismo que cursor, como número (por compatibilidad) |
limit |
entero | no | 1-500, 50 por defecto |
order |
texto | no | asc o desc |
from_datetime, to_datetime |
fecha | no | por hora de recepción |
number |
texto | no | quien responde |
send_id |
entero | no | las respuestas a un envío |
Petición:
GET /v3/sms/replies?order=asc&limit=100La página siguiente, con cursor = el next_cursor de esta. Hoy la lista sale vacía (results 0); así es cada respuesta
cuando las haya.
Respuesta (200):
{ "status": "success", "status_code": "0", "message": "1 results", "data": { "results": 1, "replies": [ { "from": "34600123456", "to": "34600999888", "text": "NO", "date_received": "2026-11-20 09:12:40.000", "date_received_iso": "2026-11-20T09:12:40.000+01:00", "reply_to": {"send_id": 71234567} } ], "has_more": false, "next_from_id": 30111, "next_cursor": "30111" } }
reply_to es el envío al que responde (send_id), o null si no se pudo saber. El SMS es el de ese envío a quien responde:
en GET /v3/sms, send_id y to = el from de la respuesta. to es nuestro número que recibió la respuesta.
Errores propios: 400 Parameter <nombre> not valid (con detail).
NumCheck#
POST /v3/numchecks — comprobar un número de móvil#
POST https://api.mundosms.es/v3/numchecks
Comprueba si un móvil existe y está activo y en qué operador está, sin llamarlo ni enviarle nada. El resultado llega a tu
url_callback.
Permiso: write, numcheck o numcheck.
| Parámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
number |
texto | sí | el número, en formato internacional. Uno por petición |
url_callback |
texto | no | URL tuya (https://, pública, hasta 150 caracteres) a la que enviamos el resultado (qué llega) |
client_id |
texto | no | tu referencia, hasta 30 caracteres |
Petición:
POST /v3/numchecks Content-Type: application/json {"number":"34600123456","url_callback":"https://crm.ejemplo.com/numcheck","client_id":"limpieza-nov"}
Respuesta (200):
{"status":"success","status_code":"0","message":"OK","data":{"id":551230,"client_id":"limpieza-nov","cost":0.02,"balance":120.33}}
Errores propios: 400 Parameter number not valid (también con una lista: es uno por petición), 402 Insufficient credit.
WhatsApp#
Envía WhatsApp desde tu sistema con el número de tu empresa conectado en el panel (WhatsApp → Números). La autenticación es la de toda la API: una clave de API creada en el panel (API y Soporte → Claves de API) con permiso de WhatsApp.
- Dirección:
https://api.mundosms.es/v3/whatsapp/…(las rutas, abajo). - Cabeceras:
Authorization: Bearer <token>y, si tu clave exige firma,X-TimestampyX-Signature. - En
GET, los parámetros van en la query; enPOST, en el cuerpo JSON. - Respuesta: JSON con
status(success|error),status_code("0"= correcto),message,detailen algunos errores, y los datos dentro dedata. Cada respuesta lleva su código HTTP (tabla de códigos, abajo).
Las rutas de WhatsApp#
| ruta | qué hace | permiso |
|---|---|---|
GET /v3/whatsapp/numbers |
tus números de WhatsApp | whatsapp_numbers |
GET /v3/whatsapp/templates |
las plantillas de un número y su estado | whatsapp_templates |
POST /v3/whatsapp/messages |
enviar un mensaje | whatsapp_send |
GET /v3/whatsapp/messages/{message_id} |
el estado de un mensaje | whatsapp_status |
POST /v3/whatsapp/campaigns |
crear un envío masivo | whatsapp_campaign |
GET /v3/whatsapp/campaigns/{campaign_id} |
el estado de un envío masivo | whatsapp_campaign |
POST /v3/whatsapp/campaigns/{campaign_id}/pause |
pausarlo (también /resume y /cancel) |
whatsapp_campaign |
Permisos de WhatsApp#
| permiso | qué permite |
|---|---|
whatsapp |
todo lo de WhatsApp |
whatsapp_send |
enviar mensajes |
whatsapp_campaign |
crear, consultar y controlar envíos masivos |
whatsapp_status, whatsapp_templates, whatsapp_numbers |
las consultas de cada ruta |
all |
todo, como en el resto de la API |
Una clave con read o write a secas (las de SMS o voz) no entra a WhatsApp. Con «Todo» en la ficha de la
clave, o marcando a la vez «Todas las consultas» y «Todas las acciones», se guarda como all, y all sí entra.
Firma, ejemplos y errores de autenticación#
Son los de toda la API: La firma, Ejemplos completos (la función mundosms() vale tal
cual: mundosms("GET", "/v3/whatsapp/templates", {"account_id": 12})) y
Errores de autenticación. Dos diferencias:
- En WhatsApp, cada petición firmada vale una sola vez con cualquier clave que firme, exija
tso no: para reintentar, vuelve a firmar con unX-Timestampnuevo. - Sin permiso para la ruta, el
403dice cuál falta:Not allowed whatsapp_send.
Para n8n hay un workflow listo para importar, con la firma hecha: n8n-whatsapp-plantillas-firmada.json (pídenoslo si
no lo tienes).
Códigos de WhatsApp: status_code y HTTP#
| HTTP | status_code |
qué pasa | qué hacer |
|---|---|---|---|
| 200 | 0 |
correcto | — |
| 400 | 3 |
parámetros que faltan o no valen (detail dice qué) |
corrige la petición |
| 401, 403, 409 | 3 |
autenticación, permiso o petición repetida (tabla anterior) | — |
| 404 | 4 |
no encontrado en tu cuenta (número, plantilla, mensaje, envío masivo o ruta) | — |
| 402 | 5 |
sin saldo (Insufficient Credit) |
recarga |
| 422 | 6 |
la plantilla no cumple las reglas de WhatsApp | — |
| 429 | 7 |
demasiadas peticiones seguidas | reintenta pasados los segundos de la cabecera Retry-After |
| 409 | 8 |
fuera de las 24 h: el cliente no te ha escrito en las últimas 24 h | manda una plantilla |
| 402 | 9 |
el número no tiene la cuota mensual activa (data.reason: pending o expired) |
actívala en el panel |
| 402 | 10 |
mensajes del mes agotados y el número no admite exceso (data.used, data.included) |
activa el exceso en el panel o espera al día 1 |
| 202 | 11 |
WhatsApp no contestó y el mensaje puede haber salido | consulta GET /v3/whatsapp/messages/{message_id} con data.id antes de reintentar |
| 422 | 12 |
WhatsApp lo rechazó (data.whatsapp_error_code, p. ej. 131026: ese teléfono no tiene WhatsApp) |
no reintentes |
| 503 | 12 |
WhatsApp lo rechazó por un límite pasajero (data.retry es true) |
reintenta pasados los segundos de Retry-After |
| 503 | 2 |
sin conexión con WhatsApp en ese momento (data.retry es true) |
reintenta en unos segundos |
| 500 | 2 |
error interno | — |
- Si el mensaje llegó a crearse, el error trae su
data.id.detaillleva el texto original del error para el soporte, sin traducir. - El 11 va con 202 a propósito: el mensaje puede haber salido, y un 5xx haría que muchas herramientas lo
repitieran solas (en n8n, «Retry on fail») y el cliente lo recibiría dos veces. Si tu herramienta reintenta, que solo
lo haga con
data.retryatrue. Si un 11 no traedata.id(un fichero que tardó más de 50 s en descargarse y subirse), míralo en el Historial del panel.
GET /v3/whatsapp/numbers — tus números#
GET https://api.mundosms.es/v3/whatsapp/numbers
Permiso: whatsapp o whatsapp_numbers.
curl -s https://api.mundosms.es/v3/whatsapp/numbers -H "Authorization: Bearer $TOKEN"
{"status":"success","status_code":"0","message":"OK", "data":{"numbers":[{"account_id":12,"number":"+34 881 92 28 02","name":"Clínica Sonríe", "quality":"GREEN","messaging_limit":"TIER_1K","coexistence":true, "monthly_fee":{"state":"active","active":true,"until":"2026-12-10","auto_renew":true}, "monthly_usage":{"used":2350,"included":10000,"overage_allowed":true}}]}}
account_idsirve para elegir número en las demás rutas; si no lo indicas, se usa el primero.monthly_fee.state:exempt,trial(primer mes gratis),active,pendingoexpired. Sin la cuota activa, los envíos dan 9.monthly_usage: los mensajes de conversación del mes (los que recibes y los que contestas);includedesnullsi el número no tiene límite. Agotados (included) y conoverage_allowedafalse, los textos dan 10. Las plantillas se cobran aparte y siguen saliendo.
GET /v3/whatsapp/templates — plantillas y su estado#
GET https://api.mundosms.es/v3/whatsapp/templates
Permiso: whatsapp o whatsapp_templates.
curl -s "https://api.mundosms.es/v3/whatsapp/templates?account_id=12" \ -H "Authorization: Bearer $TOKEN"
Devuelve data.templates. Cada una trae:
name,languageybody;category:utility,marketingoauthentication;status:approved,pendingorejected;vars: cuántos huecos{{1}},{{2}}… hay que rellenar.
Las plantillas se crean en el panel (WhatsApp → Plantillas), también las que llevan una foto, un vídeo o un documento en la cabecera.
POST /v3/whatsapp/messages — enviar un mensaje#
POST https://api.mundosms.es/v3/whatsapp/messages
Permiso: whatsapp o whatsapp_send.
Todo envío lleva to (el teléfono, con prefijo de país) y type. Esto es lo que puedes enviar:
type |
qué recibe el cliente | cuándo |
|---|---|---|
template |
una plantilla aprobada, con su cabecera (texto, foto, vídeo o documento), sus botones y los códigos de las de autenticación | siempre |
text |
un texto, hasta 4.096 caracteres | 24 h |
image, video, audio, document, sticker |
una foto, un vídeo, un audio o nota de voz, un documento o un sticker | 24 h |
location |
un punto en el mapa (tu tienda, la clínica…) | 24 h |
contacts |
una o varias tarjetas de contacto para guardar | 24 h |
buttons |
un texto con hasta 3 botones de respuesta | 24 h |
list |
un menú de hasta 10 opciones | 24 h |
cta_url |
un texto con un botón que abre una web | 24 h |
location_request |
un botón para que el cliente te envíe su ubicación | 24 h |
reaction |
un emoji sobre un mensaje del cliente | 24 h |
«24 h» quiere decir solo dentro de las 24 h desde el último mensaje del cliente; fuera, vuelve el código 8 y hace
falta una plantilla. Cualquier tipo menos reaction puede citar un mensaje con reply_to (ver más abajo).
Para escribir primero a un cliente, o pasadas 24 h desde su último mensaje, una plantilla:
curl -s https://api.mundosms.es/v3/whatsapp/messages \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"to":"34600000001","type":"template", "template":{"name":"confirmacion_cita","language":"es","vars":["Ana","martes 16","17:30"]}, "client_id":"cita-881"}'
Si el cliente te escribió en las últimas 24 h, también texto libre:
-d '{"to":"34600000001","type":"text","text":"Hola Ana, ¿en qué te ayudamos?"}'
Todos los tipos responden igual:
{"status":"success","status_code":"0","message":"OK", "data":{"id":123,"wamid":"wamid.HBgL…","credits":0.2}}
id: el del mensaje, para consultar su estado.wamid: el identificador de WhatsApp.credits: lo que se ha descontado de tu saldo. Una plantilla cuesta créditos; lo demás entra en los mensajes del mes, y pasado el límite se cobra como exceso si el número lo admite.to: con prefijo de país. Valen+y espacios, y un móvil español de 9 cifras se completa con 34.client_id: tu referencia libre (hasta 100 caracteres), que vuelve al consultar el mensaje.account_id: el número desde el que sale; si no lo indicas, el primero.- Si algo no cumple los límites de WhatsApp (un botón de más, un título largo), vuelve
400ydetaildice qué.
Plantillas con cabecera, botones y códigos
Además de los huecos del cuerpo (vars, en orden), una plantilla puede necesitar más datos, según cómo se aprobó:
-d '{"to":"34600000001","type":"template", "template":{"name":"cita_con_enlace","language":"es","vars":["Ana","martes 16"], "header":"Recordatorio","buttons":[{"index":0,"url":"cita/881"}]}}' -d '{"to":"34600000001","type":"template", "template":{"name":"factura_mensual","language":"es","vars":["881"], "header":{"type":"document","filename":"factura-881.pdf", "url":"https://erp.ejemplo.es/facturas/881.pdf"}}}' -d '{"to":"34600000001","type":"template", "template":{"name":"codigo_acceso","language":"es","code":"482913"}}'
header: si la cabecera de la plantilla es de texto con un hueco, el texto que va en él. Si es una foto, vídeo o documento, el fichero:{"type":"image"|"video"|"document","url":…,"filename":…}(obase64en vez deurl), con las mismas reglas que los ficheros de abajo. Una plantilla con documento en la cabecera no sale sin él: vuelve400diciéndolo.- Las plantillas con foto, vídeo o documento en la cabecera se crean en el panel (WhatsApp → Plantillas → Nueva, «Cabecera»): WhatsApp pide un fichero de ejemplo para revisarlas, y luego en cada envío va el de verdad.
buttons: los botones que llevan un dato, cada uno por su posición (index, empezando en 0):url(lo que se añade al final de la dirección del botón),payload(lo que te llega cuando el cliente pulsa una respuesta rápida) ocoupon_code(el cupón de un botón de copiar código).code: en las plantillas de autenticación, el código. Va al texto y al botón de copiar a la vez.- La categoría de la plantilla es la que WhatsApp le aprobó: no se elige al enviar.
Documentos, fotos, vídeos, audios y stickers
El fichero puede ir de dos maneras: con su dirección (url), y lo descargamos nosotros, o dentro del JSON en
base64. Lo más cómodo, si el fichero ya está en tu servidor o en un almacenamiento como S3, es la dirección:
-d '{"to":"34600000001","type":"document","client_id":"fra-881", "document":{"filename":"factura-881.pdf","url":"https://erp.ejemplo.es/facturas/881.pdf", "caption":"Tu factura de noviembre"}}' -d '{"to":"34600000001","type":"document","client_id":"fra-881", "document":{"filename":"factura-881.pdf","base64":"JVBERi0xLjQK…", "caption":"Tu factura de noviembre"}}' -d '{"to":"34600000001","type":"image", "image":{"url":"https://cdn.ejemplo.es/obras/salon.jpg","caption":"Así queda"}}' -d '{"to":"34600000001","type":"audio", "audio":{"filename":"respuesta.ogg","base64":"T2dnUwACAAAA…","voice":true}}'
type |
formatos | tamaño máximo | caption |
|---|---|---|---|
document |
pdf, doc, docx, xls, xlsx, ppt, pptx, txt |
16 MB | sí |
image |
jpg, png |
5 MB | sí |
video |
mp4, 3gp |
16 MB | sí |
audio |
ogg (opus), mp3, m4a, aac, amr |
16 MB | no |
sticker |
webp |
500 KB | no |
url(olink, como lo llama WhatsApp): la dirección del fichero. Tiene que ser https y de un servidor público; vale un enlace firmado que caduque (de S3, por ejemplo), siempre que siga vivo unos minutos. Se descarga una vez, en el momento del envío, y si no se puede el envío no sale y vuelve el código3con el motivo endetail: la dirección da un error (HTTP 404), devuelve una página web en vez del fichero (un enlace caducado o que pide iniciar sesión), tarda más de 15 s, pasa del tamaño máximo o apunta a una red privada.base64: el fichero entero, en vez deurl. Se admiten saltos de línea y el prefijodata:application/pdf;base64,. Uno de los dos, no los dos a la vez.filename: el tipo sale de su extensión, y es el nombre que verá el cliente en los documentos. Conbase64es obligatorio en los documentos; conurles opcional (si falta, se usa el nombre que dé tu servidor y, si no da ninguno,documento.pdf). En las fotos y los stickers es opcional, porque el tipo se reconoce por el contenido.voice: true: el audio llega como nota de voz, como si la hubieras grabado en el móvil. Tiene que serogg(opus).caption: el texto que acompaña al fichero, opcional, hasta 1.024 caracteres.- Se comprueba que el contenido sea lo que dice el nombre: un fichero que no es un PDF de verdad pero se llama
.pdfvuelve con código3, ydetaildice el motivo. Lo mismo un tipo no admitido o un fichero demasiado grande. - Si WhatsApp no acepta el fichero al subirlo, vuelve el código
12condata.whatsapp_error_code, y no se ha enviado nada. - Si la descarga y la subida tardan más de 50 s, vuelve el código
11sindata.id: el envío puede completarse después. No lo repitas sin mirar antes el Historial del panel. - Una vez enviado, el fichero aparece en el Historial del panel como si lo hubieras mandado desde allí. También el que
enviaste por
url: el Historial enseña el fichero que se envió, aunque tu enlace caduque después.
Ubicación y contactos
-d '{"to":"34600000001","type":"location","location":{"latitude":42.8782,"longitude":-8.5448, "name":"Clínica Sonríe","address":"Rúa Nova 12, Santiago"}}' -d '{"to":"34600000001","type":"contacts", "contacts":[{"name":"Recepción Clínica Sonríe","emails":["citas@clinicasonrie.es"], "phones":[{"phone":"+34 881 92 28 02","type":"WORK"}]}]}'
location:latitudeylongitudeen grados decimales;nameyaddressson opcionales.contacts: una lista de 1 a 20 tarjetas. Solo el nombre es obligatorio. Puedes darnamecomo texto o como{"formatted_name","first_name","last_name"}, y añadirphones,emails,urls,org(company,department,title),addressesybirthday(AAAA-MM-DD). Si añadeswa_ida un teléfono, el cliente ve el botón de escribirle por WhatsApp.
Botones, listas y enlaces
-d '{"to":"34600000001","type":"buttons", "buttons":{"text":"¿Confirmas tu cita del martes a las 17:30?","footer":"Clínica Sonríe", "options":[{"id":"si","title":"Sí, confirmo"}, {"id":"cambiar","title":"Cambiar la hora"}]}}' -d '{"to":"34600000001","type":"list", "list":{"text":"¿Qué día te viene mejor?","button":"Ver días", "sections":[{"title":"Esta semana","rows":[ {"id":"mar","title":"Martes","description":"de 16:00 a 20:00"}, {"id":"jue","title":"Jueves","description":"de 9:00 a 14:00"}]}]}}' -d '{"to":"34600000001","type":"cta_url", "cta_url":{"text":"Tu factura de noviembre ya está lista.","button":"Ver factura", "url":"https://www.ejemplo.es/f/881"}}' -d '{"to":"34600000001","type":"location_request", "location_request":{"text":"¿Dónde te recogemos?"}}'
buttons: el texto (hasta 1.024 caracteres) y de 1 a 3options, cada una con sutitle(hasta 20 caracteres, distintos entre sí) y suid(lo que te llega cuando el cliente pulsa; si no lo das, es el título). Opcionales:header(un texto de hasta 60 caracteres, o una foto, vídeo o documento como en las plantillas) yfooter(hasta 60).list: el texto (hasta 4.096), el botón que abre el menú (button, hasta 20) y las opciones: hasta 10 en total, ensections(cada una con sutitle, hasta 24) o, si es una sola, directamente enrows. Cada opción llevatitle(hasta 24),id(hasta 200) y, si quieres,description(hasta 72). Opcionales:header(texto) yfooter.cta_url: el texto, el botón (button, hasta 20) y la dirección que abre (url,httpohttps). Así la dirección no aparece en el texto. Opcionales:header(texto) yfooter.location_request: el texto. El cliente ve un botón para enviar su ubicación, y te llega como cualquier ubicación.- Lo que el cliente elige te llega por el webhook (
respuesta_botonorespuesta_lista, con elidde la opción), igual que su ubicación (ubicacion). Está documentado en https://www.mundosms.es/whatsapp-webhook.
Reacciones y responder citando
-d '{"to":"34600000001","type":"reaction","reaction":{"message_id":812,"emoji":"👍"}}' -d '{"to":"34600000001","type":"text","text":"Sí, abrimos el sábado de 10 a 14.","reply_to":812}'
reaction: un emoji sobre un mensaje del cliente de los últimos 30 días.reply_to: el mensaje que se cita, como cuando en WhatsApp mantienes pulsado y das a «Responder». Vale en cualquier tipo menosreaction, y puede ser un mensaje del cliente o uno tuyo.- En los dos, el mensaje se indica con su id (el que te llega en el webhook o te devolvió el envío) o con su
wamid. Tiene que ser de la conversación con ese mismoto; si no, vuelve404.
GET /v3/whatsapp/messages/{message_id} — estado de un mensaje#
GET https://api.mundosms.es/v3/whatsapp/messages/{message_id}
Permiso: whatsapp o whatsapp_status.
curl -s https://api.mundosms.es/v3/whatsapp/messages/123 -H "Authorization: Bearer $TOKEN"
{"status":"success","status_code":"0","message":"OK", "data":{"id":123,"to":"34600000001","type":"template","template":"confirmacion_cita", "state":"delivered","error_code":null,"error":null,"wamid":"wamid.HBgL…","credits":0.2, "client_id":"cita-881", "date_created":"2026-11-11 10:30:00.000","date_created_iso":"2026-11-11T10:30:00.000+01:00", "date_updated":"2026-11-11 10:30:04.000","date_updated_iso":"2026-11-11T10:30:04.000+01:00"}}
Los valores de state:
pending: creado. Si se queda así tras un 11, WhatsApp no ha dicho nada todavía.accepted→sent→delivered→read.failed: WhatsApp no pudo entregarlo, conerror_codeyerror.rejected: no salió.excluded: el destinatario se dio de baja.
Las fechas salen como en el resto de la API: en hora de Madrid con milisegundos, y la misma en ISO 8601 con su zona
(_iso). Un mensaje que no es de tu cuenta, o que no existe, da 404.
POST /v3/whatsapp/campaigns — crear un envío masivo#
POST https://api.mundosms.es/v3/whatsapp/campaigns
Permiso: whatsapp o whatsapp_campaign.
También: GET /v3/whatsapp/campaigns/{campaign_id} — su estado; POST /v3/whatsapp/campaigns/{campaign_id}/pause — pausarlo; POST /v3/whatsapp/campaigns/{campaign_id}/resume — reanudarlo; POST /v3/whatsapp/campaigns/{campaign_id}/cancel — cancelarlo.
Crear (hasta 10.000 destinatarios por llamada; para más, varias llamadas):
curl -s https://api.mundosms.es/v3/whatsapp/campaigns \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name":"Recordatorio citas lunes", "template":{"name":"confirmacion_cita","language":"es"}, "recipients":[{"to":"34600000001","vars":["Ana","lunes 6","10:00"]}, {"to":"34600000002","vars":["Luis","lunes 6","11:30"]}], "date_scheduled":"2026-10-05T18:00:00+02:00"}'
- Programar:
date_scheduled, como en SMS y VozPush (ISO 8601 con zona, o en hora de Madrid); sin ella, sale ya.scheduled_at, el nombre de antes, sigue valiendo; los dos con fechas distintas dan400. - Respuesta: en
data,campaign_id,recipients,rejected_rows(teléfonos no válidos o repetidos) ystate. - Consultar:
GET /v3/whatsapp/campaigns/45. Devuelve endata:name,state,stop_reasonydate_scheduled(con sudate_scheduled_iso;scheduled_atsigue saliendo);- los contadores
total,delivered,read,failed,excluded_optoutypending.
- Controlar:
POST /v3/whatsapp/campaigns/45/pause,/resumeo/cancel, sin cuerpo. - Estados:
draft,scheduled,sending,paused,finished,cancelledyerror. - Cobro: cada mensaje se cobra al salir, como un envío de plantilla. Sin saldo, el envío se pausa, y
stop_reasondice por qué. - Las plantillas con foto, vídeo o documento en la cabecera todavía no se pueden usar en un envío masivo: envíalas de
una en una con
POST /v3/whatsapp/messages.
Los contactos que respondieron BAJA o STOP se excluyen automáticamente de los envíos.
Lo que todavía no hace la API de WhatsApp#
- Crear plantillas: se crean en el panel.
- Formularios de WhatsApp (Flows), catálogo y productos, y plantillas en carrusel: necesitan prepararse antes en WhatsApp. Si los necesitas, escríbenos.
- Pedir una dirección postal con el formulario de WhatsApp: solo existe en India.
- Botón para que el cliente te llame por WhatsApp.
- Recibir los mensajes de tus clientes: eso no va por la API, sino por el webhook. Se configura en el panel y está documentado en https://www.mundosms.es/whatsapp-webhook.
Mensajes que te llegan (webhook)#
Lo que te escriben tus clientes, y el estado de lo que envías, no se pide a la API: te lo mandamos a tu servidor. Se activa
en el panel, en WhatsApp · Números → Detalle del número → «Destino de este número»: la URL (https), los eventos que
quieres y, al guardar, el secreto de la firma (whsec_…, se enseña una sola vez).
Cada evento es un POST con JSON, firmado: X-MundoSMS-Signature: t=<segundos unix>,v1=<firma>, donde v1 es el
HMAC-SHA256 en hexadecimal, con tu secreto, de t + . + el cuerpo tal cual llega. Comprueba la firma y que t no tenga
más de 5 minutos, y contesta un 2xx en menos de 10 segundos (si no, se reintenta, durante unas 22 horas). Un mensaje de
texto de un cliente llega así (recortado: el evento completo, en la página del webhook):
POST /tu-webhook HTTP/1.1 Content-Type: application/json; charset=utf-8 X-MundoSMS-Signature: t=1795259645,v1=6187525619683fbe958b7f95559f00b121d0faab8582eb77d9a20ec683563409 X-MundoSMS-Event: mensaje.recibido X-MundoSMS-Event-Id: evt_01a1fdd03d4974f6b012ba27c925e4d6 { "id": "evt_01a1fdd03d4974f6b012ba27c925e4d6", "tipo": "mensaje.recibido", "creado": "2026-11-21T12:14:05.257+01:00", "numero": {"id": 1, "telefono": "+34 910 00 00 00", "phone_number_id": "106540352242922", "waba_id": "102290129340398"}, "datos": { "mensaje_id": 1, "wamid": "wamid.HBgLMzQ2MDAwMDAwMDEVAgASGBQzQUVGRTY0RDQ2", "contacto": "34600000001", "nombre_contacto": "Ana Pérez", "fecha": "2026-11-21T12:14:05.257+01:00", "responde_a": null, "historial": false, "conversacion": {"id": 1, "contacto": "34600000001", "estado": "abierta", "asignado_tipo": null, "asignado_sid": null}, "tipo": "texto", "texto": "Hola, ¿tenéis mesa para 4 esta noche?" } }
Para contestarle, POST /v3/whatsapp/messages con to = datos.contacto (y reply_to = datos.wamid si quieres citar
su mensaje). Los nombres del evento van en español, como en el panel. Hay más eventos (mensaje.estado con el estado de
lo que envías, respuesta_boton y respuesta_lista dentro de mensaje.recibido, conversacion.*, contacto.baja,
plantilla.estado, numero.*), y receptores completos que comprueban la firma en PHP, Python y Node, en
https://www.mundosms.es/whatsapp-webhook.
Buenas prácticas con WhatsApp#
- Permiso: escribe solo a quien ha aceptado recibir WhatsApp de tu empresa. Si te bloquean o te reportan, WhatsApp baja la calidad de tu número y reduce cuántos mensajes puedes enviar al día.
- Tipo de plantilla: usa plantillas de aviso (utility) para recordatorios, confirmaciones y avisos de servicio. Las promocionales (marketing) cuestan más y tienen límites de frecuencia por usuario.
- Reintentos: reintenta solo con
data.retryatrue, y con el código 11 (HTTP 202) consulta antes el estado.
Catálogo de errores#
Además de los errores de autenticación:
| HTTP | status_code |
message |
Dónde |
|---|---|---|---|
| 400 | "3" |
Required parameters missing |
cualquiera: falta un parámetro obligatorio |
| 400 | "3" |
Parameter <nombre> not valid |
cualquiera: el parámetro no vale; detail dice qué se espera |
| 400 | "3" |
Body not allowed / Query not allowed / Body not valid |
cuerpo en un GET, query en un POST, o un cuerpo que no es un objeto JSON |
| 400 | "3" |
Parameters not valid |
POST /v3/campaigns |
| 400 | "3" |
Too many ids |
GET /v3/sms/sends (más de 100) |
| 402 | "5" |
Insufficient credit |
lo que cuesta: SMS, VozPush, NumCheck, verificación de números |
| 403 | "3" |
Caller ID not verified |
el número que quieres presentar no es tuyo ni está verificado |
| 403 | "3" |
RCS not enabled for this account |
POST /v3/sms con type: "rcs_simple" |
| 404 | "4" |
Route not found |
la ruta no existe |
| 404 | "4" |
Call not found |
llamadas |
| 404 | "4" |
Recording not found |
grabaciones |
| 404 | "4" |
Extension not found |
extensiones, POST /v3/calls |
| 404 | "4" |
DID not found |
números |
| 404 | "4" |
Diagram not found |
diagramas, POST /v3/campaigns |
| 404 | "4" |
Voice file not found |
locuciones |
| 404 | "4" |
SMS not found |
GET /v3/sms/sends, send-now, cancel |
| 404 | "4" |
Campaign not found |
campañas de VozPush |
| 405 | "3" |
Method not allowed |
la ruta existe con otro verbo (cabecera Allow) |
| 409 | "3" |
Duplicated request |
una petición firmada con ts que ya había llegado |
| 409 | "3" |
Extension already exists |
POST /v3/extensions |
| 409 | "3" |
Extension not registered |
POST /v3/calls |
| 409 | "3" |
SMS already sent / SMS already cancelled |
send-now, cancel |
| 409 | "3" |
Voice file cannot be deleted / … yet |
DELETE /v3/voicefiles/{id} |
| 409 | "3" |
Not possible in the current state |
pausar, reanudar o cancelar una campaña |
| 429 | "7" |
Too many attempts / Too many requests |
demasiados intentos o peticiones: espera antes de reintentar |
| 500 | "2" |
Internal error |
error nuestro: reintenta más tarde |
| 500 | "2" |
Voice server unavailable / Voice server error |
la centralita no respondió: reintenta |
Cómo tratarlos:
- 400, 403, 404, 405, 409: no los reintentes tal cual: corrige la petición (o, en el 409
Duplicated request, mira Reintentos seguros). - 401: revisa el token, la firma y el reloj (
X-Timestamp). - 402: recarga saldo.
- 429 y 500: reintenta con espera creciente (1 s, 2 s, 4 s… hasta un minuto), firmando cada vez con un
X-Timestampnuevo. - Decide por el código HTTP y por
status_code; usamessagepara casos concretos (es estable) ydetailsolo para mostrarlo o registrarlo. - Guarda el
X-Request-Idde la respuesta: con él encuentras la petición en Logs API.
Uso responsable: pide una vez y guarda en tu base de datos#
La API sirve para traer los datos a tu sistema, no para consultarlos cada vez que los enseñas. Pide cada dato una sola vez, guárdalo en tu base de datos y trabaja desde ahí. Así tus pantallas van más rápido, no dependen de tu conexión ni de la nuestra, y puedes filtrar, exportar a CSV o sacar estadísticas sin pedirnos nada.
Ejemplos de mal uso:
- Pedir el historial de llamadas cada vez que se muestra. Sincroniza con el cursor
(Sincronizar llamadas sin perder ninguna) y enséñalas desde tu base de datos.
Para saber a quién devolver la llamada está
GET /v3/calls/missed, que ya trae el resumen. - Preguntar por el estado de un SMS que ya terminó (
deliveredofailed), o por el de un envío programado antes de su hora. Pregunta solo por los que siguen pendientes, y mejor aún: pasaurl_callbackenPOST /v3/smsy te avisamos de cada informe de entrega en cuanto llega (Avisos a tu URL). - Pedir el saldo antes de cada envío. Cada
POST /v3/smsdevuelvecostybalance: guárdalos y actualízalos con cada envío o compra. - Volver a comprobar con
POST /v3/numchecksun número que ya comprobaste. Guarda el resultado.
Por eso los listados van por páginas y con tope (Límites). En Logs API ves cuántas peticiones hace tu integración. Si pide mucho más de lo que necesita, nos pondremos en contacto contigo.
Límites#
| Ruta | limit por defecto |
limit máximo |
|---|---|---|
GET /v3/calls |
20 | 100 |
GET /v3/calls/missed |
100 | 500 (ventana: 7 días por defecto, 31 como mucho) |
GET /v3/calls/live |
100 | 500 |
GET /v3/numbers |
100 | 500 |
GET /v3/extensions |
sin limit: todas |
— |
GET /v3/diagrams |
50 | 500 |
GET /v3/sms, GET /v3/sms/replies |
50 | 500 |
GET /v3/sms/sends |
— | 100 ids o referencias por petición |
Otros límites:
X-Timestamp: a menos de 5 minutos de nuestra hora; con «Rechazar peticiones repetidas», cada petición firmada una sola vez.client_id: 50 caracteres en SMS, 30 en NumCheck, 20 en VozPush, 100 en WhatsApp.- Remitente de SMS (
from): de 1 a 11 caracteres. POST /v3/voicefilespor URL: 16 MB.POST /v3/callerid-validations: 10 intentos por número.- Para sincronizar, no hace falta preguntar más de una vez por minuto: usa el cursor y pide páginas grandes.
- Peticiones por minuto: hoy no hay un tope fijo. El
429solo lo dan la verificación de números (10 intentos por número) y WhatsApp (cuando Meta o nuestro servicio frenan los envíos, conRetry-After). Si te llega un429, espera lo que digaRetry-Aftero, si no lo trae, con tiempos crecientes.
Recetas para CRM y ERP#
Guía rápida: qué usar para cada cosa.
| Quiero… | Usa |
|---|---|
| Tener en mi CRM todas las llamadas, nuevas y terminadas | GET /v3/calls sin type, con cursor y stop_at_ongoing (receta). Si no hay nada nuevo, una sola petición |
| Saber a quién devolver la llamada | GET /v3/calls/missed: perdidas pendientes, una por número |
| Saber si una perdida concreta se devolvió | GET /v3/calls: cada perdida lleva followup |
| Ver con quién habla ahora una extensión (recepción) | GET /v3/calls/live?extension=… → other_party (receta) |
| Mostrar la ficha del cliente cuando llama | GET /v3/calls/live: las in en ringing, por from |
| Las llamadas y los SMS de un contacto | GET /v3/calls y GET /v3/sms con number (receta) |
| Los SMS que he enviado y cómo acabaron | GET /v3/sms con cursor, o con send_id / client_id para un envío |
| Las respuestas a mis SMS | GET /v3/sms/replies |
| Oír o guardar una grabación | GET /v3/calls/{type}/{id}/recording (format=mp3 si es para un iPhone) |
| Llamar desde una extensión | POST /v3/calls |
| Colgar una llamada | POST /v3/calls/live/{type}/{id}/hangup (si ya había colgado: changed: false, «Call already terminated») |
| Reintentar sin duplicar | Reintentos seguros |
| Ver qué ha pedido mi integración y qué le contestamos | Logs API, con el X-Request-Id |
Sincronizar llamadas sin perder ninguna#
El objetivo: tener en tu sistema todas las llamadas terminadas, una sola vez, sin depender de las horas.
- La primera vez, decide desde cuándo quieres el historial y pide
GET /v3/calls?from_datetime=2026-11-01&stop_at_ongoing=true&order=asc&limit=100. Sintypevienen entrantes, salientes y funciones, ordenadas por hora. - Guarda cada llamada por su
type+id: es la clave única en tu sistema, porque el mismoidpuede existir eniny enout. - Guarda
next_cursor. Mientrashas_moreseatrue, pide la página siguiente conGET /v3/calls?cursor=<next_cursor>&stop_at_ongoing=true&limit=100. - Cuando
has_moreseafalse, has terminado por ahora. En la siguiente sincronización (cada minuto, cada cinco…), haz una petición con el últimonext_cursor. Si no hay nada nuevo, contestaresults: 0y el mismo cursor.
Por qué stop_at_ongoing: una llamada en curso todavía no tiene fin, duración ni coste. Con stop_at_ongoing la página se
corta antes de la primera llamada en curso, así que tu cursor nunca la deja atrás: la recibirás terminada en una
sincronización posterior. Si una página llega con results: 0 y has_more: true, la primera llamada pendiente sigue en
curso: vuelve a preguntar más tarde con el mismo cursor.
Si prefieres llevar cada tipo por separado, también vale: type in u out con from_id/next_from_id, uno por tipo.
# Sincronización incremental de llamadas (usa la función mundosms() de «Ejemplos completos») def sincroniza(cursor): # cursor: el último next_cursor guardado (None la primera vez) while True: datos = {"stop_at_ongoing": "true", "limit": 100} if cursor: datos["cursor"] = cursor else: datos.update({"from_datetime": "2026-11-01", "order": "asc"}) http, r = mundosms("GET", "/v3/calls", datos) if http != 200: raise RuntimeError(r["message"]) for llamada in r["data"]["calls"]: guarda_llamada(llamada["type"], llamada) # idempotente: clave única (type, id) cursor = r["data"]["next_cursor"] or cursor guarda_cursor(cursor) if not r["data"]["has_more"]: return cursor # al día if r["data"]["results"] == 0: return cursor # la siguiente llamada sigue en curso: la próxima pasada sigue desde aquí
Con el SDK es un bucle: for llamada in api.todos("/calls", {"from_datetime": "2026-11-01", "stop_at_ongoing": True}).
En la primera descarga de un historial largo, una llamada en curso detiene el recorrido en ese punto hasta que termine (o
pasen 12 horas): no se pierde nada, la siguiente pasada sigue desde el mismo cursor. Si necesitas saber que la descarga
inicial ha terminado, es cuando una página llega con has_more: false.
Las llamadas y los SMS de un contacto#
Para la ficha de un cliente, con su número en formato internacional:
- llamadas:
GET /v3/calls?type=in&number=34600123456&order=desc&limit=20y lo mismo contype=out; - perdidas sin devolver:
GET /v3/calls?type=in&number=34600123456&status=missed&from_datetime=…y compara con las salientes a ese número posteriores; - SMS enviados:
GET /v3/sms?number=34600123456&order=desc; - SMS recibidos de ese número:
GET /v3/sms/replies?number=34600123456&order=desc(hoy no hay SMS de vuelta: sale vacía).
¿Con quién habla recepción?#
GET /v3/calls/live?extension=recepcion: si results es 0, la extensión está libre; si no, other_party es el número con
el que habla y state dice si aún está sonando (ringing) o en conversación (talking). Para un panel con todas las
extensiones, pide GET /v3/calls/live sin filtro y agrupa por party y por las patas de legs. Para mostrar la ficha del
cliente cuando entra una llamada, busca por from las llamadas in en ringing.
La bandeja de llamadas perdidas#
A quién llamar: GET /v3/calls/missed, sin parámetros, da los números con perdidas pendientes de los últimos 7 días, uno
por número, con cuántas veces llamó y cuándo.
- Es una foto, no una sincronización. Un número sale de la lista en cuanto alguien le atiende, así que pídela entera cada vez (cada pocos minutos basta).
- Para atender por orden de llegada, ordena por
first_missed. Si llamó varias veces, ahí va la primera. - Para el histórico completo (perdidas devueltas o no, con su
followup), sincroniza con el cursor ystatus=missed. Elfollowupde una perdida puede cambiar después: si lo guardas, vuelve a pedir las que tengaspending.
Reintentos seguros#
Una red que corta puede dejarte sin saber si una petición llegó. Cómo reintentar sin duplicar un envío:
- Consultas (
GET): reintenta sin más, firmando con unX-Timestampnuevo. - Envíos (
POST /v3/sms,POST /v3/campaigns,POST /v3/numchecks,POST /v3/whatsapp/messages): manda siempre unclient_idúnico por envío (por ejemplo, el id de tu registro). Si no recibes respuesta:- reenvía exactamente la misma petición (mismo cuerpo, mismo
X-Timestampy misma firma) dentro de los 5 minutos: con «Rechazar peticiones repetidas», si contesta409 Duplicated request, la primera petición sí llegó; - en ese caso, o si dudas, busca el envío por tu referencia (
GET /v3/sms/sends?client_id=…oGET /v3/sms?client_id=…;GET /v3/campaigns?client_id=…). Si existe, no lo vuelvas a enviar; - si no existe, envíalo de nuevo con un
X-Timestampnuevo.
- reenvía exactamente la misma petición (mismo cuerpo, mismo
- Cambios (
PATCH,hangup): son repetibles: aplicar dos veces el mismo valor dachanged: false, con unmessageque lo dice. - Ante 429 o 500, espera con tiempos crecientes antes de reintentar; no reintentes en bucle. Los SDK ya lo hacen así:
reintentan solos los 429 y, en
GET, los 5xx y los fallos de red; unPOSTo unPATCHque falla por la red no lo repiten (no se sabe si llegó).
El paso 2 en código, con la función mundosms de Python de arriba:
def enviar_sms_una_vez(datos): """datos lleva un client_id único (por ejemplo, el id de tu registro).""" try: return mundosms("POST", "/v3/sms", datos) except OSError: # la red cortó: no sabemos si llegó http, r = mundosms("GET", "/v3/sms/sends", {"client_id": datos["client_id"]}) if http == 200 and any("error" not in s for s in r["data"]["sms"]): return http, r # llegó: no lo repitas return mundosms("POST", "/v3/sms", datos) # no llegó: ahora sí, con un X-Timestamp nuevo
Avisos a tu URL (url_callback)#
Algunas rutas aceptan una URL tuya (url_callback) a la que avisamos cuando algo termina, para que no tengas que preguntar.
Así funcionan hoy:
- Todos los avisos son un
GETa tu URL con los datos en la query, añadidos a los parámetros que ya lleve. - No van firmados. Para comprobar que el aviso es nuestro, pon en tu URL un parámetro secreto que solo conozcáis tu
sistema y nosotros (
https://crm.ejemplo.com/avisos/sms?k=8f2c…) y compruébalo al recibirlo. Usahttps://. - Contesta rápido, en menos de 5 segundos: guarda el aviso y procésalo después.
- Trátalos como pistas, no como la verdad: si un aviso no llega o llega dos veces, la ruta de consulta de cada objeto siempre tiene el estado bueno.
- Tamaño de la URL: hasta 150 caracteres en SMS y NumCheck, y hasta 250 en VozPush. Más larga, la petición da
400 Parameter url_callback not valid. - Solo a direcciones públicas, también al enviar: el nombre de tu URL tiene que resolver a direcciones IPv4 públicas cuando lo pides y cada vez que te avisamos, y una redirección solo se sigue (hasta 3) si lleva a otra dirección pública: si tu servidor solo tiene IPv6, o redirige a una dirección privada, el aviso no sale y cuenta como fallido.
Informe de entrega de un SMS (POST /v3/sms)#
Un aviso por destinatario, cuando el SMS termina: entregado o fallido. No hay avisos de estados intermedios. Si no
pasas url_callback, se usa la URL de avisos de tu cuenta, si la tienes configurada.
GET /avisos/sms?k=8f2c&smsid=cita-88123&status=0&msisdn=34600123456&date_received=2026-11-21%2010%3A15%3A02&date_now=2026-11-21%2010%3A15%3A04 User-Agent: MundoSMS-Callback X-Webhook-Source: mundosms
| Parámetro | Qué es |
|---|---|
smsid |
tu client_id, si lo mandaste; si no, nuestro id del envío |
status |
0 entregado, 2 fallido |
msisdn |
el destinatario |
date_received |
la hora de entrega que da el operador (AAAA-MM-DD hh:mm:ss, hora de Madrid); no va si el operador no la da |
error_code |
casi nunca; Flood si lo frenó la protección contra envíos repetidos |
date_now |
cuándo se mandó este aviso |
Contesta con el texto OK: el código HTTP no cuenta. Si no llega OK, se reintenta cada 5 minutos como mínimo,
unas 20 veces (algo más de hora y media), cada vez con un date_now nuevo. Espera como mucho 5 segundos.
Fin de una campaña de VozPush (POST /v3/campaigns)#
Un aviso cuando la campaña termina o se cancela, con el resultado de cada destino:
GET /avisos/vozpush?k=8f2c&str=1%7C2%7C3.6%7C1%7C1%7C2026-11-21+10%3A31%3A07%7C45%7C0%7C45%7C0%7C0%0A%5B%5B%2234600123456%22%2C%22Finalizada%22%5D%5D%0A%5B%5D%0A%5B%5D&callid=recordatorio-1120callid: tuclient_id, si lo mandaste; si no, nuestroidde la campaña.str: cuatro líneas.- Separados por
|: terminada (1), estado (2finalizada,4cancelada,5error), coste, contestadas, fallidas, la hora de la última actualización y los segundos totales, de funciones, a móvil, a fijo y a SIP. - En JSON, el estado de cada destino:
[["34600123456","Finalizada"],["34911222333","No respondida"]]. - En JSON, las teclas que marcó cada destino:
[["34600123456","1|3"]]. - En JSON, sus grabaciones.
- La respuesta da igual y no se reintenta. Puede llegar dos veces: hazlo idempotente.
- En una campaña grande, la URL lleva el resultado de todos los destinos y algún servidor o proxy puede rechazarla por
larga. Si te pasa, usa el aviso solo como señal y pide el resultado con
GET /v3/campaigns/{id}.
Con url_callback_single_failed, además, un aviso por cada destino que queda fallido del todo (ya sin reintentos):
GET /avisos/fallidos?k=8f2c&callid=991250&destination=34600123456&status_lastcall=No+respondidaAquí callid es siempre nuestro id de la campaña. status_lastcall es uno de: No respondida, Ocupado,
Rechazada, No molestar, Desconectado, Contestador, Fax, Error, Cancelado, Desconocido.
Verificación de un número (POST /v3/callerid-validations)#
Es el mismo aviso que el fin de una campaña (la verificación es una llamada de VozPush), con callid = el vozpush_id
que devolvió la petición. Llega cuando termina la llamada y no dice si el número quedó verificado. Para saberlo, vuelve
a hacer POST /v3/callerid-validations con el número: si ya lo está, la respuesta lo dice y no se vuelve a llamar.
NumCheck (POST /v3/numchecks)#
Un aviso con el resultado:
GET /avisos/numcheck?k=8f2c&hlrid=limpieza-nov&msisdn=34600123456&b_valid=1&result=limpieza-nov%7C34600123456%7C1%7CSuccess%7C0%7C%7C21407%7CES%7CSpain%7C…&date_now=2026-11-21%2010%3A20%3A01&date_received=2026-11-21%2010%3A20%3A01hlrid: tuclient_id, si lo mandaste; si no, nuestroid.b_valid:1si el número existe y está activo.result, separado por|:id|número|válido|estado|código de error|descripción del error|código de red|país (ISO)|país|operador|red|tipo de red|ubicación|portado|portado desde|portado desde (2). Con un número que no es válido, solo trae los primeros campos.- Contesta con el texto
OK. No se reintenta.
SMS que llegan a uno de tus números (sms_url, PATCH /v3/numbers/{did})#
Hoy ningún número recibe SMS: no hay avisos de SMS entrantes. sms_url y sms_email se guardan, pero no se usan.
Lo que todavía no avisa#
- Llamadas de click2dial (
POST /v3/calls):url_callbackse acepta, pero hoy no se envía ningún aviso. Para saber cómo acabó, consulta la llamada enGET /v3/calls. - Faxes que llegan a tu número (
fax_url): el aviso lleva el fax dentro de la URL y la mayoría de servidores la rechazan por larga. No es fiable: recibe los faxes por correo (fax_email). - Llamadas que entran, se contestan o terminan: no hay avisos en tiempo real. Para la ficha del cliente,
GET /v3/calls/live.
Logs API: tus peticiones de los últimos 30 días#
En el panel, en API y Soporte → Logs API, están las peticiones de tu cuenta a la API de los últimos 30 días, con lo que llegó, lo que respondimos y cuánto tardamos. Es lo primero que hay que mirar cuando algo «no funciona»: si la petición no está, no llegó a la API (o llegó con un token que no es de una clave tuya); si está, ves exactamente qué mandaste y qué te contestamos.
- Cada respuesta lleva
X-Request-Id: búscalo en Logs API (o pégalo en el enlace:APILogs.html#<X-Request-Id>). - Filtros: fechas, clave, API (REST, la anterior
/APIv3/o enlaces firmados), resultado (correctas o con error), código HTTP yX-Request-Id. - Detalle: la petición y la respuesta, y la misma petición como orden de
curl(sin tus credenciales). - Lo que no se guarda: el token completo (solo su parte pública, sin la firma), la firma, la clave privada y las contraseñas.
- La petición: entera hasta 64 KB; de un fichero en base64, su tamaño y su huella. Una petición más grande se guarda además entera y comprimida, ficheros incluidos, para poder reproducir el problema, y la puedes descargar desde el detalle. De las respuestas, hasta 2 KB si fue bien y hasta 16 KB si fue un error.
- Solo lo ve tu cuenta, y nuestro soporte cuando nos lo pidas.
- Las peticiones de las APIs anteriores (
/APIv3/, y la/APIv2/y la extranet con tu usuario y contraseña) salen marcadas como «API antigua»: si aparecen, tu integración todavía no ha migrado (Migrar desde /APIv3/). De esas, la contraseña nunca se guarda, y elcurlque te proponemos la deja comoTU_CONTRASEÑA. - Una petición aparece unos segundos después de hacerla.
SDK: un fichero en PHP, Python o Node.js#
Si no quieres escribir la firma, descarga el cliente de tu lenguaje y cópialo en tu proyecto. Es un solo fichero, sin dependencias, con el mismo uso en los tres:
| Lenguaje | Fichero | Requisitos |
|---|---|---|
| PHP | mundosms.php (guárdalo como mundosms.php) |
PHP 7.4 o superior con curl |
| Python | mundosms.py | Python 3.8 o superior |
| Node.js | mundosms.js | Node.js 18 o superior |
from mundosms import MundoSMS, MundoSMSError api = MundoSMS("TU_TOKEN", "TU_CLAVE_PRIVADA") # la clave privada, "" si tu clave no exige firma r = api.post("/sms", {"to": "34600123456", "text": "Tu cita es mañana a las 10:00", "from": "MiClinica"}) print(r["data"]["id"]) for llamada in api.todos("/calls", {"from_datetime": "2026-11-01", "stop_at_ongoing": True}): print(llamada["type"], llamada["id"], llamada["state"]) try: api.patch("/extensions/recepcion", {"record_calls": True}) except MundoSMSError as e: print(e.http, e.status_code, e, e.detail)
get(ruta, filtros),post(ruta, datos),patch(ruta, datos)ydelete(ruta, filtros), con la ruta sin/v3("/calls","/numbers/34910123456"). Devuelven la respuesta entera (status,message,data).todos(ruta, filtros)recorre todas las páginas de un listado (connext_cursoronext_from_id) y te da los elementos uno a uno.- Un error es una excepción
MundoSMSErrorcon el código HTTP (http),status_code, el mensaje ydetail. - Firma cada petición con
X-Timestampen milisegundos, y reintenta solo lo que es seguro repetir (ver Reintentos seguros). - En PHP:
require "mundosms.php"; $api = new MundoSMS("TOKEN", "CLAVE");, yforeach ($api->todos("/calls", […]) as $c). En Node.js:const { MundoSMS } = require("./mundosms");, yfor await (const c of api.todos("/calls", {…})).
Buenas prácticas de seguridad#
- Firma con
tssiempre. Deja activadas «Firmar cada petición» y «Rechazar peticiones repetidas» en todas tus claves: sin firma, quien vea el token puede usarlo; con firma pero sin la segunda, una petición capturada se puede repetir durante 5 minutos. - Lista de IPs. Si tu sistema llama desde IPs fijas, ponlas en la clave: desde cualquier otra,
IP not allowed. - Una clave por integración, con solo los permisos que necesita. Si una se filtra, se revoca esa y no las demás.
- Rota las claves: crea la nueva, cámbiala en tu sistema y borra la vieja. Hazlo al menos una vez al año y siempre que alguien que la conocía deje de necesitarla.
- La clave privada no sale de tu servidor: ni en el navegador de tus usuarios, ni en una app móvil, ni en el código de un repositorio. Guárdala como un secreto (variable de entorno, gestor de secretos).
- El token, tampoco en la URL: siempre en la cabecera
Authorization. - Caducidad: para pruebas, pon caducidad a la clave; para integraciones, déjala vacía pero vigila su uso en Logs API.
- Lo que recibes en tus
url_callback: compruébalo antes de fiarte, y no ejecutes nada solo porque llegue. - TLS: llama siempre a
https://y no desactives la comprobación del certificado.
Migrar desde /APIv3/#
Política de versiones#
- La API REST (
https://api.mundosms.es/v3/) es la API de MundoSMS. Dentro de/v3/solo se añaden cosas (rutas, parámetros opcionales, campos en la respuesta, valores nuevos en los estados): escribe tu integración para que ignore campos y valores que no conozca. - Un cambio que rompa (quitar o renombrar un campo, cambiar un tipo) irá en una versión nueva (
/v4/), con aviso previo y un tiempo de convivencia. - La API anterior,
https://api.mundosms.es/APIv3/<método>, sigue funcionando para lo ya integrado, pero ya no se amplía: lo nuevo solo llega a la REST. Cuando dejemos de verla en uso, avisaremos con fecha antes de retirarla. Sus peticiones salen en Logs API como «API antigua». - Los enlaces que ya hemos enviado (grabaciones en HubSpot, correos de llamada perdida, QR de las apps) siguen valiendo.
Qué cambia#
Antes (/APIv3/) |
Ahora (REST, /v3/) |
|---|---|
una dirección por método, todo por POST |
una ruta por recurso y su verbo (GET, POST, PATCH, DELETE) |
| la firma cubre el token y el cuerpo | la firma cubre también el verbo, la ruta, la query y X-Timestamp: no sirve para otra petición |
ts dentro del cuerpo JSON |
la cabecera X-Timestamp (segundos o milisegundos) |
HTTP 200 siempre, sin Content-Type |
el código HTTP de cada caso (400, 401, 402, 403, 404, 405, 409, 429, 500) y application/json |
status_code "1" para éxitos con matiz (sin resultados, ya estaba así, programado) |
"0", y el matiz en data (results: 0, changed: false, state: "scheduled") |
«no existe» con status_code "3" |
HTTP 404 y "4" |
"4" (Already sent, XML Error, Max retries) y "6" (Callerid not validated) |
"3" (409 o 400) y "7" (429) |
message de éxito variado (IN_PROGRESS, File returned…) |
OK (N results en los listados) |
details |
detail |
fechas AAAA-MM-DD hh:mm:ss, "" sin fecha |
con milisegundos y su gemela _iso; null sin fecha |
cantidades e ids como texto ("12.00", "123") |
números JSON |
sí/no como "0"/"1" y prefijo b_ |
true/false sin prefijo (record_calls) |
| estados numéricos o en español | palabras estables (answered, no_answer, delivered…) |
ids que aceptaban tu referencia o la nuestra (sms_id, callid) |
id (el nuestro) y client_id (el tuyo), por separado |
| historiales sin paginación | limit, cursor, order, has_more y next_cursor (llamadas, SMS, respuestas, números y diagramas; from_id y next_from_id siguen valiendo) |
set_voipdids/set_voipextensions: un campo por petición (change_parameter/change_value) |
PATCH con los campos que cambian, todos de una vez o ninguno |
WhatsApp con status: "ok" y su propio formato |
el contrato común (success, data, id, client_id, date_*) |
Equivalencias de nombres#
/APIv3/ |
Ruta REST | Nombres que cambian (antes → ahora) |
|---|---|---|
list_voipcalls |
GET /v3/calls (y GET /v3/calls/{type}/{id}) |
callerid, callerid_text, destination, destination_type (1-9) → from, from_name, to, to_type (palabra); status (0-11), sip_originator, destination_pickup → state (palabra) y state_code, extension, pickup_extension; plan_id, bridgetype, xmlplan, arr_related → bundle_id, bridge_type, xml_plan (con include_xml), related (con include_related); showall → all_legs |
list_voipmissedcalls |
GET /v3/calls/missed |
— |
list_voiplivecalls |
GET /v3/calls/live |
type_id, caller, called, d_started, d_answered, d_bridged → id, from, to, date_start, date_answer, date_bridged; peer, peers, search, b_only_main → party, legs, extension, all_legs (al revés: all_legs: true = b_only_main: 0) |
action_voiplivecalls |
POST /v3/calls/live/{type}/{id}/hangup |
callid → id, en la ruta; action ya no se manda |
getrecording_voipcalls |
GET /v3/calls/{type}/{id}/recording |
id "in_123" → type + id en la ruta; name, type (MIME) → filename, content_type |
click2dial |
POST /v3/calls |
destination, callerid_destination, callerid_extension, id_urlcallback → to, from, extension_caller_id, url_callback |
get_voipdids |
GET /v3/numbers (y /{did}) |
b_calls, b_fax, b_sms, b_record_calls, xml, id_diagramflow → calls_enabled, fax_enabled, sms_enabled, record_calls, xml_plan, diagram_id; minutecall_cost, minutecallm_cost, date_expire: "Never" → minute_cost_landline, minute_cost_mobile, date_expire: null |
set_voipdids |
PATCH /v3/numbers/{did} |
change_parameter + change_value → los campos que cambian, en el cuerpo |
get_voipextensions |
GET /v3/extensions (y /{extension}) |
login, callerid, b_record_calls, show_status, status → extension, caller_id (+ caller_id_name, caller_id_number), record_calls, include_status, registration |
new_voipextensions |
POST /v3/extensions |
callerid, callerid_num, callerid_text, b_record_calls, login → caller_id, caller_id_number, caller_id_name, record_calls, extension |
set_voipextensions |
PATCH /v3/extensions/{extension} |
change_parameter + change_value → los campos que cambian, en el cuerpo |
getdiagrams_voip |
GET /v3/diagrams (y /{id}) |
— |
callerid_validation |
POST /v3/callerid-validations |
callerid, keycode, ntries, vozpushid → number, code, attempts, vozpush_id |
upload_voicefile, get_voicefile, delete_voicefile |
POST /v3/voicefiles, GET y DELETE /v3/voicefiles/{id} |
name, type (MIME) → filename, content_type |
sendcall |
POST /v3/campaigns |
destination, xmlplan, plan_id, sender, customid, date_start → to, xml_plan, diagram_id, from, client_id, date_scheduled; d_start/d_end, h_start/h_end, days_span, n_max_*, delay_nextcall → date_window_start/_end, time_window_start/_end, weekdays, max_*, retry_delay_min |
getreport_call |
GET /v3/campaigns/{id} (o ?client_id=), POST …/pause, /resume, /cancel |
callid, destination, continue, end, calls_results, n_answered, n_failed → id, to, resume, cancel, results, answered_count, failed_count |
getrecording_vozpush |
GET /v3/campaigns/{id}/calls/{to}/recording |
— |
sendsms |
POST /v3/sms |
destination, message, sender, smsid/customid, send_date, callback, b_keep_sizesms → to, text, from, client_id, date_scheduled, url_callback, keep_sms_size; data.smsid → data.id (el nuestro) y data.client_id |
quotesms |
POST /v3/sms/quote |
los de sendsms |
sendsms_cert |
POST /v3/sms/certified |
los de sendsms, y cert_cif, cert_lang, cert_tomail → cert_tax_id, cert_language, cert_email |
getreport |
GET /v3/sms/sends/{id} (o ?id=…, ?client_id=…) |
sms_id (nuestro o tuyo), dest_delivered, dest_failed (texto) → id o client_id, delivered, failed (listas) |
scheduled_sendings |
POST /v3/sms/sends/{id}/send-now y /cancel |
sms_id, action 1/2 → id en la ruta; data.smsid, data.status → data.id, data.state |
| (nuevo) | GET /v3/sms, GET /v3/sms/replies |
— |
numcheck |
POST /v3/numchecks |
phones → number (uno); customid, data.hlrid → client_id, data.id |
whatsapp_* |
/v3/whatsapp/… (WhatsApp) |
status: "ok" → success; message_id → id; client_ref → client_id; created, updated → date_created, date_updated (+ _iso) |
Ojo con estos cambios:
- Lo que identifica el recurso va en la ruta (
/v3/numbers/{did},/v3/sms/sends/{id}): ya no se manda en los datos. - En las rutas de SMS y de campañas,
ides solo nuestro id, un número. Si tienes tu propia referencia, búscala enclient_id. GET /v3/callsya no trae el plan XML ni las llamadas relacionadas si no los pides (include_xml,include_related).- En
POST /v3/campaigns,date_start(cuándo lanzarla) no tiene alias: da400 Parameter date_start not valid. Usadate_scheduled; losdate_window_*son la ventana de días.
Cómo migrar#
- Usa tus claves de siempre: las mismas valen para la REST. Si tu clave no firmaba, aprovecha para que firme.
- Cambia cada llamada por su ruta (tabla anterior) y la firma por la nueva (La firma): o mejor, usa el SDK, que firma solo.
- Trata los códigos HTTP: muchas librerías (Guzzle,
requestsconraise_for_status,fetchconr.ok) tratan un 4xx o 5xx como excepción. El cuerpo sigue siendo JSON: léelo también en esos casos. - Cambia los nombres de los campos que lees de la respuesta y los tipos: números y
true/false. - Prueba con una clave de solo lectura y el formulario de esta página antes de pasar los envíos, y comprueba en Logs API que ya no te sale ninguna petición «API antigua».
Historial de cambios#
2026-11-22#
- Un solo cursor en todas las listas: todas devuelven
next_cursory aceptancursor, así que una página se pide igual en cualquier lista.from_idynext_from_idsiguen valiendo donde estaban. - Fechas ISO 8601 con zona también en lo que mandas (
from_datetime,to_datetime), como ya pasaba endate_scheduled: puedes mandar tal cual unadate_x_isoque te hayamos devuelto. - Documentación: el ejemplo de
GET /v3/numberstrae elnext_cursorque devuelve la API; el tope declient_iden WhatsApp (100); y que hoy ningún número recibe SMS (sms_url,sms_emailyGET /v3/sms/replies). - Los avisos de VozPush también comprueban la dirección pública al enviar, como los de SMS y NumCheck.
- Documentación: los ejemplos de PHP y Python mandan las listas de la query separadas por comas (antes, una lista daba
400); el ejemplo de SMS personalizados usa
text; ISO 8601 con zona también enfrom_datetime/to_datetime; y «Reintentos seguros» con el ejemplo en código. - Documentación: los ejemplos de Node.js y Python ya no mandan los valores nulos como texto («null», «None»); el ejemplo de
GET /v3/sms/repliesusa el cursor; y la tabla de migración nombracursor/next_cursor. - WhatsApp:
date_scheduledpara programar una campaña, como en SMS y VozPush (scheduled_atsigue valiendo), y la consulta devuelvedate_scheduledydate_scheduled_iso. - Documentación: la regla de WhatsApp de «cada petición firmada vale una vez», dentro de la tabla de modos de firma; que
getreport_calltambién pausa y cancela campañas; qué campos deGET /v3/callssalen con cadatype; y un ejemplo del webhook de WhatsApp (lo que te llega cuando te escribe un cliente).
2026-11-21#
- API REST en
https://api.mundosms.es/v3/: una ruta por recurso, firma que cubre verbo, ruta, query, cuerpo yX-Timestamp,PATCHde varios campos a la vez y WhatsApp con el mismo contrato que el resto. Recoge todo lo del contrato del 20/11, que no llega a publicarse en otra dirección. - Logs API en el panel: tus peticiones de los últimos 30 días, con
X-Request-Iden cada respuesta. - SDK de un fichero en PHP, Python y Node.js.
GET /v3/numbersyGET /v3/diagrams: con cursor (from_id,limit,has_more,next_from_id), en orden deid. Antes devolvían como mucho 100 números y 50 diagramas, sin forma de ver el resto.- Nueva sección «Uso responsable»: pide cada dato una vez y guárdalo en tu base de datos.
2026-11-20#
- Contrato nuevo: códigos HTTP,
status_codecomún con WhatsApp, fechas con milisegundos e ISO 8601,nullen vez de"", números ytrue/falseen JSON, estados en palabras,idyclient_idseparados y paginación con cursor. - Nuevos: los SMS enviados por destinatario y las respuestas a tus SMS.
- Historial de llamadas: filtros
number,status,extension,did,to_datetime,stop_at_ongoing,limityorder. En las entrantes,statusva por quién atendió, conattended_byyfollowupen cada perdida. Sintype, todas las llamadas por hora de inicio con un solo cursor (next_cursor). - Nuevo: las perdidas por devolver, una por número.
- Llamadas en curso:
extensionconother_party(con quién habla) ynumber. - Grabaciones en MP3 con
format. - Página de referencia con el formulario «Pruébalo», la especificación OpenAPI y la colección de Postman.
¿Dudas con la integración? Escríbenos y te ayudamos. Para recibir en tu sistema los mensajes de WhatsApp, tienes el webhook de WhatsApp.