Dbetancor: Página creada con «{{#seo: |title= API de campañas {{PROD_TILDE}}. |titlemode=append |keywords=API, campañas, llamadas, html, API, servicios web, desarrollo web, VOIP, campañas de llamadas...»

2026-04-22T15:00:10Z

Página creada con «{{#seo: |title= API de campañas {{PROD_TILDE}}. |titlemode=append |keywords=API, campañas, llamadas, html, API, servicios web, desarrollo web, VOIP, campañas de llamadas...»

Página nueva

{{#seo:
|title= API de campañas {{PROD_TILDE}}.
|titlemode=append
|keywords=API, campañas, llamadas, html, API, servicios web, desarrollo web, VOIP, campañas de llamadas, url
|description= Con la API de campañas se pueden gestionar campañas de llamadas salientes: crear, listar, añadir números, lanzar llamadas y guardar resultados.
}}

==¿Qué es la API de campañas?==

===Descripción API de campañas===

Este servicio web nos permite gestionar campañas de llamadas salientes en una cuenta {{PRODUCTO}}: crear campañas, listar las existentes, añadir números, iniciar llamadas y guardar los resultados de cada una.

Si no sabe lo que es una API lea [[que es una api|¿Qué son las APIs de {{PRODUCTO}}?]]

==Autenticación==

Todas las llamadas a esta API requieren los parámetros de autenticación:

* 'principal' es su número de usuario de la cuenta {{PRODUCTO}} (o teléfono principal).
* 'pass' es la contraseña de la cuenta {{PRODUCTO}}.

La URL base para todas las operaciones es:

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=...

==Forma de uso==

===Listar campañas (accion=listar)===

Devuelve la lista de campañas de la cuenta (en XML). Esta es también la acción por defecto si se omite el parámetro 'accion'.

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=listar

Ejemplo de respuesta:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
<campanya>
<id>2024-03-15_10-30-00_p12345.sqlite</id>
<nombre>Clientes marzo</nombre>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<estado>0</estado>
<grabamos>0</grabamos>
<total>150</total>
<pendientes>87</pendientes>
<acabadas>63</acabadas>
</campanya>
<campanya>
<id>2024-02-01_09-00-00_p54321.sqlite</id>
<nombre>Campaña febrero</nombre>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<estado>1</estado>
<grabamos>0</grabamos>
<total>200</total>
<pendientes>0</pendientes>
<acabadas>200</acabadas>
</campanya>
</campanyas>

El campo 'estado' indica si la campaña está abierta (0) o cerrada (1).

===Crear una campaña (accion=nueva)===

Crea una nueva campaña con la lista de números indicada.

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=nueva&nombre=...&llamante=...&mascara=...&numeros=...

donde:

* 'nombre' es el nombre descriptivo de la campaña.
* 'llamante' es el número desde el que se realizarán las llamadas (debe ser un número activado de la cuenta).
* 'mascara' es el número que verá el destinatario de la llamada (debe ser una máscara válida de la cuenta).
* 'numeros' es la lista de números a llamar, un número por línea. Opcionalmente, separado por coma o tabulador, se puede incluir información adicional sobre el contacto.
* 'repes' (opcional): si se incluye este parámetro, se eliminan los números duplicados.
* 'grabamos' (opcional): si se incluye este parámetro, las llamadas se grabarán.

El número puede incluir prefijo internacional con + (se convierte automáticamente a 00) o ser una extensión VoIP del tipo usuario@telefacil.com. Se admite un máximo de 5.000 números por campaña.

Ejemplo de respuesta:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
<id>2024-03-15_10-30-00_p12345.sqlite</id>
<telefonos>150</telefonos>
</campanyas>

El campo 'id' es el identificador de la campaña creada, que se usará en el resto de operaciones. El campo 'telefonos' indica cuántos números se insertaron correctamente.

===Ver una campaña (accion=ver)===

Devuelve los datos completos de una campaña y la lista de todos sus números.

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=ver&campanya=...

donde:

* 'campanya' es el identificador de la campaña (campo 'id' devuelto por 'listar' o 'nueva').

Ejemplo de respuesta:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
<campanya>
<id>2024-03-15_10-30-00_p12345.sqlite</id>
<nombre>Clientes marzo</nombre>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<estado>0</estado>
<grabamos>0</grabamos>
<minutos>0</minutos>
<telefono>
<oid>1</oid>
<numero>666111222</numero>
<info>Juan García</info>
<comentario>Interesado en tarifa plana</comentario>
<estado>3</estado>
<resultado>4</resultado>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<momento>2024-03-15 11:05:32</momento>
<ref>abc123</ref>
<usuario>912345678</usuario>
<recordar></recordar>
</telefono>
<telefono>
<oid>2</oid>
<numero>666333444</numero>
<info>María López</info>
<comentario></comentario>
<estado>0</estado>
<resultado>0</resultado>
<llamante></llamante>
<mascara></mascara>
<momento></momento>
<ref></ref>
<usuario></usuario>
<recordar></recordar>
</telefono>
</campanya>
</campanyas>

Los valores del campo 'estado' de cada teléfono son: 0=libre, 1=intentando, 2=cogida, 3=acabada.

Los valores del campo 'resultado' son: 0=Sin resultado, 1=No contestada, 2=Comunicando, 3=Buzón, 4=Contestada.

===Añadir números a una campaña (accion=anyadir)===

Añade números a una campaña existente. Solo se pueden añadir números si la campaña está abierta (estado=0).

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=anyadir&campanya=...&numeros=...

donde:

* 'campanya' es el identificador de la campaña.
* 'numeros' es la lista de números a añadir, uno por línea (mismo formato que en 'nueva').
* 'repes' (opcional): si se incluye, se omiten números ya existentes en la campaña.

Ejemplo de respuesta:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
<telefonos>25</telefonos>
</campanyas>

===Cambiar datos de una campaña (accion=cambiar)===

Modifica el nombre, llamante y máscara de una campaña existente.

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=cambiar&campanya=...&nombre=...&llamante=...&mascara=...

donde:

* 'campanya' es el identificador de la campaña.
* 'nombre' es el nuevo nombre de la campaña.
* 'llamante' es el nuevo número llamante.
* 'mascara' es la nueva máscara.

Ejemplo de respuesta:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
</campanyas>

===Cerrar una campaña (accion=cerrar)===

Marca la campaña como cerrada. Una vez cerrada no se pueden añadir números ni iniciar nuevas llamadas.

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=cerrar&campanya=...

donde:

* 'campanya' es el identificador de la campaña.

Ejemplo de respuesta:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
</campanyas>

===Siguiente llamada (accion=siguiente)===

Selecciona el siguiente número pendiente de la campaña e inicia la llamada mediante callback: primero se llama al número 'llamante' y, cuando descuelga, se conecta automáticamente con el número de destino de la campaña.

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=siguiente&campanya=...

donde:

* 'campanya' es el identificador de la campaña.
* 'llamante' (opcional): sobreescribe el llamante almacenado en la campaña para esta llamada.
* 'mascara' (opcional): sobreescribe la máscara almacenada en la campaña para esta llamada.

Ejemplo de respuesta cuando la llamada se inicia correctamente:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
<resultado>1</resultado>
<oid>42</oid>
<numero>666111222</numero>
<info>Juan García</info>
<comentario></comentario>
<ref>abc123</ref>
</campanyas>

El campo 'oid' identifica el registro del número llamado y debe usarse en la operación 'guardar' para guardar el resultado. El campo 'ref' es la referencia interna de la llamada. Si no hay más números pendientes:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
<resultado>0</resultado>
<msgerr>No hay mas llamadas en esta campanya</msgerr>
</campanyas>

===Guardar resultado de una llamada (accion=guardar)===

Guarda el resultado de una llamada iniciada con 'siguiente'. Debe llamarse después de que el agente haya completado la llamada.

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=guardar&campanya=...&oid=...&resultado=...&comentario=...

donde:

* 'campanya' es el identificador de la campaña.
* 'oid' es el identificador del número devuelto por 'siguiente'.
* 'resultado' es el resultado de la llamada: 0=Sin resultado, 1=No contestada, 2=Comunicando, 3=Buzón, 4=Contestada.
* 'comentario' (opcional): comentario libre sobre la llamada.
* 'llamante' (opcional): llamante usado en la llamada.
* 'mascara' (opcional): máscara usada en la llamada.
* 'dejar_para_despues' (opcional): si se incluye, el número vuelve a la cola para ser llamado de nuevo.
* 'recordar' (opcional, requiere 'dejar_para_despues'): si se incluye, se crea un recordatorio.
* 'fechayhora' (opcional, requiere 'recordar'): fecha y hora del recordatorio en formato DD/MM/AAAA HH:MM.

Ejemplo de respuesta:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
</campanyas>

===Eliminar una campaña (accion=eliminar)===

Elimina permanentemente una campaña y todos sus datos. Esta operación no se puede deshacer.

https://scgi.duocom.es/cgi-bin/{{DIR_CGI}}/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=eliminar&campanya=...

donde:

* 'campanya' es el identificador de la campaña.

Ejemplo de respuesta:

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
</campanyas>

===Respuesta del servicio===

El servicio web retorna todas las respuestas en formato [https://es.wikipedia.org/wiki/Extensible_Markup_Language XML]. Todas las respuestas están encerradas en la raíz 'campanyas', y contienen siempre un campo 'error' que será 0 si el comando o petición enviado al servidor se ejecutó con éxito, o 1 si hubo algún error, en cuyo caso habrá también un campo 'msgerr' que explica dicho error.

Una respuesta de error sería:

HTTP/1.1 200 OK
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>1</error>
<msgerr>Registro incorrecto. Compruebe que el usuario y la clave sean validos (1).</msgerr>
</campanyas>

==Ejemplos API de campañas==

====Ejemplo de flujo completo en PHP + CURL====

Tenga presente que, aunque la aplicación web es accesible mediante una URL, no debe poner nunca enlaces a esta aplicación directamente en el código fuente de sus páginas web, ya que sus visitantes podrían descubrir datos sensibles como su número de usuario y su contraseña simplemente mirando el código HTML.

La aplicación web debe ser llamada siempre desde el servidor, usando para ello alguna de las librerías que permite llamadas a servicios HTTPS.

He aquí un ejemplo en PHP usando cURL que crea una campaña, inicia una llamada y guarda el resultado:
<pre>
<?php
$principal = '912345678';
$pass = 'MiPass123';
$base_url = 'https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas';

function api_campanyas($base_url, $params) {
$url = $base_url . '?' . http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
$output = curl_exec($curl);
curl_close($curl);
return simplexml_load_string($output);
}

// 1. Crear una campaña
$xml = api_campanyas($base_url, [
'principal' => $principal,
'pass' => $pass,
'accion' => 'nueva',
'nombre' => 'Campaña de prueba',
'llamante' => '912345678',
'mascara' => '900123456',
'numeros' => "666111222,Juan García\n666333444,María López\n",
'repes' => '1',
]);
if ((int)$xml->error !== 0) die('Error: ' . $xml->msgerr);
$campanya_id = (string)$xml->id;
echo "Campaña creada: $campanya_id con {$xml->telefonos} teléfonos\n";

// 2. Iniciar la siguiente llamada
$xml = api_campanyas($base_url, [
'principal' => $principal,
'pass' => $pass,
'accion' => 'siguiente',
'campanya' => $campanya_id,
]);
if ((int)$xml->error !== 0) die('Error: ' . $xml->msgerr);
if ((int)$xml->resultado === 0) die("No hay más llamadas pendientes\n");
$oid = (int)$xml->oid;
$numero = (string)$xml->numero;
echo "Llamando a $numero (oid=$oid)...\n";

// 3. Guardar el resultado (tras que el agente complete la llamada)
$xml = api_campanyas($base_url, [
'principal' => $principal,
'pass' => $pass,
'accion' => 'guardar',
'campanya' => $campanya_id,
'oid' => $oid,
'resultado' => 4, // 4 = Contestada
'comentario' => 'Cliente interesado, enviar oferta',
]);
if ((int)$xml->error !== 0) die('Error: ' . $xml->msgerr);
echo "Resultado guardado correctamente\n";
?>
</pre>

====Ejemplo de listado de campañas en XML====

<?xml version="1.0" encoding="UTF-8" ?>

<campanyas>
<error>0</error>
<campanya>
<id>2024-03-15_10-30-00_p12345.sqlite</id>
<nombre>Clientes marzo</nombre>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<estado>0</estado>
<grabamos>0</grabamos>
<total>150</total>
<pendientes>87</pendientes>
<acabadas>63</acabadas>
</campanya>
</campanyas>

----

----

'''Indice'''

[[Página principal]] >> [[Desarrolladores]] >> API de campañas.

API de campañas - Historial de revisiones

Dbetancor: Página creada con «{{#seo: |title= API de campañas {{PROD_TILDE}}. |titlemode=append |keywords=API, campañas, llamadas, html, API, servicios web, desarrollo web, VOIP, campañas de llamadas...»