Documentación de la API API v1
Documentación

Campañas

Una campaña vende una oferta en una red ( google o meta ) con un objetivo y un presupuesto. El presupuesto está en un solo nivel: en la campaña ( budget_optimization: ad_campaign , el valor por defecto en Google, donde es una regla de la red) o en cada uno de sus grupos ( ad_group , el valor por defecto en Meta: cada conjunto de anuncios gasta el suyo, sin optimización de presupuesto de campaña, y la campaña suma los de sus grupos). status es lo que la organización decidió ( draft , active , paused ); delivery_status es lo que ocurre ahora ( draft , payment_failed , completed , paused , no_ad_groups , no_ads , issues , scheduled , processing , active ) e issues dice qué corregir. Los montos van en USD como texto decimal; budget_amount_local los expresa en la moneda de la cuenta publicitaria.

Listar campañas#

GET /api/v1/ad_campaigns Bearer

De la más antigua a la más reciente, por páginas: limit (1 a 100, 25 por defecto) y after (el next_cursor de la página anterior).

Parámetros

platform string

Solo las campañas de google o de meta .

status string

draft , active o paused .

offering_id string

Solo las campañas que venden esta oferta.

limit integer

Cuántos por página, de 1 a 100.

after string

El next_cursor de la página anterior.

Devuelve · 200 con la lista ( data , has_more , next_cursor ) · 422 con un filtro inválido.

