Givemefi Partner Delivery API
docs v0.2
Sandbox / Partner Review
Givemefi · Partner Integration

Partner Delivery API

Integra creatividades de Givemefi en portales cautivos sin convertir la publicidad en una dependencia del acceso WiFi. El backend del partner solicita una creatividad, el portal la renderiza si está disponible y, ante timeout o error, el flujo de conectividad continúa.

Principio de integraciónLa publicidad nunca debe bloquear el acceso WiFi. Si Givemefi no responde dentro del presupuesto de tiempo del partner, responde 204 o devuelve un error temporal, continúa el flujo de conectividad.
VersionesAPI v1 es el contrato del endpoint y aparece en la ruta /v1/. Documentación v0.2 identifica esta revisión de la guía. Actualizar la documentación no cambia por sí mismo la versión de la API.
Patrón
Server-to-server
Autenticación
Bearer API key
Timeout recomendado
Máximo 1.500 ms

Disponibilidad v0.2

VALIDADOIMAGESelección y asset temporal.
VALIDADOVIDEOSelección, MIME y duración cuando existe.
CONTROLADOHTML5Requiere capability y habilitación de origen de render.
RESERVADOEventsEl endpoint Partner de medición no forma parte todavía de esta guía operativa.

La documentación describe únicamente capacidades que el partner puede usar o preparar en la fase actual. Una capacidad marcada como controlada requiere habilitación expresa; una capacidad reservada no debe integrarse todavía.

Glosario

Placement
Punto de entrega configurado por Givemefi. Su placement_key determina el inventario y formatos elegibles.
Flight
Ventana/configuración de entrega de una creatividad. Es un concepto interno de campaña y no se expone al partner.
Creative
La pieza publicitaria seleccionada: imagen, video o HTML5.
Delivery
Una decisión de selección identificada por delivery_id. Una delivery no equivale por sí sola a una impresión.
Descriptor
Objeto JSON devuelto en creative con la información necesaria para renderizar la pieza.
Capability
Formato autorizado para una credencial Partner, por ejemplo image, video o html5.
Scope
Conjunto de placements que una credencial puede consultar.
Sandbox
Entorno de integración y validación separado del uso productivo.

Flujo de integración

1. Usuario
→
Inicia la conexiónEl portal cautivo comienza su flujo normal.
2. Portal
→
Solicita una decisión a su backendNo expongas la API key de Givemefi en JavaScript del navegador.
3. Backend partner
→
Llama a POST /v1/deliveries/selectUsa Bearer auth, placement_key y X-Request-Id.
4. Givemefi
→
Devuelve 200 o 204200 contiene un descriptor de creative. 204 significa continuar sin anuncio.
5. Backend partner
→
Pasa el descriptor al portalLa API no “empuja” datos al navegador; el partner controla su propio flujo.
6. Portal
→
Renderiza la piezaUsa asset_url para IMAGE/VIDEO o render_url para HTML5 controlado.
7. Portal
→
Continúa WiFiTambién continúa ante 204, 429, 5xx o timeout.

Walled garden

En un portal cautivo, el navegador puede no tener acceso general a internet cuando se muestra la creatividad. Antes de una prueba funcional, permite en el walled garden los orígenes que Givemefi entregue durante el onboarding.

OrigenUsoQuién lo consume
{{base_url}}Partner Delivery API.Backend del partner.
{{asset_origin}}Assets temporales de IMAGE/VIDEO.Navegador/portal.
{{render_origin}}Runtime HTML5 cuando la capability esté habilitada.Iframe del portal.
ImportanteLos hostnames exactos de sandbox/producción se entregan durante onboarding. No asumas dominios a partir de los ejemplos. Si un asset o el renderer no está permitido antes de autenticación, la selección puede responder 200 pero el creative no cargará en el navegador.

Credenciales y soporte

Qué recibirás

  • Base URL del entorno.
  • API key Partner entregada por canal seguro.
  • placement_key autorizado.
  • Capabilities habilitadas.
  • Orígenes que debes permitir en el walled garden.

Soporte

