Documentación

API REST de Serpflow

Consume Serpflow desde tu CRM, n8n, scripts internos o cualquier integración. Endpoints REST sobre HTTPS con autenticación Bearer y respuestas JSON. Disponible en el plan Agency Pro.

Autenticación

Todas las llamadas requieren el header Authorization: Bearer sk_live_…. Las keys se generan desde Configuración → API keys y se muestran una sola vez al crearlas — guárdalas en un gestor de secretos.

curl -H "Authorization: Bearer sk_live_xxx..." \
  https://serpflow.es/api/v1/clients

Las keys revocadas devuelven 401 key_revoked inmediatamente. Si tu agencia cambia a un plan sin acceso API, los endpoints devuelven 403 plan_required sin afectar a las keys (cuando vuelvas a Agency Pro siguen funcionando).

Base URL y versionado

https://serpflow.es/api/v1

La v1 se mantendrá compatible. Cualquier cambio incompatible se publicará bajo /api/v2 con un periodo de aviso de 90 días.

Endpoints

GET/api/v1/clients

Lista los clientes de tu agencia.

Response 2xx

{
  "clients": [
    {
      "id": "uuid",
      "nombre": "Acme Studio",
      "url": "https://acme.studio",
      "created_at": "2026-05-16T10:23:00Z",
      "auto_audit_frequency": "monthly",
      "last_auto_audit_at": "2026-05-01T06:30:00Z"
    }
  ]
}

POST/api/v1/clients

Crea un cliente nuevo. Opcionalmente con competidores.

Request body

{
  "nombre": "Acme Studio",
  "url": "https://acme.studio",
  "competitors": [
    "https://competitor1.com",
    "https://competitor2.com"
  ]
}

Response 2xx

{
  "client": {
    "id": "uuid",
    "nombre": "Acme Studio",
    "url": "https://acme.studio",
    "created_at": "2026-05-16T10:23:00Z"
  }
}

GET/api/v1/analyses?client_id=…&status=done&limit=50

Lista análisis. Parámetros opcionales: client_id, status, limit (máx 200).

Response 2xx

{
  "analyses": [
    {
      "id": "uuid",
      "client_id": "uuid",
      "type": "audit",
      "status": "done",
      "created_at": "2026-05-15T14:02:11Z",
      "error_message": null
    }
  ]
}

POST/api/v1/analyses

Crea y ejecuta un análisis. Por defecto espera al resultado ("wait": true). Pasa "wait": false para crear en pendiente y hacer polling.

Request body

{
  "client_id": "uuid-del-cliente",
  "type": "audit",
  "wait": true
}

Response 2xx

{
  "analysis": {
    "id": "uuid",
    "status": "done",
    "result_json": {
      "summary": "…",
      "recommendations": [ … ],
      "metrics": { … }
    },
    "created_at": "2026-05-16T10:25:00Z"
  }
}

GET/api/v1/analyses/:id

Devuelve un análisis con el result_json completo.

Response 2xx

{
  "analysis": {
    "id": "uuid",
    "status": "done",
    "result_json": { … },
    "share_token": "abc...",
    "share_expires_at": null
  }
}

GET/api/v1/clients/:id/rankings

Devuelve las keywords seguidas del cliente con su posición actual y hasta 30 snapshots históricos.

Response 2xx

{
  "keywords": [
    {
      "id": "uuid",
      "keyword": "agencia seo Barcelona",
      "current_position": 14,
      "current_url": "https://acme.studio/...",
      "last_checked_at": "2026-05-16T06:00:00Z",
      "history": [
        { "position": 18, "checked_at": "2026-05-14T..." },
        { "position": 16, "checked_at": "2026-05-15T..." },
        { "position": 14, "checked_at": "2026-05-16T..." }
      ]
    }
  ]
}

Códigos de error

401 missing_credentials — falta header Authorization.
401 invalid_key_format — formato de key incorrecto.
401 invalid_key — key no existe.
401 key_revoked — la key fue revocada.
402 quota_exceeded — superaste el límite de análisis del mes.
403 plan_required — tu plan no incluye acceso API.
404 not_found / client_not_found — el recurso no existe en tu agencia.
400 invalid_body — payload inválido (revisa details en la respuesta).
500 db_error — error interno; reintenta o contacta a soporte.

Ejemplo completo

Crear un cliente y lanzar una auditoría:

# 1. Crear cliente
curl -X POST https://serpflow.es/api/v1/clients \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Acme","url":"https://acme.studio"}'

# 2. Lanzar auditoría (espera hasta done)
curl -X POST https://serpflow.es/api/v1/analyses \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"<uuid-del-paso-1>","type":"audit"}'

¿Algo no encaja con tu integración?

Escríbenos a serpflowcontacto@gmail.com con tu caso y respondemos en 24h.