API para conectar su sistema

Referencia técnica

Guía técnica para desarrolladores de integraciones

Empiece por las convenciones de llamada comunes y el inicio de sesión. Después siga el proceso desde la carga de un archivo hasta la activación de una campaña y consulte los puntos de acceso disponibles.

Inicio de sesión

El identificador de acceso no es una dirección de correo, sino un código de ocho caracteres generado al crear el usuario, por ejemplo A1B2C3D4. Cree un usuario específico con los permisos mínimos necesarios para la integración; así podrá revocar su acceso en cualquier momento sin afectar a otros usuarios.

curl -u "A1B2C3D4:your-password" https://admin.example.org/api/public/login

La contraseña se envía con cada solicitud. Guárdela como secreto, por ejemplo, en una variable de entorno o en un gestor de contraseñas; nunca en el código fuente, un repositorio o los registros.

Los siguientes ejemplos suponen que estas variables están definidas:

export API="https://admin.example.org"
export AUTH="A1B2C3D4:su-contrasena"

Los ejemplos utilizan curl porque no depende de un lenguaje de programación. La interfaz utiliza HTTP, por lo que puede llamarse desde cualquier lenguaje o herramienta compatible con Basic Auth, como Python, JavaScript, PHP, Postman o Make.

Proceso: de un archivo a una campaña en reproducción

1. Obtener el identificador de la empresa. Lo utilizará en todas las llamadas posteriores.
2. Cargar un archivo multimedia. La respuesta devuelve su identificador.
3. Cargar una plantilla de campaña. El servidor la rellena con los ajustes de la empresa y la lista de ubicaciones y dispositivos.
4. Editar la plantilla : nombre, periodo, dispositivos de destino y creatividad.
5. Crear la campaña. Se crea como borrador y todavía no se reproduce.
6. Activar la campaña. El sistema prepara un nuevo plan de reproducción y lo envía a los dispositivos.
7. Supervisar los resultados en el informe de campaña.

1. Identificador de la empresa

curl -u "$AUTH" "$API/api/public/login"

Respuesta abreviada:

{
  "id": 1715714421868,
  "name": "Integración – tienda en línea",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Agencia publicitaria S. L." },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Guarde el valor de company.id; los ejemplos lo utilizan como variable COMPANY. La sección permission enumera los permisos del usuario; su significado se describe en Permisos.

2. Carga de un archivo multimedia

El archivo se envía como cuerpo binario de la solicitud mediante PUT; sus propiedades se indican en las cabeceras.

curl -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: oferta-verano.jpg" \
  -H "file-suffix: jpg" \
  --data-binary @oferta-verano.jpg

La misma llamada en Python:

import requests

with open("oferta-verano.jpg", "rb") as f:
    r = requests.put(
        f"{API}/api/resource/single/{COMPANY}",
        auth=("A1B2C3D4", "su-contrasena"),
        headers={
            "file-type": "IMAGE",
            "file-mime": "image/jpeg",
            "file-name": "oferta-verano.jpg",
            "file-suffix": "jpg",
        },
        data=f,
    )
r.raise_for_status()
resource_id = r.json()["id"]

La respuesta contiene el identificador del archivo (id) y su tipo (type); utilizará ambos valores en la creatividad de la campaña.

{
  "id": 1724832015443,
  "type": 2,
  "name": "oferta-verano",
  "width": 1920,
  "height": 1080,
  "duration": 0,
  "aspectRatio": 32
}

• Tamaño: archivos normales hasta aproximadamente 1,1 GB y vídeo con transparencia hasta aproximadamente 2,1 GB. El servidor rechaza los archivos mayores con 413.
• Preparación del vídeo: el vídeo se convierte en segundo plano tras la carga. Está listo cuando los detalles del archivo (GET /api/resource/single/{companyId}/{id}) contienen un valor en dt_ready. Las imágenes se preparan prácticamente al instante.
• Cabecera ausente: sin file-mime, file-name o file-suffix el servidor devuelve 204 y no crea el archivo multimedia. Compruebe siempre que la respuesta contiene id antes de continuar.

3. Plantilla de campaña

No construya la campaña a mano. Solicite una plantilla que el servidor rellena con un periodo predeterminado de un mes desde hoy, los ajustes de la empresa y todas las ubicaciones y dispositivos. Cada dispositivo aparece marcado como isActive: false.

curl -u "$AUTH" "$API/api/campaign/company/$COMPANY" > campaign.json

Ejemplo de plantilla abreviado:

{
  "id": -1,
  "groupId": -1,
  "state": 2,
  "name": "",
  "start": "2026-11-01T10:00:00",
  "end": "2026-12-01T10:00:00",
  "isCommercial": true,
  "isNonCommercial": false,
  "settings": {
    "type": 2,
    "companyCount": 10,
    "companyDuration": 10000,
    "campaignCount": 1,
    "campaignDuration": 10000
  },
  "locations": [
    {
      "id": 1698234512100,
      "name": "Centro comercial del centro",
      "days": [ { "day": 1, "start": "09:00", "end": "21:00" } ],
      "devices": [
        {
          "id": 1698234512201,
          "name": "Entrada A",
          "screenRatio": 32,
          "isHorizontal": true,
          "isActive": false
        }
      ]
    }
  ],
  "visuals": []
}

El valor de settings.type determina el modo de reproducción de la empresa: 2 = SLOT, 4 = IMPRESSION. El proveedor establece el modo y no puede modificarse mediante la API.

4. Edición de la plantilla

• name: nombre de la campaña mostrado en la administración y los informes.
• start, end: inicio y fin de la campaña.
• isActive: establecer en true para los dispositivos en los que deba reproducirse la campaña.
• visuals: añadir una creatividad con el archivo cargado.

"visuals": [
  {
    "id": 1,
    "name": "Creatividad principal",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "oferta-verano",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]

La plantilla puede editarse mediante un script, por ejemplo, con jq:

jq --argjson res "$RESOURCE" '
  .name = "Oferta de verano 2026"
  | .start = "2026-11-02T00:00:00"
  | .end   = "2026-11-09T00:00:00"
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Creatividad principal", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: "oferta-verano", duration: 10000, type: 2 }]
    }]