El contacto técnico y el canal de escalamiento se comunican durante el onboarding. Para soporte comparte X-Request-Id, timestamp y código HTTP; nunca compartas la API key, signed URLs completas ni tokens de render.

Quickstart

  1. Guarda la API key únicamente en tu backend.
  2. Configura el walled garden.
  3. Obtén el placement_key de sandbox.
  4. Haz una solicitud con X-Request-Id.
  5. Si recibes 200, renderiza el descriptor; si recibes 204 o un fallo temporal, continúa WiFi.
cURL · selección
curl -sS -X POST "{{base_url}}/v1/deliveries/select" \
  -H "Authorization: Bearer $GIVEMEFI_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: wifi-session-001" \
  --data '{
    "placement_key": "{{placement_key}}",
    "session_id": "anonymous-session-7f3a",
    "context": {
      "locale": "es-CO",
      "device_type": "mobile",
      "screen_width": 390,
      "screen_height": 844
    }
  }'

Respuesta esperada

HTTP 200 · ejemplo IMAGE
{
  "status": "ready",
  "delivery_id": "uuid",
  "event_token": "opaque-token",
  "creative": {
    "type": "image",
    "mime_type": "image/jpeg",
    "asset_url": "https://...signed...",
    "asset_expires_in": 3600,
    "asset_expires_at": "2026-11-19T20:00:00Z",
    "width": 300,
    "height": 250,
    "landing_url": "https://example.com/landing"
  }
}

GET /v1/health

GET{{base_url}}/v1/health

Comprueba que el servicio está disponible. No requiere Bearer auth y no devuelve información sensible.

cURL
curl -sS "{{base_url}}/v1/health"
200
{"status":"ready","version":"v1"}

POST /v1/deliveries/select

POST{{base_url}}/v1/deliveries/select

Request

Campo/headerTipoRequeridoDescripción
AuthorizationheaderSíBearer <partner_api_key>.
X-Request-Idheader stringSí en esta guíaIdentificador de correlación. No implica idempotencia.
placement_keyUUIDSíPlacement entregado por Givemefi.
session_idstringNoSesión anónima/pseudónima. No envíes email, teléfono, MAC ni PII.
contextobjectNoContexto permitido de dispositivo/pantalla.

Campos permitidos en context

locale, device_type, os, browser, screen_width y screen_height. No envíes campos adicionales esperando que se persistan o utilicen.

200 · Creative disponible

CampoTipoPresenciaDescripción
statusstringSiempreready.
delivery_idUUIDSiempreIdentifica esta decisión de entrega.
event_tokenstringSiempreReservado para la futura API de eventos. No lo uses como credencial general.
creative.typeenumSiempreimage, video o html5 cuando esté habilitado.
creative.mime_typestringSiempreMIME validado por Givemefi.
creative.asset_urlURLIMAGE/VIDEOURL temporal para el asset.
creative.asset_expires_innumberIMAGE/VIDEOTTL en segundos; actualmente 3600.
creative.asset_expires_atdatetimeIMAGE/VIDEOVencimiento absoluto.
creative.render_urlURLHTML5URL opaca del renderer; no es un ZIP ni HTML crudo.
creative.render_expires_innumberHTML5TTL del render; actualmente 3600.
creative.render_expires_atdatetimeHTML5Vencimiento absoluto del render.
creative.width / heightintegerOpcionalSe incluyen juntos cuando están disponibles y son positivos.
creative.duration_secondsnumberVIDEO opcionalDuración cuando está disponible.
creative.landing_urlHTTPS URLIMAGE/VIDEO opcionalDestino de navegación. No significa por sí sola que el click quede medido por Givemefi.

204 · Sin inventario

Respuesta sin body. Continúa el flujo WiFi. Puede ocurrir si el placement no tiene un candidato elegible o si el formato disponible no está habilitado para la credencial.

IMAGE

Renderiza creative.asset_url como imagen y utiliza las dimensiones devueltas cuando estén presentes. La URL es temporal; no la conviertas en un recurso permanente ni compartido entre usuarios.

ClickSi existe landing_url, puede usarse como destino de navegación. En v0.2 no documentamos esa navegación como un click medido por Givemefi porque el endpoint Partner de eventos aún no está habilitado.

