# Neike API

> API pública de Neike — mensajería sobre WhatsApp, Instagram y Messenger vía una sola API. JSON sobre HTTPS bajo `/api`, autenticado con API key (`x-neike-api-key: whk_live_…`) o JWT de usuario de la consola.

## Docs

- [OpenAPI spec](https://api.neike.dev/api/openapi.json): contrato máquina completo — paths, schemas y auth.
- [Referencia interactiva (Scalar)](https://api.neike.dev/api/docs): explorador navegable de la API.
- [Documentación completa para agentes](https://api.neike.dev/api/llms-full.txt): cada endpoint con su firma y schema, en texto plano.

## Endpoints

- `GET /api/embed/ads-sessions` — Listar sesiones de conexión de anuncios del cliente
- `POST /api/embed/ads-sessions` — Crear una sesión embebible de conexión de anuncios
- `GET /api/embed/ads-sessions/{sessionId}` — Estado y resultado de una sesión de conexión de anuncios
- `POST /api/embed/ads-sessions/{sessionId}/revoke` — Revocar una sesión antes de que se use
- `GET /api/embed/sessions` — Listar sesiones de signup del cliente
- `POST /api/embed/sessions` — Crear una sesión de signup embebible
- `GET /api/embed/sessions/{sessionId}` — Estado y resultado de una sesión
- `POST /api/embed/sessions/{sessionId}/revoke` — Revocar una sesión antes de que se use
- `GET /api/marketing/ad-accounts` — Listar cuentas publicitarias
- `GET /api/marketing/ad-accounts/{id}` — Detalle de una cuenta publicitaria
- `PATCH /api/marketing/ad-accounts/{id}` — Activar o pausar una cuenta publicitaria
- `DELETE /api/marketing/ad-accounts/{id}` — Desconectar una cuenta publicitaria
- `POST /api/marketing/ad-accounts/{id}/refresh` — Resincronizar con Meta
- `GET /api/marketing/ads` — Listar anuncios
- `POST /api/marketing/ads` — Crear un anuncio
- `GET /api/marketing/ads/{adId}` — Detalle de un anuncio
- `PATCH /api/marketing/ads/{adId}` — Editar un anuncio
- `DELETE /api/marketing/ads/{adId}` — Borrar un anuncio
- `GET /api/marketing/adsets` — Listar conjuntos de anuncios
- `POST /api/marketing/adsets` — Crear un conjunto de anuncios
- `GET /api/marketing/adsets/{adSetId}` — Detalle de un conjunto de anuncios
- `PATCH /api/marketing/adsets/{adSetId}` — Editar un conjunto de anuncios
- `DELETE /api/marketing/adsets/{adSetId}` — Borrar un conjunto de anuncios
- `GET /api/marketing/campaigns` — Listar campañas
- `POST /api/marketing/campaigns` — Crear una campaña
- `GET /api/marketing/campaigns/{campaignId}` — Detalle de una campaña
- `PATCH /api/marketing/campaigns/{campaignId}` — Editar una campaña
- `DELETE /api/marketing/campaigns/{campaignId}` — Borrar una campaña
- `GET /api/marketing/creatives` — Listar creatividades
- `POST /api/marketing/creatives` — Crear una creatividad
- `GET /api/marketing/creatives/{creativeId}` — Detalle de una creatividad
- `DELETE /api/marketing/creatives/{creativeId}` — Borrar una creatividad
- `GET /api/marketing/creatives/images` — Resolver imágenes por hash
- `GET /api/marketing/enums` — Catálogo de enums de la Marketing API
- `POST /api/marketing/images` — Subir una imagen
- `GET /api/marketing/insights` — Métricas de entrega
- `POST /api/marketing/insights/reports` — Pedir un reporte asincrónico
- `GET /api/marketing/insights/reports/{reportRunId}` — Avance de un reporte asincrónico
- `GET /api/marketing/insights/reports/{reportRunId}/results` — Resultados de un reporte asincrónico
- `POST /api/marketing/oauth/exchange` — Canjear el code de Meta
- `GET /api/marketing/oauth/url` — URL para conectar una cuenta publicitaria
- `GET /api/marketing/pages` — Páginas de Facebook del usuario
- `GET /api/marketing/terms` — Estado de la aceptación de responsabilidad
- `POST /api/marketing/terms/accept` — Aceptar la responsabilidad por el gasto publicitario
- `POST /api/marketing/videos` — Subir un video
- `GET /api/marketing/videos/{videoId}` — Estado de un video
- `POST /api/outbound/send` — Enviar mensaje
- `DELETE /api/templates/delete` — Borrar plantilla
- `POST /api/templates/list` — Listar plantillas
- `POST /api/templates/submit` — Crear/enviar plantilla a aprobación
- `GET /api/webhooks/config` — Config de webhook del cliente
- `PATCH /api/webhooks/config` — Actualizar config de webhook
- `POST /api/webhooks/config/generate-secret` — Generar token de webhook
- `PATCH /api/webhooks/dispatch/{platform}` — Prender o apagar el despacho de una plataforma o de un servicio

## Webhooks entrantes (tu backend los recibe)

Además de los endpoints de arriba (que TU llamás), Neike le hace `POST` a **tu**
backend cuando entra un mensaje o cambia un estado. Configurás la URL base y un token
(`webhook_secret`, write-only: se muestra una única vez al generarlo) desde Neike o vía
`PATCH /api/webhooks/config`. En cada dispatch mandamos la cabecera `x-webhook-token`
con ese token; validalo antes de procesar.

- `POST {tu_url}/chat/whatsapp/receive` — mensaje entrante de WhatsApp `{ event, channel, contact, message }`
- `POST {tu_url}/chat/instagram/receive` — mensaje entrante de Instagram
- `POST {tu_url}/chat/facebook/receive` — mensaje entrante de Facebook Messenger
- `POST {tu_url}/chat/whatsapp/update` — estado del mensaje (`sent|delivered|read|failed`)
- `POST {tu_url}/chat/updateTemplateStatus` — estado de una plantilla (`APPROVED|REJECTED|…`)
- `POST {tu_url}/ads/events` — eventos de anuncios de Meta (`ad_account.*`, `ads.connected`, `campaign.*`, `adset.*`, `ad.*`, `adcreative.*`)
- `POST {tu_url}/channels/connected` — `channel.connected` del signup embebido

Contrato completo (payloads exactos, tipos de mensaje, adjuntos): https://api.neike.dev/api/llms-full.txt

Además existe un **servidor MCP** en `https://api.neike.dev/mcp` (OAuth automático o API key) para
conectar agentes de IA directo a los canales. Guía: https://docs.neike.dev/en/guides/mcp/

Y si tus propios clientes conectan SUS números, el onboarding se embebe en tu app con un
iframe (`POST /api/embed/sessions` → `embed_url`). El sandbox con `allow-popups` es
obligatorio y el tema se declara con `?theme=light|dark|system`, porque el iframe no puede
leer el de tu página. Detalle: https://api.neike.dev/api/llms-full.txt