' campaign.json > campaign-edited.json

Si la campaña se dirige a pantallas horizontales y verticales (isHorizontal), añada una creatividad para cada orientación. De lo contrario, el contenido se recortará o reducirá en algunas pantallas. Consulte Creatividades de las campañas para obtener más información.

5. Creación de la campaña

curl -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @campaign-edited.json \
  -o response.json

export CAMPAIGN=$(jq -r '.id' response.json)
export GROUP=$(jq -r '.groupId' response.json)

La campaña se crea como borrador y no se reproduce en ningún dispositivo. La respuesta contiene la campaña guardada con los valores asignados de id y groupId. La plantilla ya contiene state: 2 (borrador); el servidor rechaza cualquier otro valor con 409.

6. Activación de la campaña

curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

• +01:00: zona horaria que sigue la campaña, como desplazamiento respecto a UTC. Para Europa Central, utilice +01:00 en invierno y +02:00 durante el horario de verano.
• 0: número de impresiones esperado para toda la campaña. Se aplica en modo IMPRESSION; en modo SLOT, utilice 0.

Una campaña cuyo inicio sea hoy o anterior pasa a estar activa y su inicio se fija en el momento de la activación. Una campaña con inicio futuro pasa a estar publicada y empieza el día previsto.

El sistema recalcula el plan de reproducción y lo envía a los dispositivos afectados. En los conectados suele tardar unas decenas de segundos; un dispositivo desconectado lo recibe al recuperar la conexión. Compruebe la capacidad en la administración; consulte Capacidad de las campañas.

7. Resultados de la campaña

curl -u "$AUTH" "$API/api/report/$COMPANY/campaign/$GROUP"
curl -u "$AUTH" "$API/api/report/$COMPANY/campaign/$GROUP/impression"

Los informes utilizan groupId, no el identificador de campaña id. El primer punto de acceso devuelve el resumen de la campaña; el segundo, las cifras de impresiones registradas. Los dispositivos envían registros continuamente por lotes, por lo que las cifras no están disponibles en tiempo real. Consulte Informe de campaña para conocer el significado de las cifras.

Pausar, detener y eliminar

# Pausar una campaña activa; otra llamada la reanuda
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

# Detener de forma permanente
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00"

# Eliminar
curl -u "$AUTH" -X DELETE \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN"

El punto de acceso del paso 6 actúa como un conmutador: pausa una campaña activa o publicada y reanuda una pausada. Compruebe el estado actual (state en los detalles) antes de llamarlo. Una campaña detenida no puede volver a iniciarse, pero permanece en la lista con sus informes. Una campaña eliminada desaparece de la lista.

Resumen de puntos de acceso

Las rutas son relativas a la dirección de administración. {c} representa el identificador de la empresa.

Cuenta

Multimedia

Campañas

Ubicaciones y dispositivos

Informes

Listas de valores

Los valores de las listas se escriben como números en JSON.

Estado de la campaña (state)

Tipos de contenido multimedia

Para los documentos, la cabecera file-type utiliza el valor PDF, no DOCUMENT.

Permisos

La interfaz aplica los mismos permisos que la administración y los comprueba en cada solicitud. En la respuesta de inicio de sesión, cada área se expresa mediante un número que es la suma de los derechos individuales:

Por ejemplo, resource: 28 (4 + 8 + 16) significa que el usuario puede ver, añadir y editar contenido multimedia, pero no eliminarlo. Los valores superiores (128 en 1024) representan los mismos derechos fuera de la empresa del usuario; una integración no los necesita.

Activar, pausar y detener una campaña requiere el derecho Añadir. Eliminar una campaña activada o un archivo requiere Eliminar; un borrador puede eliminarse sin ese derecho. Un buen punto de partida es el rol Gestor de publicidad de la empresa, eliminando los derechos innecesarios.

Códigos de error

Ejemplo completo

El script realiza todo el proceso, desde la carga de una imagen hasta la activación de una campaña en todos los dispositivos de la empresa. Requiere curl y jq.

#!/usr/bin/env bash
set -euo pipefail

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?defina INTEGRATION_AUTH=usuario:contrasena}"
FILE="oferta-verano.jpg"
NAME="Oferta de verano 2026"
FROM="2026-11-02T00:00:00"
TO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

# 1) Identificador de la empresa
COMPANY=$(curl -sf -u "$AUTH" "$API/api/public/login" | jq -r '.company.id')

# 2) Cargar el archivo multimedia
RESOURCE=$(curl -sf -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: $FILE" \
  -H "file-suffix: jpg" \
  --data-binary "@$FILE" | jq -r '.id')

# 3) Plantilla de campaña
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > template.json

# 4) Editar la plantilla
jq --argjson res "$RESOURCE" --arg n "$NAME" --arg from "$FROM" --arg to "$TO" '
  .name = $n
  | .start = $from
  | .end = $to
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Creatividad principal", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' template.json > campaign.json

# 5) Crear un borrador
RESPONSE=$(curl -sf -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @campaign.json)
CAMPAIGN=$(echo "$RESPONSE" | jq -r '.id')
GROUP=$(echo "$RESPONSE" | jq -r '.groupId')

# 6) Activar
curl -sf -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/$TZ_OFFSET/0" > /dev/null

echo "Campaña $CAMPAIGN activada, informe: $API/api/report/$COMPANY/campaign/$GROUP"