cURL 
curl "https://edge.datil.com/api/v1/ad_campaigns" \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 200 
{
  "object": "list",
  "data": [
    {
      "id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
      "object": "ad_campaign",
      "title": "Firma electrónica · Ecuador",
      "platform": "meta",
      "objective": "sales",
      "status": "active",
      "delivery_status": "processing",
      "issues": [],
      "offering": {
        "id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
        "external_key": "portal.cert.y1.persona_natural",
        "label": "Firma electrónica 1 año"
      },
      "budget_optimization": "ad_campaign",
      "budget_type": "daily",
      "budget_amount": "25.00",
      "budget_amount_local": "25.00",
      "budget_currency": "USD",
      "budget_local_currency": "USD",
      "starts_at": "2026-09-27",
      "ends_at": null,
      "special_ad_categories": [],
      "regions": {
        "include": [
          "EC"
        ],
        "exclude": []
      },
      "google": null,
      "meta": {
        "audience_expansion": false
      },
      "metrics": {
        "window_days": 30,
        "impressions": 12480,
        "clicks": 311,
        "spend": "74.20",
        "conversions": 9.0,
        "conversion_value": "180.00",
        "roas": 2.43,
        "reach": 8400,
        "frequency": 1.49,
        "unique_clicks": 280,
        "ctr": 0.0249,
        "cpc": "0.24",
        "cpm": "5.95",
        "cpa": "8.24",
        "events": [
          {
            "name": "purchase",
            "count": 9,
            "value": "180.00"
          }
        ],
        "reached_people": 640
      },
      "approved_by": "api_key:9c1d2e3f-4a5b-4c6d-8e7f-8a9b0c1d2e3f",
      "approved_at": "2026-09-27T14:03:02Z",
      "created_at": "2026-09-27T14:03:01Z",
      "updated_at": "2026-09-27T14:03:02Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Crear una campaña#

POST /api/v1/ad_campaigns Bearer

Redacta la campaña y propone su presupuesto. Con status: active (el valor por defecto) la lanza: aprueba el presupuesto y la conciliación la crea en la red. Lanzar exige saldo publicitario cuando Datil opera las cuentas de la organización.

Content-Type: application/json

Cuerpo de la solicitud

title string requerido

El nombre de la campaña, hasta 120 caracteres.

platform string requerido

La red.

googlemeta

offering_id string requerido

La oferta que vende: su id o su clave externa ( GET /ad_offerings ).

objective string

Lo que la red busca; sin él, la venta de la oferta.

salesleadstraffic

status string

active (por defecto) la lanza; draft la deja en borrador.

draftactive

budget_optimization string

Dónde está el presupuesto: en la campaña (por defecto en Google) o en cada grupo (por defecto en Meta). En Google el presupuesto es de la campaña por regla de la red: ad_group responde 400 budget_level .

ad_campaignad_group

budget_amount string

El presupuesto en USD ( "25.00" o 25 ).

budget_amount_local string

El presupuesto en la moneda de la cuenta publicitaria, convertido al tipo de cambio oficial del día. Uno de los dos, nunca ambos.

budget_type string

Diario (por defecto) o total hasta ends_at .

dailylifetime

starts_at string

Fecha de inicio (ISO 8601).

ends_at string

Fecha de fin (ISO 8601); obligatoria con un presupuesto total.

special_ad_categories array

Meta: financial_products , employment , housing , politics , online_gambling .

google objeto

Google: campaign_type — search (anuncios de texto) o demand_gen (imágenes).

google.campaign_type string

El tipo de campaña de Google.

searchdemand_gen

meta objeto

Meta: audience_expansion — alcanzar más allá de los intereses.

meta.audience_expansion boolean

Si Meta puede ampliar el público.

Devuelve · 201 con la campaña · 400 payment_method_required sin Saldo publicitario para lanzar · 400 network_not_connected con la red sin conectar · 422 validation_failed con errors · 422 unknown_offering .

cURL 
curl -X POST https://edge.datil.com/api/v1/ad_campaigns \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Firma electrónica · Ecuador",
  "platform": "meta",
  "objective": "sales",
  "offering_id": "portal.cert.y1.persona_natural",
  "status": "active",
  "budget_optimization": "ad_campaign",
  "budget_amount": "25.00",
  "budget_type": "daily"
}'
Respuesta · 201 
{
  "id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
  "object": "ad_campaign",
  "title": "Firma electrónica · Ecuador",
  "platform": "meta",
  "objective": "sales",
  "status": "active",
  "delivery_status": "processing",
  "issues": [],
  "offering": {
    "id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
    "external_key": "portal.cert.y1.persona_natural",
    "label": "Firma electrónica 1 año"
  },
  "budget_optimization": "ad_campaign",
  "budget_type": "daily",
  "budget_amount": "25.00",
  "budget_amount_local": "25.00",
  "budget_currency": "USD",
  "budget_local_currency": "USD",
  "starts_at": "2026-09-27",
  "ends_at": null,
  "special_ad_categories": [],
  "regions": {
    "include": [
      "EC"
    ],
    "exclude": []
  },
  "google": null,
  "meta": {
    "audience_expansion": false
  },
  "metrics": {
    "window_days": 30,
    "impressions": 12480,
    "clicks": 311,
    "spend": "74.20",
    "conversions": 9.0,
    "conversion_value": "180.00",
    "roas": 2.43,
    "reach": 8400,
    "frequency": 1.49,
    "unique_clicks": 280,
    "ctr": 0.0249,
    "cpc": "0.24",
    "cpm": "5.95",
    "cpa": "8.24",
    "events": [
      {
        "name": "purchase",
        "count": 9,
        "value": "180.00"
      }
    ],
    "reached_people": 640
  },
  "approved_by": "api_key:9c1d2e3f-4a5b-4c6d-8e7f-8a9b0c1d2e3f",
  "approved_at": "2026-09-27T14:03:02Z",
  "created_at": "2026-09-27T14:03:01Z",
  "updated_at": "2026-09-27T14:03:02Z"
}

Consultar una campaña#

GET /api/v1/ad_campaigns/:id Bearer

Un objeto de tu organización, con su estado de entrega.

Parámetros

id string requerido

El id del objeto.

Devuelve · 200 con el objeto · 404 not_found para uno que no es de tu organización.

cURL 
curl "https://edge.datil.com/api/v1/ad_campaigns/7b0f6a52-3c1e-4d7e-9a57-0c1f5c2e9b10" \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 200 
{
  "id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
  "object": "ad_campaign",
  "title": "Firma electrónica · Ecuador",
  "platform": "meta",
  "objective": "sales",
  "status": "active",
  "delivery_status": "processing",
  "issues": [],
  "offering": {
    "id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
    "external_key": "portal.cert.y1.persona_natural",
    "label": "Firma electrónica 1 año"
  },
  "budget_optimization": "ad_campaign",
  "budget_type": "daily",
  "budget_amount": "25.00",
  "budget_amount_local": "25.00",
  "budget_currency": "USD",
  "budget_local_currency": "USD",
  "starts_at": "2026-09-27",
  "ends_at": null,
  "special_ad_categories": [],
  "regions": {
    "include": [
      "EC"
    ],
    "exclude": []
  },
  "google": null,
  "meta": {
    "audience_expansion": false
  },
  "metrics": {
    "window_days": 30,
    "impressions": 12480,
    "clicks": 311,
    "spend": "74.20",
    "conversions": 9.0,
    "conversion_value": "180.00",
    "roas": 2.43,
    "reach": 8400,
    "frequency": 1.49,
    "unique_clicks": 280,
    "ctr": 0.0249,
    "cpc": "0.24",
    "cpm": "5.95",
    "cpa": "8.24",
    "events": [
      {
        "name": "purchase",
        "count": 9,
        "value": "180.00"
      }
    ],
    "reached_people": 640
  },
  "approved_by": "api_key:9c1d2e3f-4a5b-4c6d-8e7f-8a9b0c1d2e3f",
  "approved_at": "2026-09-27T14:03:02Z",
  "created_at": "2026-09-27T14:03:01Z",
  "updated_at": "2026-09-27T14:03:02Z"
}

Cambiar una campaña#

PATCH /api/v1/ad_campaigns/:id Bearer

Cambia el nombre, el objetivo, las fechas o el presupuesto; un presupuesto nuevo en una campaña publicada queda aprobado al instante. status: active lanza un borrador o reanuda una campaña pausada; status: paused la pausa.

Content-Type: application/json

Parámetros

id string requerido

El id de la campaña.

Cuerpo de la solicitud

title string requerido

El nombre de la campaña, hasta 120 caracteres.

objective string

Lo que la red busca; sin él, la venta de la oferta.

salesleadstraffic

status string

active (por defecto) la lanza; draft la deja en borrador.

draftactive

budget_amount string

El presupuesto en USD ( "25.00" o 25 ).

budget_amount_local string

El presupuesto en la moneda de la cuenta publicitaria, convertido al tipo de cambio oficial del día. Uno de los dos, nunca ambos.

budget_type string

Diario (por defecto) o total hasta ends_at .

dailylifetime

starts_at string

Fecha de inicio (ISO 8601).

ends_at string

Fecha de fin (ISO 8601); obligatoria con un presupuesto total.

special_ad_categories array

Meta: financial_products , employment , housing , politics , online_gambling .

meta objeto

Meta: audience_expansion — alcanzar más allá de los intereses.

meta.audience_expansion boolean

Si Meta puede ampliar el público.

Devuelve · 200 con la campaña · 400 por una regla de lanzamiento · 409 por su estado · 422 con errors .

cURL 
curl -X PATCH https://edge.datil.com/api/v1/ad_campaigns/7b0f6a52-3c1e-4d7e-9a57-0c1f5c2e9b10 \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "budget_amount": "30.00",
  "ends_at": "2026-12-31"
}'
Respuesta · 200 
{
  "id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
  "object": "ad_campaign",
  "title": "Firma electrónica · Ecuador",
  "platform": "meta",
  "objective": "sales",
  "status": "active",
  "delivery_status": "processing",
  "issues": [],
  "offering": {
    "id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
    "external_key": "portal.cert.y1.persona_natural",
    "label": "Firma electrónica 1 año"
  },
  "budget_optimization": "ad_campaign",
  "budget_type": "daily",
  "budget_amount": "25.00",
  "budget_amount_local": "25.00",
  "budget_currency": "USD",
  "budget_local_currency": "USD",
  "starts_at": "2026-09-27",
  "ends_at": null,
  "special_ad_categories": [],
  "regions": {
    "include": [
      "EC"
    ],
    "exclude": []
  },
  "google": null,
  "meta": {
    "audience_expansion": false
  },
  "metrics": {
    "window_days": 30,
    "impressions": 12480,
    "clicks": 311,
    "spend": "74.20",
    "conversions": 9.0,
    "conversion_value": "180.00",
    "roas": 2.43,
    "reach": 8400,
    "frequency": 1.49,
    "unique_clicks": 280,
    "ctr": 0.0249,
    "cpc": "0.24",
    "cpm": "5.95",
    "cpa": "8.24",
    "events": [
      {
        "name": "purchase",
        "count": 9,
        "value": "180.00"
      }
    ],
    "reached_people": 640
  },
  "approved_by": "api_key:9c1d2e3f-4a5b-4c6d-8e7f-8a9b0c1d2e3f",
  "approved_at": "2026-09-27T14:03:02Z",
  "created_at": "2026-09-27T14:03:01Z",
  "updated_at": "2026-09-27T14:03:02Z"
}

Eliminar una campaña#

DELETE /api/v1/ad_campaigns/:id Bearer

Elimina la campaña. Una campaña publicada se pausa y se retira de la red ( REMOVED en Google, DELETED en Meta) en la próxima conciliación; su presupuesto deja de reservarse. La campaña queda en el registro, con su historia.

Parámetros

id string requerido

El id del objeto.

Devuelve · 200 con deleted: true · 404 · 409 por su estado.

cURL 
curl -X DELETE https://edge.datil.com/api/v1/ad_campaigns/7b0f6a52-3c1e-4d7e-9a57-0c1f5c2e9b10 \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 200 
{
  "id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
  "object": "ad_campaign",
  "deleted": true
}

Pausar una campaña#

POST /api/v1/ad_campaigns/:id/pause Bearer

Retiene la campaña con el mismo presupuesto; la red la pausa en la próxima conciliación.

Content-Type: application/json

Parámetros

id string requerido

El id del objeto.

Devuelve · 200 con el objeto · 400 por una regla de lanzamiento · 404 · 409 por su estado.

cURL 
curl -X POST https://edge.datil.com/api/v1/ad_campaigns/7b0f6a52-3c1e-4d7e-9a57-0c1f5c2e9b10/pause \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 200 
{
  "id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
  "object": "ad_campaign",
  "title": "Firma electrónica · Ecuador",
  "platform": "meta",
  "objective": "sales",
  "status": "active",
  "delivery_status": "processing",
  "issues": [],
  "offering": {
    "id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
    "external_key": "portal.cert.y1.persona_natural",
    "label": "Firma electrónica 1 año"
  },
  "budget_optimization": "ad_campaign",
  "budget_type": "daily",
  "budget_amount": "25.00",
  "budget_amount_local": "25.00",
  "budget_currency": "USD",
  "budget_local_currency": "USD",
  "starts_at": "2026-09-27",
  "ends_at": null,
  "special_ad_categories": [],
  "regions": {
    "include": [
      "EC"
    ],
    "exclude": []
  },
  "google": null,
  "meta": {
    "audience_expansion": false
  },
  "metrics": {
    "window_days": 30,
    "impressions": 12480,
    "clicks": 311,
    "spend": "74.20",
    "conversions": 9.0,
    "conversion_value": "180.00",
    "roas": 2.43,
    "reach": 8400,
    "frequency": 1.49,
    "unique_clicks": 280,
    "ctr": 0.0249,
    "cpc": "0.24",
    "cpm": "5.95",
    "cpa": "8.24",
    "events": [
      {
        "name": "purchase",
        "count": 9,
        "value": "180.00"
      }
    ],
    "reached_people": 640
  },
  "approved_by": "api_key:9c1d2e3f-4a5b-4c6d-8e7f-8a9b0c1d2e3f",
  "approved_at": "2026-09-27T14:03:02Z",
  "created_at": "2026-09-27T14:03:01Z",
  "updated_at": "2026-09-27T14:03:02Z"
}

Reanudar una campaña#

POST /api/v1/ad_campaigns/:id/unpause Bearer

Levanta la retención, o lanza un borrador. Exige Saldo publicitario cuando Datil opera las cuentas de la organización.

Content-Type: application/json

Parámetros

id string requerido

El id del objeto.

Devuelve · 200 con el objeto · 400 por una regla de lanzamiento · 404 · 409 por su estado.

cURL 
curl -X POST https://edge.datil.com/api/v1/ad_campaigns/7b0f6a52-3c1e-4d7e-9a57-0c1f5c2e9b10/unpause \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 200 
{
  "id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e",
  "object": "ad_campaign",
  "title": "Firma electrónica · Ecuador",
  "platform": "meta",
  "objective": "sales",
  "status": "active",
  "delivery_status": "processing",
  "issues": [],
  "offering": {
    "id": "5d2c1f0e-8a4b-4c3d-9e6f-1a2b3c4d5e6f",
    "external_key": "portal.cert.y1.persona_natural",
    "label": "Firma electrónica 1 año"
  },
  "budget_optimization": "ad_campaign",
  "budget_type": "daily",
  "budget_amount": "25.00",
  "budget_amount_local": "25.00",
  "budget_currency": "USD",
  "budget_local_currency": "USD",
  "starts_at": "2026-09-27",
  "ends_at": null,
  "special_ad_categories": [],
  "regions": {
    "include": [
      "EC"
    ],
    "exclude": []
  },
  "google": null,
  "meta": {
    "audience_expansion": false
  },
  "metrics": {
    "window_days": 30,
    "impressions": 12480,
    "clicks": 311,
    "spend": "74.20",
    "conversions": 9.0,
    "conversion_value": "180.00",
    "roas": 2.43,
    "reach": 8400,
    "frequency": 1.49,
    "unique_clicks": 280,
    "ctr": 0.0249,
    "cpc": "0.24",
    "cpm": "5.95",
    "cpa": "8.24",
    "events": [
      {
        "name": "purchase",
        "count": 9,
        "value": "180.00"
      }
    ],
    "reached_people": 640
  },
  "approved_by": "api_key:9c1d2e3f-4a5b-4c6d-8e7f-8a9b0c1d2e3f",
  "approved_at": "2026-09-27T14:03:02Z",
  "created_at": "2026-09-27T14:03:01Z",
  "updated_at": "2026-09-27T14:03:02Z"
}

Los problemas#

Cada objeto trae issues : los problemas abiertos, cada uno con id , message (qué pasó y cómo corregirlo), resource_type y resource_id .

Campos

id string

El problema, estable mientras siga abierto.

message string

Qué pasó y cómo corregirlo.

resource_type string

ad_campaign , ad_group o ad .

resource_id string

El objeto del problema.

Sin conexión — reintentando…

Preferencias de cookies

Esenciales

Sesión, seguridad, idioma y tema. Sin ellas el sitio no funciona.

Siempre activas

Cuenta las visitas y prueba qué versión de una página funciona mejor. Solo cookies propias.

Mide y mejora nuestros anuncios en Google y Meta. Compartimos el clic del anuncio y, si nos das tu correo o teléfono, solo su huella cifrada.