API REST

Todo lo que hace el panel, por HTTPS con una clave de API.

Autenticación

Crea una clave en Ajustes → API keys y envíala como token Bearer. Las claves se muestran una sola vez.

curl https://api.adjoin.dev/v1/me \
  -H "Authorization: Bearer adj_live_…"

read: Peticiones GET.
write: Crear y cambiar campañas, sitios y placements.
conversions: Solo los endpoints de conversiones servidor a servidor.

Una clave nunca es admin y no puede crear claves ni pedir pagos — eso requiere una persona con sesión iniciada.

Los importes son siempre enteros en micros: 1 USD = 1.000.000.

Endpoints

GET /v1/me: A quién pertenece la clave.
GET /v1/campaigns: Tus campañas con estado, puja, presupuesto y gasto.
POST /v1/campaigns: Crea una campaña; empieza en revisión. El presupuesto se reserva de tu saldo prepago.
POST /v1/campaigns/plan: Puja inicial, previsión de alcance y reserva para un presupuesto, antes de comprometerte.
GET /v1/refunds?campaign_id=cmp_…: Clics que filtramos y no cobramos, con el motivo.
POST /v1/conversions/s2s: Confirma una conversión desde tu servidor.
POST /v1/conversions/s2s/refund: Revierte un pedido dentro de su plazo de devolución.
GET /v1/sites · POST /v1/sites: Tus sitios; registra un dominio.
POST /v1/sites/{site_id}/verify: Comprueba la propiedad del dominio (DNS TXT, archivo o meta tag).
GET /v1/placements?site_id= · POST /v1/placements: Huecos de un sitio; crea uno.
GET /v1/placements/{placement_id}/live: Si un hueco recibió peticiones en las últimas 24 horas.
GET /v1/boost · POST /v1/boost: Estado del Launch Day Boost; aplícalo a una campaña.
GET /v1/credits: Saldo de crédito de promoción cruzada y actividad reciente.
GET /v1/segments: Etiquetas de audiencia que han puesto los publishers, con páginas vistas de 7 días (solo 100+). Úsalas en target_segments / exclude_segments al crear una campaña.

Crear una campaña

pricing_model es cpc, cpm, cpa, affiliate, guaranteed o cross_promo (pagado con crédito, sin presupuesto en efectivo). Un 402 significa que tu saldo disponible es insuficiente.

curl -X POST https://api.adjoin.dev/v1/campaigns \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{
    "name": "Launch",
    "pricing_model": "cpc",
    "bid_micros": 300000,
    "total_budget_micros": 50000000,
    "daily_cap_micros": 5000000,
    "target_categories": ["devtools"],
    "creatives": [{ "headline": "Ship faster", "body": "…", "cta": "Try it",
                    "landing_url": "https://myapp.dev", "format": "card" }]
  }'

Conversiones servidor a servidor

Cambia la fuente de conversión de la campaña a s2s y confirma pedidos desde tu servidor con una clave con alcance conversions. El píxel deja de cobrar esa campaña, así un pedido nunca se cobra por ambas vías. Los clics se pueden confirmar durante 7 días.

# the ad click lands on https://myapp.dev/?aj_t=… — keep aj_t with the order
curl -X POST https://api.adjoin.dev/v1/conversions/s2s \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{ "click_token": "<aj_t>", "order_id": "order_1234", "value_micros": 29000000 }'

# a return or cancellation, inside the return window
curl -X POST https://api.adjoin.dev/v1/conversions/s2s/refund \
  -H "Authorization: Bearer adj_live_…" -H "Content-Type: application/json" \
  -d '{ "campaign_id": "cmp_…", "order_id": "order_1234" }'

Errores

Los errores son JSON con un campo detail. 401: falta la clave o no es válida. 403: falta el alcance. También se devuelve 404 para objetos de otras cuentas, sin revelar si existen.

Preguntas: [email protected]