VIDEO

La API devuelve el MIME real del creative y duration_seconds cuando está disponible. El partner no debe inferir el formato por la extensión del URL.

ReproducciónEsta versión no establece todavía un contrato de códecs, peso máximo, autoplay o duración mínima de exposición. La experiencia de reproducción del portal debe respetar siempre el principio fail-open y no impedir el acceso WiFi.

HTML5 · capability controlada

HTML5 solo se entrega cuando la credencial tiene la capability html5, el placement la permite, existe un package listo y el origen de frame está autorizado.

Respuesta HTML5
{
  "status": "ready",
  "delivery_id": "uuid",
  "event_token": "opaque-token",
  "creative": {
    "type": "html5",
    "mime_type": "text/html",
    "render_url": "{{render_origin}}/v1/render/<ephemeral-token>/index.html",
    "render_expires_in": 3600,
    "render_expires_at": "2026-11-19T20:00:00Z",
    "width": 320,
    "height": 480
  }
}

Iframe de referencia

JavaScript
const creative = response.creative;
const frame = document.createElement('iframe');
frame.src = creative.render_url;
frame.width = String(creative.width ?? 320);
frame.height = String(creative.height ?? 480);
frame.sandbox = 'allow-scripts allow-popups';
frame.referrerPolicy = 'no-referrer';
frame.setAttribute('title', 'Publicidad');
document.querySelector('#ad-slot').replaceChildren(frame);
Sandbox HTML5El comportamiento adicional de popups/landings está todavía bajo certificación. No agregues permisos de sandbox por tu cuenta. Usa únicamente la política comunicada por Givemefi para tu integración.

El partner no recibe ZIP, storage_path, storage_bucket, package_id, creative_id ni manifiestos internos.

Reglas de uso de una delivery

PreguntaRegla v0.2
¿Una delivery equivale a una impresión?No. La selección y la impresión son conceptos distintos. La medición de impresión formará parte de Events.
¿Puedo reutilizar una delivery para varios usuarios?No recomendado. Trata cada decisión como asociada a su solicitud/sesión.
¿Puedo guardar permanentemente asset_url?No. Es temporal y tiene expiración.
¿Puedo cachear HTML5?No. El renderer utiliza política no-store.
¿Puedo hacer prefetch masivo?No está soportado como patrón contractual en esta versión.
¿Cómo solicito un formato o tamaño?No se solicita en el body. Lo determina el placement_key, la configuración de Givemefi, inventario elegible y capabilities de la credencial.

Click y medición

Events todavía no está disponible para integración Partner en esta versiónEl response incluye event_token para compatibilidad con el contrato futuro, pero no debes intentar reportar eventos a un endpoint no documentado.
ConceptoEstado v0.2
SelecciónDisponible mediante /deliveries/select.
ImpresiónNo se infiere automáticamente de una selección. API Partner de Events reservada.
Click IMAGE/VIDEOlanding_url es destino de navegación; esta guía no afirma que abrirla registre un evento en Givemefi.
Click HTML5Se gestiona dentro del runtime HTML5 controlado; el contrato externo de medición se publicará cuando Events quede certificado.
event_tokenResérvalo únicamente para la futura API de eventos si Givemefi te indica almacenarlo.

Retries, correlación y timeout

Usa X-Request-Id para correlacionar soporte y logs. En esta versión no se ofrece una garantía de idempotencia durable para /deliveries/select.

Un retry puede ser una nueva decisiónRepetir una selección puede producir un nuevo delivery_id y un nuevo event_token. No deduzcas que el mismo X-Request-Id deduplica solicitudes.
SituaciónAcción recomendada
200 dentro del presupuestoRenderiza la creatividad.
204Continúa WiFi.
429Respeta Retry-After para solicitudes futuras; no prolongues el acceso actual.
5xx / 503Continúa WiFi.
TimeoutAborta la espera y continúa WiFi.

Presupuesto recomendado: máximo 1.500 ms para la decisión publicitaria. No hagas reintentos síncronos que extiendan el acceso WiFi más allá de ese presupuesto.

HTTP y errores

