Documentación API

Recursos técnicos para integrar nuestras soluciones publicitarias en tus aplicaciones

Introducción

La API de PublicAdis te permite integrar nuestras soluciones publicitarias en tus aplicaciones. Puedes crear y gestionar campañas, anuncios, y acceder a datos de rendimiento en tiempo real.

Esta API RESTful utiliza JSON para todas las solicitudes y respuestas, y se encuentra actualmente en la versión 1.0.

URL Base:

https://api.publicadis.com/v1

Autenticación

Todas las solicitudes a la API requieren autenticación mediante un token API. Para obtener tu token, sigue estos pasos:

Inicia sesión en tu panel de control de PublicAdis
Ve a la sección "Configuración" > "API"
Haz clic en "Generar nuevo token"
Guarda tu token en un lugar seguro, ya que no podrás verlo nuevamente

Ejemplo de encabezado de autenticación:

Authorization: Bearer tu_token_api

Importante: Mantén tu token API seguro. No lo compartas ni expongas en código público.

Endpoints

Campañas

Estos endpoints te permiten crear, consultar, actualizar y eliminar campañas publicitarias.

GET/campaigns

Obtiene una lista de todas tus campañas.

Parámetros opcionales:

status (string): Filtra por estado de campaña (active, paused, completed)
limit (integer): Límite de resultados (por defecto: 20, máx: 100)
offset (integer): Desplazamiento para paginación

GET/campaigns/{campaign_id}

Obtiene detalles de una campaña específica.

POST/campaigns

Crea una nueva campaña publicitaria.

Cuerpo de la solicitud (JSON):

{
  "name": "Mi Campaña de Verano",
  "budget": 1000,
  "start_date": "2023-07-01",
  "end_date": "2023-08-31",
  "status": "active",
  "objective": "traffic",
  "targeting": {
    "locations": ["Cusco"],
    "age_range": [18, 65],
    "interests": ["turismo", "gastronomía"]
  }
}

PUT/campaigns/{campaign_id}

Actualiza una campaña existente.

DELETE/campaigns/{campaign_id}

Elimina una campaña.

Anuncios

Estos endpoints te permiten gestionar los anuncios asociados a tus campañas.

GET/campaigns/{campaign_id}/ads

Lista todos los anuncios de una campaña específica.

POST/campaigns/{campaign_id}/ads

Crea un nuevo anuncio para una campaña.

GET/ads/{ad_id}

Obtiene detalles de un anuncio específico.

Métricas

Estos endpoints te permiten acceder a datos de rendimiento de tus campañas y anuncios.

GET/campaigns/{campaign_id}/metrics

Obtiene métricas de rendimiento para una campaña específica.

Parámetros opcionales:

date_range (string): Rango de fechas (last_7_days, last_30_days, custom)
start_date (string): Fecha de inicio (formato: YYYY-MM-DD)
end_date (string): Fecha de fin (formato: YYYY-MM-DD)
metrics (array): Métricas específicas a obtener (impresiones, clics, conversiones, etc.)

GET/ads/{ad_id}/metrics

Obtiene métricas de rendimiento para un anuncio específico.

Ejemplos de código

A continuación, te mostramos cómo interactuar con nuestra API en diferentes lenguajes de programación:

JavaScript (Node.js)

const fetch = require('node-fetch');

const API_TOKEN = 'tu_token_api';
const BASE_URL = 'https://api.publicadis.com/v1';

async function createCampaign(campaignData) {
  try {
    const response = await fetch(`${BASE_URL}/campaigns`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(campaignData),
    });

    if (!response.ok) {
      throw new Error(`Error: ${response.status}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error creating campaign:', error);
    throw error;
  }
}

// Ejemplo de uso
const newCampaign = {
  name: 'Campaña de Invierno',
  budget: 5000,
  start_date: '2023-06-01',
  end_date: '2023-08-31',
  status: 'active',
  objective: 'conversions',
};

createCampaign(newCampaign)
  .then(campaign => console.log('Campaña creada:', campaign))
  .catch(error => console.error(error));

Python

import requests

API_TOKEN = 'tu_token_api'
BASE_URL = 'https://api.publicadis.com/v1'

def get_campaign_metrics(campaign_id, date_range='last_30_days'):
    headers = {
        'Authorization': f'Bearer {API_TOKEN}',
        'Content-Type': 'application/json'
    }
    
    params = {
        'date_range': date_range
    }
    
    response = requests.get(
        f'{BASE_URL}/campaigns/{campaign_id}/metrics',
        headers=headers,
        params=params
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        print(f'Error: {response.status_code}')
        print(response.json())
        return None

# Ejemplo de uso
metrics = get_campaign_metrics('campaign_12345')
print(metrics)

cURL

curl -X POST \
  https://api.publicadis.com/v1/campaigns \
  -H 'Authorization: Bearer tu_token_api' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Mi Campaña de Verano",
    "budget": 1000,
    "start_date": "2023-07-01",
    "end_date": "2023-08-31",
    "status": "active",
    "objective": "traffic",
    "targeting": {
      "locations": ["Cusco"],
      "age_range": [18, 65],
      "interests": ["turismo", "gastronomía"]
    }
  }'

Manejo de errores

La API utiliza códigos de estado HTTP estándar para indicar el éxito o fracaso de una solicitud. Los códigos comunes incluyen:

Código	Descripción
200 - OK	La solicitud se ha completado con éxito
201 - Created	El recurso se ha creado correctamente
400 - Bad Request	La solicitud contiene errores o datos inválidos
401 - Unauthorized	Autenticación requerida o inválida
403 - Forbidden	No tienes permisos para acceder al recurso
404 - Not Found	El recurso solicitado no existe
429 - Too Many Requests	Has excedido el límite de solicitudes
500 - Server Error	Error interno del servidor

Cuando ocurre un error, la API devuelve una respuesta JSON con información detallada:

{
  "error": {
    "code": "invalid_request",
    "message": "El campo 'budget' debe ser un número positivo",
    "status": 400,
    "details": {
      "field": "budget",
      "value": "-100",
      "constraint": "must_be_positive"
    }
  }
}

Recomendamos siempre manejar los errores adecuadamente en tu aplicación para proporcionar una mejor experiencia al usuario.

Límites de uso

Para garantizar un servicio estable, aplicamos límites al número de solicitudes que puedes realizar:

Plan	Límite de solicitudes
Básico	100 solicitudes por minuto
Profesional	300 solicitudes por minuto
Empresarial	1000 solicitudes por minuto

Si excedes estos límites, recibirás un error 429 Too Many Requests. Cada respuesta incluye encabezados que indican tu límite y cuántas solicitudes te quedan:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1624987483

Versionado

Para garantizar la compatibilidad a largo plazo, nuestra API está versionada. La versión actual es v1.

Cuando realizamos cambios importantes que podrían romper la compatibilidad, incrementamos el número de versión. Las versiones anteriores siguen siendo compatibles durante al menos 12 meses después del lanzamiento de una nueva versión.

Recomendación: Especifica siempre la versión en tus solicitudes a la API para asegurar la compatibilidad a largo plazo.

¿Listo para empezar a integrar nuestra API?

Regístrate en nuestra plataforma, obtén tu token API y comienza a desarrollar aplicaciones que aprovechen nuestras soluciones publicitarias.

Crear Cuenta Ver Ejemplos en GitHub