API v1 — Documentación

4 endpoints REST de solo lectura sobre el mismo panel que alimenta las exportaciones y el feed. 10.000 filas/mes incluidas, 5€ por cada 1.000 adicionales.

Autenticación

Envía tu clave en la cabecera x-api-key, o como Authorization: Bearer <clave>. Ambas formas son equivalentes.

curl -H "x-api-key: cvx_tu_clave_aqui" \
  "https://n8n.citavox.es/webhook/api/v1/deltas?vertical=dental&weeks=4"

Cómo consigo una clave: se genera y se envía automáticamente por email al suscribirte al plan API (ver precios). Se muestra una sola vez en ese email — guárdala. Si la pierdes, escribe a soporte para rotarla (invalida la anterior, genera una nueva).

URL base: actualmente https://n8n.citavox.es/webhook/api/v1/. Migraremos a https://api.citavox.es/api/v1/ sin cambiar rutas, parámetros ni formato de respuesta — solo el dominio. Si integras hoy, deja el host en una variable de configuración.

Límites

Límite	Valor	Qué pasa al superarlo
Peticiones por minuto	60 / clave	`429 rate_limit_exceeded`
Filas incluidas / mes	10.000	No se corta — se factura 5€ por cada 1.000 filas adicionales (Stripe, a mes vencido)

Endpoints

GET/visibility/vertical

Serie semanal de share-of-voice para todas las marcas de una vertical.

Parámetro	Tipo	Obligatorio	Descripción
`vertical`	string	Sí	Slug de la vertical (ej. `dental`)
`city`	string	No	Filtra por ciudad
`weeks`	int	No (def. 12)	Nº de semanas de histórico

{
  "data": [
    { "week": "2026-07-06", "city": "Madrid", "brand": "Clínica Ejemplo",
      "mention_rate": 0.42, "avg_position": 1.8, "sentiment_score": 0.31, "sample_n": 120 }
  ],
  "rows_returned": 1,
  "meta": { "endpoint": "visibility/vertical", "generated_at": "2026-07-14T08:00:00.000Z" }
}

GET/visibility/brand

Histórico de una marca concreta (búsqueda parcial, no distingue mayúsculas).

Parámetro	Tipo	Obligatorio	Descripción
`brand`	string	No	Coincidencia parcial del nombre; vacío = todas
`vertical`	string	No	Filtra por slug de vertical

{
  "data": [
    { "week": "2026-07-06", "city": "Madrid", "vertical": "dental", "brand": "Clínica Ejemplo",
      "mention_rate": 0.42, "avg_position": 1.8, "sentiment_score": 0.31, "sample_n": 120 }
  ],
  "rows_returned": 1,
  "meta": { "endpoint": "visibility/brand", "generated_at": "2026-07-14T08:00:00.000Z" }
}

GET/citations/domain

Con qué frecuencia se cita un dominio concreto como fuente en las respuestas de IA.

Parámetro	Tipo	Obligatorio	Descripción
`domain`	string	Sí	Dominio exacto (ej. `clinicaejemplo.es`)
`vertical`	string	No	Filtra por slug de vertical

{
  "data": [
    { "week": "2026-07-06", "city": "Madrid", "vertical": "dental",
      "cited_domain": "clinicaejemplo.es", "citation_rate": 0.18, "sample_n": 120 }
  ],
  "rows_returned": 1,
  "meta": { "endpoint": "citations/domain", "generated_at": "2026-07-14T08:00:00.000Z" }
}

GET/deltas

Movimientos semana a semana: subidas, bajadas, nuevas entradas y nuevas fuentes citadas.

Parámetro	Tipo	Obligatorio	Descripción
`vertical`	string	Sí	Slug de la vertical
`city`	string	No	Filtra por ciudad
`weeks`	int	No (def. 4)	Nº de semanas de histórico

{
  "data": [
    { "week": "2026-07-06", "city": "Madrid", "delta_type": "new_entrant",
      "brand": "Clínica Nueva", "magnitude": 0.15, "details": {} }
  ],
  "rows_returned": 1,
  "meta": { "endpoint": "deltas", "generated_at": "2026-07-14T08:00:00.000Z" }
}

Errores

Código	Cuerpo	Causa
401	`{"error":"invalid_api_key"}`	Clave ausente, incorrecta, inactiva o sin permiso de lectura
429	`{"error":"rate_limit_exceeded"}`	Más de 60 peticiones en los últimos 60 segundos

Todos los endpoints devuelven exclusivamente métricas derivadas (share-of-voice, posición, sentimiento, dominios citados) — nunca el texto literal de las respuestas de IA. Ver metodología.