HTTPSignificadoAcción del partner
200Creative listo.Renderiza el descriptor.
204Sin inventario elegible.Continúa WiFi.
400Request inválido.Corrige el request; no bloquees la sesión.
401Credencial ausente, inválida, revocada o de entorno incorrecto.No reintentes con la misma credencial sin corregirla.
403Placement fuera del scope autorizado.Verifica onboarding/scope.
413Request demasiado grande.Reduce el payload. El límite contractual exacto se comunicará con la versión operativa correspondiente.
429Cuota agotada.Respeta Retry-After; continúa WiFi.
503Servicio temporalmente no disponible.Fail-open; continúa WiFi.
Error JSON
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid placement_key."
  },
  "request_id": "wifi-session-001"
}

El catálogo completo y estable de error.code se publicará cuando quede congelado como contrato externo. No implementes lógica dependiente de mensajes humanos.

Seguridad y privacidad

Debes

  • Mantener la API key en backend/server-side.
  • Usar HTTPS.
  • Tratar signed URLs y render URLs como temporales.
  • Usar un session_id anónimo/pseudónimo.
  • Aplicar fail-open.
  • Permitir únicamente los orígenes entregados para el walled garden.

No debes

  • Exponer la API key en JavaScript del navegador.
  • Enviar email, teléfono, MAC u otra PII como session_id.
  • Persistir URLs temporales como assets permanentes.
  • Alterar permisos del iframe HTML5 sin coordinación.
  • Intentar acceder a Storage o IDs internos.

Ejemplos de integración

Node.js

Node.js · fetch
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 1500);

try {
  const r = await fetch(`${process.env.GIVEMEFI_BASE_URL}/v1/deliveries/select`, {
    method: 'POST',
    signal: controller.signal,
    headers: {
      'Authorization': `Bearer ${process.env.GIVEMEFI_PARTNER_API_KEY}`,
      'Content-Type': 'application/json',
      'X-Request-Id': crypto.randomUUID()
    },
    body: JSON.stringify({ placement_key: process.env.GIVEMEFI_PLACEMENT_KEY, context: {} })
  });

  if (r.status === 204) return null;
  if (!r.ok) return null; // fail-open
  return await r.json();
} finally {
  clearTimeout(timer);
}

Python

Python · requests
import os, uuid, requests

try:
    r = requests.post(
        f"{os.environ['GIVEMEFI_BASE_URL']}/v1/deliveries/select",
        headers={
            "Authorization": f"Bearer {os.environ['GIVEMEFI_PARTNER_API_KEY']}",
            "Content-Type": "application/json",
            "X-Request-Id": str(uuid.uuid4()),
        },
        json={"placement_key": os.environ["GIVEMEFI_PLACEMENT_KEY"], "context": {}},
        timeout=1.5,
    )
    delivery = None if r.status_code == 204 or not r.ok else r.json()
except requests.RequestException:
    delivery = None  # fail-open

Estos ejemplos muestran el patrón de control de timeout y fail-open; adapta observabilidad, circuit breakers y gestión de secretos a tu plataforma.

Checklist de integración

  • Base URL y API key recibidas por canal seguro.
  • placement_key de sandbox confirmado.
  • Walled garden configurado.
  • API key solo en backend.
  • Timeout máximo de 1.500 ms aplicado.
  • 200 IMAGE/VIDEO procesado.
  • 204 continúa WiFi.
  • 401/403/429/503 continúan WiFi sin bloquear al usuario.
  • URLs temporales no se guardan como recursos permanentes.
  • X-Request-Id se registra para soporte.
  • HTML5 solo se habilita si Givemefi confirma capability y origen.

Changelog

Versión docsFechaCambios
0.22026-11-19Walled garden, glosario, secuencia, reglas de uso, tracking explícito, retries, tablas de campos, Node/Python, accesibilidad, tono e infraestructura desacoplada.
0.12026-11-19Primera guía pública de referencia para Partner Delivery API.
Recursos descargablesOpenAPI y colección Postman se incorporarán al paquete de integración cuando el contrato operativo quede congelado. Esta documentación no publica endpoints o códigos que todavía no estén certificados para partners.