Informe de inteligencia de empresa

Proporciona un sitio web y un objetivo, y recibe un informe estructurado sobre la empresa con el que tu propio modelo de IA o tu equipo pueden trabajar de inmediato: qué vende la empresa y a quién, el mercado y el lenguaje de los compradores, los competidores reales, qué preguntan y qué objeciones plantean los compradores en debates públicos, y un plan de acción listo para el objetivo elegido. Cada dato factual enlaza con la evidencia de la que procede.

Un informe sirve a un único objetivo:

focus	Pensado para
reddit_promotion	promocionar la empresa en Reddit: comunidades relevantes, búsquedas que hacen aparecer hilos pertinentes, preguntas y objeciones de los compradores, afirmaciones seguras
seo_web	promocionar la empresa en buscadores: consultas comerciales por intención, quién ocupa hoy los resultados, carencias de contenido
competitor_intel	estudiar la empresa como competidor: posicionamiento, precios, funcionalidades, de qué se quejan sus clientes

Un segundo objetivo para la misma empresa es una segunda petición. Durante 7 días reutiliza la lectura del sitio y el perfil de la empresa del primer informe, así que empieza antes y ambos informes describen la empresa de la misma manera; el trabajo muestra "core_reused": true.

La inteligencia de empresa se activa para una clave bajo petición: escribe a support@omev.be. El informe se cobra del saldo habitual de la clave.

Profundidad y precio

depth	Precio por informe entregado	Qué incluye
standard (por defecto)	$0.99	el informe de la empresa sin la voz de la audiencia: 3–6 competidores y la búsqueda estándar; las secciones con la voz de los compradores se marcan como no incluidas
extended	$1.99	todo lo de standard, más la voz de la audiencia (hasta 300 comentarios de compradores leídos, con foros y otras fuentes añadidas en nichos estrechos), 7–8 competidores y una búsqueda más amplia

Pagas una sola vez por informe, cuando descargas por primera vez un resultado terminado, según lo completo que esté:

Grado de completitud del informe	Cobro
75 % o más	el precio completo
40–74 %	el 70 % del precio
15–39 %	el 30 % del precio
menos del 15 %	gratis

Un cobro parcial se redondea a la baja a céntimos enteros. El trabajo muestra completeness_percent y charged_usd. No se cobran los informes que fallan, los sitios que no podemos leer, los trabajos cancelados ni las descargas repetidas del mismo informe. Un informe de dominio incluye el informe extendido junto con la investigación de comunidades y de visibilidad en IA.

Iniciar un informe

curl -sS https://llmapi.omev.be/v1/cig/jobs/create \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://vessi.com",
    "focus": "reddit_promotion",
    "depth": "standard",
    "client_ref": "acme-client-17",
    "idempotency_key": "acme-17-vessi-reddit-2026-09"
  }'

Campo	Requerido	Significado
url	sí	el sitio web de la empresa; una dirección pública http/https
focus	sí	uno de reddit_promotion, seo_web, competitor_intel
depth	no	standard (por defecto) o extended
market	no	un país o una región, como "US", o una lista de hasta 10, como ["EU", "DE"]
language	no	un código de idioma como "en", o una lista de hasta 6, como ["en", "de"]
voice	no	en nombre de quién hablan las respuestas sugeridas: brand (por defecto) o community_member; OmevAI nunca publica nada
max_age_days	no	de 1 a 1830; los hilos de debate más antiguos quedan fuera del plan de acción
client_ref	no	tu propia etiqueta para el cliente final (agencias: desglosar el gasto por cliente)
idempotency_key	no	de 8 a 200 caracteres; repetirla devuelve el mismo trabajo en lugar de iniciar uno nuevo
callback_url	no	una dirección pública https a la que llamamos cuando el informe termina (consulta Notificación)
callback_secret	no	de 16 a 200 caracteres; con él, cada notificación va firmada

Antes de iniciar un informe, comprobamos que el saldo de tu clave cubre su precio. Si no lo cubre, la respuesta es 402 INSUFFICIENT_BALANCE y no se inicia nada.

La respuesta es 202 con el trabajo:

{
  "job": {"id": "cig_…", "status": "queued", "stage": "", "focus": "reddit_promotion",
          "depth": "standard", "client_ref": "acme-client-17", "charged_usd": 0},
  "idempotent_replay": false,
  "poll_after_seconds": 10
}

Varios sitios a la vez

Envía hasta 50 informes en una sola llamada. Cada elemento admite los mismos campos que un informe individual.

curl -sS https://llmapi.omev.be/v1/cig/jobs/batch \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"url": "https://vessi.com", "focus": "reddit_promotion", "client_ref": "acme-17"},
      {"url": "https://vessi.com", "focus": "seo_web", "client_ref": "acme-17"},
      {"url": "https://allbirds.com", "focus": "competitor_intel", "client_ref": "acme-17",
       "callback_url": "https://hooks.example.com/omev", "callback_secret": "a-long-random-secret"}
    ]
  }'

La respuesta es 202 con una entrada por elemento, en el mismo orden. Un elemento con un error recibe su propio error y no detiene a los demás:

{
  "items": [
    {"index": 0, "job": {"id": "cig_…", "status": "queued", …}, "idempotent_replay": false},
    {"index": 1, "job": {"id": "cig_…", "status": "queued", …}, "idempotent_replay": false},
    {"index": 2, "error": {"code": "INVALID_URL", "message": "…"}}
  ],
  "poll_after_seconds": 10
}

El saldo debe cubrir todos los elementos válidos juntos; de lo contrario, la llamada devuelve 402 INSUFFICIENT_BALANCE y no se inicia ningún elemento. Dos objetivos para el mismo sitio en una misma llamada comparten una sola lectura del sitio.

