--- title: "API y MCP de Valyzer — eventos geopolíticos y regulatorios con evidencia" description: "Eventos geopolíticos y regulatorios estructurados y bitemporales, con la evidencia en cada campo, vía API REST y MCP. Sandbox gratis, sin tarjeta." canonical: https://valyzer.com/es/for-developers last_updated: 2026-11-03 --- # API y MCP de Valyzer — eventos geopolíticos y regulatorios con evidencia > Una API para sanciones, cambios regulatorios, activos críticos y exposición. Cada valor, con su evidencia. Page: https://valyzer.com/es/for-developers ## Tu agente habla con seguridad de un mundo que no ve. - Los modelos responden sobre sanciones, aranceles y regulación con datos de entrenamiento desfasados, o se lo inventan. - La búsqueda web devuelve titulares, no la fuente oficial, la fecha ni lo que cambió. - Construirlo tú mismo implica vigilar cada día boletines, listas de sanciones y tribunales, en muchos idiomas. ## La misma pregunta. Una respuesta que puedes comprobar. ¿Qué controles a la exportación anunció China en abril de 2025? - Sin Valyzer: Mi conocimiento tiene una fecha de corte, así que puede que me falten anuncios recientes. China ya ha usado controles a la exportación, pero no puedo confirmar qué se anunció en abril de 2025. Consulta las fuentes oficiales. - Con Valyzer: El 4 de abril de 2025, el Ministerio de Comercio de China (MOFCOM) publicó nuevas restricciones a la exportación. Severidad: alta. (MOFCOM · 2025-04-04 · hecho) Cada respuesta lleva su fuente y su fecha, y dice «sin datos» en lugar de adivinar. ## Lanza la función, no el pipeline. - **Alertas de sanciones dentro de tu herramienta de compras**: Tus usuarios reciben un aviso cuando sancionan a un proveedor. - **Riesgo de rutas y puertos en tu copiloto de logística**: Tus usuarios ven qué puertos de su ruta tienen eventos activos. - **Un feed de cambios regulatorios para tu agente de compliance**: Tus usuarios saben qué cambió, con la fuente oficial. ## Vigilar un perímetro Valyzer no guarda perímetros de los usuarios de la API o MCP ni envía notificaciones ni webhooks. Tu app guarda el perímetro de cada usuario y consulta. 1. Guarda el perímetro de cada usuario en tu app: códigos `country` ISO-2, ids de entidad (de `search_entities` / `GET /v1/entities`) y códigos de `type` de evento. 2. Consulta `search_events` / `GET /v1/events` con los filtros `country`, `entity` y `type` (cada uno repetible, p. ej. `?country=CN&country=TW&entity=&type=`). 3. Para consultas incrementales llama a `list_event_changes` / `GET /v1/events/changes?since=<última consulta>`. Devuelve eventos nuevos, corregidos y retirados, pero no se puede filtrar por perímetro: conserva los elementos cuyo evento encaje con el perímetro (obtenlo con `get_event` / `GET /v1/events/{id}` si necesitas sus países o entidades) y guarda `meta.until` como el siguiente `since`. ## En tu agente en un minuto. Dale el encargo a tu agente de código o añade Valyzer a las herramientas de IA que ya usas. Un solo registro, las mismas reglas de evidencia, la misma cuota. ### Pega esto en tu agente de código ```text Añade Valyzer a este proyecto. Lee https://valyzer.com/es/for-developers.md y la especificación OpenAPI en https://api.valyzer.com/v1/openapi.json. Llama a la API REST con la cabecera X-Api-Key tomada de la variable de entorno VALYZER_API_KEY. Usa GET /v1/changes?since=… para la sincronización incremental y muestra la evidencia de cada afirmación (sourceName, publishedAt) allí donde se muestren los datos. ``` ### Cliente MCP URL del servidor MCP: https://api.valyzer.com/v1/mcp #### claude.ai Funciona en la web y en la app. 1. Abre Ajustes y entra en Conectores. 2. Elige Añadir conector personalizado. 3. Pega la URL de abajo. 4. Inicia sesión para aprobar. No hay clave que copiar. URL del servidor MCP: ``` https://api.valyzer.com/v1/mcp ``` #### ChatGPT Añádelo como conector personalizado en ChatGPT. 1. Abre Ajustes y entra en Conectores. 2. Elige Añadir conector personalizado. 3. Pega la URL de abajo. 4. Inicia sesión para aprobar. No hay clave que copiar. URL del servidor MCP: ``` https://api.valyzer.com/v1/mcp ``` #### Claude Desktop No hace falta ningún archivo de configuración. 1. Abre Ajustes y entra en Conectores. 2. Elige Añadir conector personalizado. 3. Pega la URL de abajo. 4. Inicia sesión para aprobar. No hay clave que copiar. URL del servidor MCP: ``` https://api.valyzer.com/v1/mcp ``` Sin interfaz, con clave API: ``` { "mcpServers": { "valyzer": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.valyzer.com/v1/mcp", "--header", "X-Api-Key:${VALYZER_API_KEY}" ], "env": { "VALYZER_API_KEY": "vyz_..." } } } } ``` #### Claude Code Inicia sesión con OAuth la primera vez que uses una herramienta de Valyzer. terminal: ``` claude mcp add --transport http valyzer https://api.valyzer.com/v1/mcp ``` Sin interfaz, con clave API: ``` claude mcp add --transport http valyzer https://api.valyzer.com/v1/mcp \ --header "X-Api-Key: vyz_..." ``` #### Cursor Un clic y, cuando Cursor lo pida, inicia sesión. ~/.cursor/mcp.json: ``` { "mcpServers": { "valyzer": { "url": "https://api.valyzer.com/v1/mcp" } } } ``` Sin interfaz, con clave API: ``` { "mcpServers": { "valyzer": { "url": "https://api.valyzer.com/v1/mcp", "headers": { "X-Api-Key": "${env:VALYZER_API_KEY}" } } } } ``` #### VS Code Un clic y, cuando VS Code lo pida, inicia sesión. .vscode/mcp.json: ``` { "servers": { "valyzer": { "type": "http", "url": "https://api.valyzer.com/v1/mcp" } } } ``` Sin interfaz, con clave API: ``` { "inputs": [ { "type": "promptString", "id": "valyzer-api-key", "description": "Valyzer API key", "password": true } ], "servers": { "valyzer": { "type": "http", "url": "https://api.valyzer.com/v1/mcp", "headers": { "X-Api-Key": "${input:valyzer-api-key}" } } } } ``` Para clientes sin interfaz y CI, envía tu clave API en la cabecera X-Api-Key. Sustituye vyz_... por tu clave. Herramientas MCP: - Search published events - Get one event with evidence - Get an event's revision history - Search entities - Get one entity - Get a country brief - Search the world atlas - List impact changes since a date - List event changes since a date (incremental sync) - List entity changes since a date (incremental sync) ## Una respuesta que tu agente puede citar. Quédate en el nivel que necesites. Nada es un resumen: cada capa apunta a la anterior. 1. **Fuente**: Boletín, lista de sanciones, tribunal o prensa. Con derechos aprobados. 2. **Evidencia**: Localizador exacto, URL y fecha de publicación. 3. **Afirmación**: Hecho o inferencia. Nunca mezclados. 4. **Evento**: Tipado, con severidad, localizado y vinculado a entidades. 5. **Impacto**: Dirección, mecanismo, horizonte y confianza 0–1. Dos ejes de tiempo en cada registro: `asOf` (cuándo fue cierto) and `knownAt` (cuándo se supo). Cada corrección es una versión nueva. Nada se sobrescribe. - Los hechos y las inferencias nunca se mezclan. - Null donde la cobertura es escasa, nunca un cero inventado. - Las correcciones son versiones nuevas que puedes reproducir con knownAt. ## Pregúntalo como lo dirías - **Compliance y KYC**: "¿Han sancionado hoy a algún proveedor de mi lista?" (`/v1/changes`, `/v1/entities`, `/v1/events`) - **Cadena de suministro**: "¿Qué puertos de mi ruta Asia–Europa tienen eventos activos?" (`/v1/world/search`, `/v1/world/paths`, `/v1/events`) - **Energía y materias primas**: "¿Qué terminales de GNL están expuestas a la tensión UE–Rusia?" (`/v1/world/tension`, `/v1/world/exposure`, `/v1/world/search`) - **Legal y regulatorio**: "¿Qué cambió en controles de exportación desde el 1 de octubre, según se supo entonces?" (`/v1/events`, `/v1/events/:id/history`, `/v1/changes`) - **Riesgo y seguros**: "¿Qué países de mi cartera están más expuestos ahora?" (`/v1/world/exposure`, `/v1/world/tension`, `/v1/entities`) - **Investigación y medios**: "Muéstrame cada corrección de este evento y su evidencia." (`/v1/events/:id/history`, `/v1/events`, `/v1/entities`) ## Llama a la API REST desde cualquier lenguaje. Tres peticiones cubren la mayoría de integraciones. Cada afirmación lleva su evidencia y cada registro, sus dos ejes de tiempo: asOf, cuándo fue cierto; knownAt, cuándo se supo. ### GET /v1/events Busca eventos publicados. Filtra por tipo, país, entidad y tiempo, ahora o según se supo en una fecha pasada. ```bash curl -G https://api.valyzer.com/v1/events \ -H "X-Api-Key: $VALYZER_API_KEY" \ -d type=export_restriction -d country=CN \ -d knownAt=2025-04-30T00:00:00Z ``` ```ts const url = new URL("https://api.valyzer.com/v1/events"); url.search = new URLSearchParams({ type: "export_restriction", country: "CN", knownAt: "2025-04-30T00:00:00Z", }).toString(); const res = await fetch(url, { headers: { "X-Api-Key": process.env.VALYZER_API_KEY! }, }); if (!res.ok) throw new Error(`Valyzer ${res.status}`); const { data } = await res.json(); ``` ```python import os import requests res = requests.get( "https://api.valyzer.com/v1/events", headers={"X-Api-Key": os.environ["VALYZER_API_KEY"]}, params={"type": "export_restriction", "country": "CN", "knownAt": "2025-04-30T00:00:00Z"}, ) res.raise_for_status() data = res.json()["data"] ``` Respuesta, abreviada (200 OK): ```json { "data": [{ "type": "export_restriction", "severity": "high", "occurrence": { "from": "2025-04-04T00:00:00Z" }, "claims": [{ "kind": "fact", "confidence": 0.95, "evidence": [{ "sourceName": "MOFCOM", "publishedAt": "2025-04-04T00:00:00Z" }] }], "impacts": [{ "direction": "negative", "horizon": "short_term", "confidence": 0.6 }], "updatedAt": "2025-04-07T09:12:00Z" }] } ``` ### GET /v1/changes Sincroniza lo que cambió desde una fecha. Consulta con since para recibir los impactos que se supieron o se corrigieron. Nada se sobrescribe, así que tu copia no se desfasa. ```bash curl -G https://api.valyzer.com/v1/changes \ -H "X-Api-Key: $VALYZER_API_KEY" \ -d since=2025-04-01T00:00:00Z ``` ```ts const url = new URL("https://api.valyzer.com/v1/changes"); url.search = new URLSearchParams({ since: "2025-04-01T00:00:00Z", }).toString(); const res = await fetch(url, { headers: { "X-Api-Key": process.env.VALYZER_API_KEY! }, }); if (!res.ok) throw new Error(`Valyzer ${res.status}`); const { data } = await res.json(); ``` ```python import os import requests res = requests.get( "https://api.valyzer.com/v1/changes", headers={"X-Api-Key": os.environ["VALYZER_API_KEY"]}, params={"since": "2025-04-01T00:00:00Z"}, ) res.raise_for_status() data = res.json()["data"] ``` Respuesta, abreviada (200 OK): ```json { "data": [{ "kind": "added", "changedAt": "2025-04-07T09:12:00Z", "impact": { "direction": "negative", "confidence": 0.6 } }], "meta": { "since": "2025-04-01T00:00:00Z", "until": "…" } } ``` ### GET /v1/world/exposure Exposición por país, con los huecos declarados. Una puntuación de 0 a 100 por país, o null cuando la cobertura es insuficiente. Una pregunta sin respuesta nunca se muestra como segura. ```bash curl https://api.valyzer.com/v1/world/exposure \ -H "X-Api-Key: $VALYZER_API_KEY" ``` ```ts const url = new URL("https://api.valyzer.com/v1/world/exposure"); const res = await fetch(url, { headers: { "X-Api-Key": process.env.VALYZER_API_KEY! }, }); if (!res.ok) throw new Error(`Valyzer ${res.status}`); const { data } = await res.json(); ``` ```python import os import requests res = requests.get( "https://api.valyzer.com/v1/world/exposure", headers={"X-Api-Key": os.environ["VALYZER_API_KEY"]}, ) res.raise_for_status() data = res.json()["data"] ``` Respuesta, abreviada (200 OK): ```json { "data": { "version": "geoexposure-v1", "calculatedAt": "…", "values": { "": 0–100 | null }, "quality": { "": "complete" | "partial" | "stale" } } } ``` ### Endpoints principales - `GET /v1/events`: Eventos publicados, filtrados por tipo, país, entidad y tiempo - `GET /v1/events/:id`: Un evento con afirmaciones, evidencia, entidades e impactos - `GET /v1/changes`: Qué ha cambiado desde una fecha, para polling y sincronización - `GET /v1/entities/:id`: Ficha de entidad, actual e histórica - `GET /v1/world/exposure`: Exposición de países, activos y rutas - `GET /v1/world/tension`: Tensión bilateral, comparable en el tiempo ### Del registro a la primera llamada en dos minutos. 1. **Crea una cuenta**: Solo email. Empieza en Sandbox. 2. **Crea una clave**: En la consola. Se muestra una vez. 3. **Llama a /v1**: Envíala en la cabecera X-Api-Key. Claves X-Api-Key que creas y revocas en tu consola. Al superar la cuota la API responde 429, nunca una factura sorpresa. ## Hecho para que lo lean los agentes. Cada punto de entrada es legible por máquinas: un agente encuentra la especificación, aprende el contrato y llama a la API sin una persona en medio. ### Recursos legibles por máquinas - llms.txt: https://valyzer.com/llms.txt (Índice del sitio para LLM) - llms-full.txt: https://valyzer.com/llms-full.txt (Ofertas, precios y preguntas frecuentes en un documento) - Esta página en Markdown: https://valyzer.com/es/for-developers.md (El mismo texto y los mismos ejemplos, sin HTML) - OpenAPI 3.1: https://api.valyzer.com/v1/openapi.json (La especificación completa, importable en cualquier sitio) - Endpoint MCP: https://api.valyzer.com/v1/mcp (OAuth 2.1 o clave API) - Documentación interactiva: https://api.valyzer.com/v1/docs (Prueba cada endpoint en el navegador) ### El contrato - `QUOTA_EXCEEDED · RATE_LIMITED`: 429 con cabecera Retry-After. Al superar la cuota, nunca una factura sorpresa. - `PLAN_HISTORY_LIMIT`: 403 cuando asOf, knownAt o since es anterior a la ventana de historia de tu plan. - `X-Valyzer-History-Days`: Cabecera de respuesta con la ventana de historia de tu plan. - `X-Valyzer-Page-Limit`: Cabecera de respuesta con el tamaño de página aplicado a tu llamada. - `REST · MCP`: Un solo registro, las mismas reglas de evidencia, la misma cuota. ## Empieza gratis. Pasa a pago con un clic. Sandbox es gratis para siempre. Developer es una tarifa plana de 99 € al mes, cancelable cuando quieras. Sin excedentes. ### Sandbox 0 € gratis para siempre · sin tarjeta. 1000 llamadas / mes · 10 peticiones/min. - Los mismos datos publicados y su evidencia - Últimos 30 días de historia · 20 registros por llamada - asOf / knownAt dentro de esa ventana - Hasta 2 claves API ### Developer 99 € / mes · o 990 € / año (2 meses gratis). 25.000 llamadas / mes · 120 peticiones/min. - Todo lo de Sandbox - 12 meses de historia · 100 registros por llamada - Exportación masiva (JSON / CSV / GeoJSON) - Hasta 10 claves API, uso visible en tu consola - Facturas con IVA y NIF · soporte por email ### Enterprise A medida acuerdo anual. Desde 1.000.000 llamadas / mes · 600 peticiones/min. - Historia completa · 100 registros por llamada - SLA y derechos de redistribución declarados - Tu propio perímetro en un espacio privado - Informes congelados e integraciones a medida Sandbox y Developer: Todos los eventos, afirmaciones y fuentes publicados; Capas del mundo, exposición, tensión y búsqueda; Historial de revisiones dentro de la ventana de tu plan. Solo Enterprise: Perímetros de cliente: proveedores, plantas, dependencias; Alertas de workspace e informes congelados; Análisis humano y fuentes a medida. Una llamada es una petición autenticada a /v1. Las cuotas son por cuenta y se reinician el día 1 de cada mes (UTC). Precios sin IVA. ## Preguntas técnicas. **¿De dónde salen los datos?** Boletines oficiales, listas de sanciones, tribunales, datasets abiertos y prensa. Una fuente solo llega a la API cuando sus derechos y procedencia están aprobados, y cada afirmación enlaza a ella. **¿Qué pasa cuando se corrige un hecho?** No se sobrescribe nada. La versión anterior se cierra y se registra una nueva, así que puedes consultar la verdad actual o reproducir lo que devolvía la API en una fecha pasada con knownAt. **¿Cómo conecto claude.ai o ChatGPT?** Añade un conector personalizado, pega https://api.valyzer.com/v1/mcp e inicia sesión para aprobar. No hay clave que copiar: al aprobar se crea una conexión que usa la cuota y los límites de tu plan, y no cuenta para tu límite de claves API. Puedes desconectarla desde tu consola. **¿Qué pasa si supero mi cuota?** La API responde 429 (QUOTA_EXCEEDED o RATE_LIMITED) con una cabecera Retry-After. No hay cobro por excedentes: pásate a Developer o habla con nosotros de Enterprise. **¿Puedo mostrar datos de Valyzer a mis clientes?** Sí, dentro de tu producto y con la atribución de fuente que incluye cada respuesta. La redistribución masiva o reventa requiere un acuerdo Enterprise. **¿Cómo funcionan el pago y la cancelación?** Developer se paga con tarjeta a través de Stripe, con IVA y factura con el NIF de tu empresa. Cambia la tarjeta, pasa de mensual a anual o cancela desde el portal de facturación de tu consola; mantienes el plan hasta el final del periodo pagado. **¿Cuánta historia y cuántos registros por llamada incluye cada plan?** Sandbox lee los últimos 30 días con hasta 20 registros por llamada; Developer, los últimos 12 meses con hasta 100; Enterprise tiene historia completa. Un límite mayor se recorta al tamaño de página de tu plan (cabecera X-Valyzer-Page-Limit). Un asOf, knownAt o since anterior a tu ventana, o un registro fuera de ella, responde 403 PLAN_HISTORY_LIMIT. X-Valyzer-History-Days indica tu ventana.