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.
/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.Disponibilidad v0.2
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_keydetermina 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
creativecon la información necesaria para renderizar la pieza. - Capability
- Formato autorizado para una credencial Partner, por ejemplo
image,videoohtml5. - 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
POST /v1/deliveries/selectUsa Bearer auth, placement_key y X-Request-Id.asset_url para IMAGE/VIDEO o render_url para HTML5 controlado.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.
| Origen | Uso | Quié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. |
Credenciales y soporte
Qué recibirás
- Base URL del entorno.
- API key Partner entregada por canal seguro.
placement_keyautorizado.- 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
- Guarda la API key únicamente en tu backend.
- Configura el walled garden.
- Obtén el
placement_keyde sandbox. - Haz una solicitud con
X-Request-Id. - Si recibes 200, renderiza el descriptor; si recibes 204 o un fallo temporal, continúa WiFi.
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
{
"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
Comprueba que el servicio está disponible. No requiere Bearer auth y no devuelve información sensible.
curl -sS "{{base_url}}/v1/health"{"status":"ready","version":"v1"}POST /v1/deliveries/select
Request
| Campo/header | Tipo | Requerido | Descripción |
|---|---|---|---|
Authorization | header | Sí | Bearer <partner_api_key>. |
X-Request-Id | header string | Sí en esta guía | Identificador de correlación. No implica idempotencia. |
placement_key | UUID | Sí | Placement entregado por Givemefi. |
session_id | string | No | Sesión anónima/pseudónima. No envíes email, teléfono, MAC ni PII. |
context | object | No | Contexto 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
| Campo | Tipo | Presencia | Descripción |
|---|---|---|---|
status | string | Siempre | ready. |
delivery_id | UUID | Siempre | Identifica esta decisión de entrega. |
event_token | string | Siempre | Reservado para la futura API de eventos. No lo uses como credencial general. |
creative.type | enum | Siempre | image, video o html5 cuando esté habilitado. |
creative.mime_type | string | Siempre | MIME validado por Givemefi. |
creative.asset_url | URL | IMAGE/VIDEO | URL temporal para el asset. |
creative.asset_expires_in | number | IMAGE/VIDEO | TTL en segundos; actualmente 3600. |
creative.asset_expires_at | datetime | IMAGE/VIDEO | Vencimiento absoluto. |
creative.render_url | URL | HTML5 | URL opaca del renderer; no es un ZIP ni HTML crudo. |
creative.render_expires_in | number | HTML5 | TTL del render; actualmente 3600. |
creative.render_expires_at | datetime | HTML5 | Vencimiento absoluto del render. |
creative.width / height | integer | Opcional | Se incluyen juntos cuando están disponibles y son positivos. |
creative.duration_seconds | number | VIDEO opcional | Duración cuando está disponible. |
creative.landing_url | HTTPS URL | IMAGE/VIDEO opcional | Destino 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.
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.
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.
{
"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
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);El partner no recibe ZIP, storage_path, storage_bucket, package_id, creative_id ni manifiestos internos.
Reglas de uso de una delivery
| Pregunta | Regla 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
event_token para compatibilidad con el contrato futuro, pero no debes intentar reportar eventos a un endpoint no documentado.| Concepto | Estado v0.2 |
|---|---|
| Selección | Disponible mediante /deliveries/select. |
| Impresión | No se infiere automáticamente de una selección. API Partner de Events reservada. |
| Click IMAGE/VIDEO | landing_url es destino de navegación; esta guía no afirma que abrirla registre un evento en Givemefi. |
| Click HTML5 | Se gestiona dentro del runtime HTML5 controlado; el contrato externo de medición se publicará cuando Events quede certificado. |
event_token | Resé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.
delivery_id y un nuevo event_token. No deduzcas que el mismo X-Request-Id deduplica solicitudes.| Situación | Acción recomendada |
|---|---|
| 200 dentro del presupuesto | Renderiza la creatividad. |
| 204 | Continúa WiFi. |
| 429 | Respeta Retry-After para solicitudes futuras; no prolongues el acceso actual. |
| 5xx / 503 | Continúa WiFi. |
| Timeout | Aborta 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
| HTTP | Significado | Acción del partner |
|---|---|---|
| 200 | Creative listo. | Renderiza el descriptor. |
| 204 | Sin inventario elegible. | Continúa WiFi. |
| 400 | Request inválido. | Corrige el request; no bloquees la sesión. |
| 401 | Credencial ausente, inválida, revocada o de entorno incorrecto. | No reintentes con la misma credencial sin corregirla. |
| 403 | Placement fuera del scope autorizado. | Verifica onboarding/scope. |
| 413 | Request demasiado grande. | Reduce el payload. El límite contractual exacto se comunicará con la versión operativa correspondiente. |
| 429 | Cuota agotada. | Respeta Retry-After; continúa WiFi. |
| 503 | Servicio temporalmente no disponible. | Fail-open; continúa WiFi. |
{
"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_idanó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
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
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-openEstos 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_keyde 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-Idse registra para soporte.- HTML5 solo se habilita si Givemefi confirma capability y origen.
Changelog
| Versión docs | Fecha | Cambios |
|---|---|---|
| 0.2 | 2026-11-19 | Walled garden, glosario, secuencia, reglas de uso, tracking explícito, retries, tablas de campos, Node/Python, accesibilidad, tono e infraestructura desacoplada. |
| 0.1 | 2026-11-19 | Primera guía pública de referencia para Partner Delivery API. |