Seguimiento del trabajo

Un informe standard tarda entre 10 y 25 minutos, uno extended hasta aproximadamente una hora: el servicio lee el sitio, realiza búsquedas, analiza a los competidores y lee los debates de los compradores. Consulta el estado cada 15–30 segundos.

curl -sS https://llmapi.omev.be/v1/cig/jobs/get \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "cig_…"}'

status pasa por queued, running y después uno de completed, partial, failed, cancelled. Durante la ejecución, stage indica en qué punto está el trabajo, por ejemplo site_read, business_mix, profile_extract, research_plan, market_frame, competitors, search, communities, audience, claim_verify, synthesis, thread_tone, moderation. Un informe que reutiliza una lectura anterior del sitio muestra site_core_reused en lugar de los tres primeros valores. Toma la lista como orientativa: pueden aparecer pasos nuevos.

partial es un informe entregado en el que alguna parte no se completó; el motivo figura en evidence_base.limitations, y evidence_base.coverage.completeness muestra cada sección con lo encontrado, su objetivo y su mínimo. Con failed, error.code indica la causa, por ejemplo site_unreadable cuando el sitio bloquea las visitas automatizadas.

Para detener un trabajo, envía el mismo cuerpo a /v1/cig/jobs/cancel.

Notificación cuando el informe está listo

Con callback_url no necesitas consultar el estado. Cuando el trabajo llega a completed, partial, failed o cancelled, enviamos un POST a esa dirección:

{"event": "cig.job.finished", "job": {"id": "cig_…", "status": "completed", …}}

Cabecera	Significado
X-Omev-Event-Id	el id del trabajo; úsalo para ignorar entregas repetidas
X-Omev-Signature	sha256= seguido del HMAC-SHA256 en hexadecimal del cuerpo sin procesar, calculado con tu callback_secret (solo se envía si indicaste un secreto)

Responde con cualquier estado 2xx. Si la llamada falla, lo intentamos dos veces más, a los 10 segundos y a los 60 segundos. El resultado se muestra en job.callback_status. La notificación solo incluye el trabajo; descarga el informe con /v1/cig/jobs/result como de costumbre.

Comprueba la firma antes de confiar en el cuerpo:

import hashlib, hmac

def is_from_omev(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

Descargar el informe

curl -sS https://llmapi.omev.be/v1/cig/jobs/result \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "cig_…"}'

La respuesta contiene job, profile (el informe completo) y stage1 (un resumen breve del mismo informe con diez campos). Antes de que termine el trabajo, la llamada devuelve 409 JOB_NOT_READY.

El informe tiene nueve secciones:

Sección	Contenido
meta	objetivo, profundidad, URL de destino, mercado, fecha de generación
company	producto, posicionamiento, composición del negocio, funcionalidades, oferta, señales de confianza
market	perfil del comprador (ICP), marco del mercado, palabras clave, consultas de los compradores
problems	problemas que resuelve la marca, frustraciones en la categoría
brand_perception	quejas, elogios y menciones encontrados en fuentes públicas
competition	competidores (direct, adjacent, status_quo) con el motivo por el que cada uno compite
audience	preguntas, objeciones y expectativas de los compradores, citas literales de compradores
playbook	el plan para el objetivo: comunidades, búsquedas, mensajes, próximas acciones, límites para las afirmaciones
evidence_base	todas las fuentes y citas en las que se basa el informe, cifras de cobertura, limitaciones

Los elementos incluyen evidence_ids, que apuntan a evidence_base.evidence, donde cada entrada tiene la url de la fuente y la cita exacta en quote. Las afirmaciones se marcan como stated (lo dice la propia empresa), observed (visto en fuentes independientes) o inferred (nuestra conclusión). Cuando pases el informe a un modelo de IA, indícale que presente como hechos solo los elementos stated y observed, y que nunca use nada de lo que figura en playbook.reply_guardrails.do_not_claim.

Errores

Código	Cuándo
401	clave de API ausente o no válida
402 INSUFFICIENT_BALANCE	el saldo de la clave no cubre el informe (o todos los elementos válidos de una llamada con varios sitios)
404 JOB_NOT_FOUND	trabajo desconocido, o un trabajo que pertenece a otra cuenta
409 JOB_NOT_READY	se pidió el resultado antes de que terminara el trabajo
422 INVALID_URL	la dirección no es un sitio web público
422 INVALID_FOCUS, 422 INVALID_DEPTH, 422 INVALID_VOICE	un valor fuera de las listas anteriores
422 INVALID_MARKET, 422 INVALID_LANGUAGE, 422 INVALID_MAX_AGE, 422 INVALID_IDEMPOTENCY_KEY	un campo fuera de rango: más de 10 mercados, más de 6 códigos de idioma, una antigüedad fuera de 1–1830 días, una clave fuera de 8–200 caracteres
422 INVALID_CALLBACK_URL, 422 INVALID_CALLBACK_SECRET	la dirección de notificación no es una dirección pública https, o el secreto no tiene de 16 a 200 caracteres
422 INVALID_REQUEST, 422 BATCH_TOO_LARGE	una llamada con varios sitios sin elementos, con un elemento que no es un objeto o con más de 50 elementos
429	demasiadas peticiones; vuelve a intentarlo tras una breve pausa

Todos los errores tienen la misma forma: {"error": {"code": "INVALID_FOCUS", "message": "…"}}. Un 401 por una clave incorrecta y un 429 funcionan igual en todas las API de OmevAI; consulta Errores para ver su formato.