Saltar al contenido
SPREVA

SPREVA abre pronto.

Únete a la lista de espera y te escribiremos una sola vez, cuando tu cuenta esté lista.

Sin newsletter. Solo un email cuando SPREVA abra.

Referencia

API REST

Crea, programa y publica publicaciones, sube archivos multimedia y consulta resultados desde tu propio código. La API sigue las mismas reglas y la misma validación que el propio SPREVA.

Tu primera petición

  1. 1

    Crea una clave de API en SPREVA en Desarrollo y luego Claves de API. Para este ejemplo basta una clave Solo lectura; para publicar hace falta una clave con acceso Publicación.

  2. 2

    Lista tus cuentas sociales:

    Terminal
    curl https://dev-app.spreva.ai/api/v1/social-accounts \
  -H "Authorization: Bearer spreva_sk_..."
  3. 3

    Lee la respuesta. Los resultados vienen dentro de data, y el id de una cuenta es lo que pasas como connectionId al crear una publicación para ella. El ejemplo está resumido: el objeto real tiene más campos.

    JSON
    {
  "data": [
    {
      "id": "e81b3f52-0000-4000-8000-000000000005",
      "provider": "instagram",
      "displayName": "Acme Studio",
      "username": "acme",
      "status": "ACTIVE",
      "needsReconnect": false
    }
  ]
}

Lo básico

Todos los endpoints están en esta dirección. Envía JSON, con la clave como Authorization: Bearer seguido de la clave.

URL
https://dev-app.spreva.ai/api/v1
  • Una clave pertenece a un espacio de trabajo y solo ve ese espacio de trabajo.
  • Límite: 120 peticiones por minuto para cada persona en un espacio de trabajo, compartidas entre todas las claves que creó. Por encima de eso, la respuesta es un 429 cuyo mensaje dice cuántos segundos esperar.
  • Los errores llegan en el idioma de la cabecera Accept-Language de la petición; su code nunca cambia.
  • Desde un navegador con sesión iniciada en SPREVA, envía x-workspace-id con el id del espacio de trabajo en lugar de una clave.

Claves y permisos

Una clave actúa en nombre de la persona que la creó y nunca puede hacer más de lo que permite el rol de esa persona. Las crean propietarios y administradores, en un plan que incluya acceso a la API, y la clave completa se muestra una sola vez. Cada clave tiene los permisos que se le dieron:

posts:read
Ver publicaciones, su estado, sus resultados y las colas
media:read
Ver la biblioteca multimedia
accounts:read
Ver las cuentas sociales conectadas
analytics:read
Ver las analíticas
posts:write
Crear, editar, programar, publicar y eliminar publicaciones, y gestionar colas
media:write
Subir, renombrar y eliminar multimedia
webhooks:write
Ver y añadir endpoints de webhook
ai:write
Usar la IA. Los subtítulos y los hashtags también necesitan posts:write; el texto alternativo y las imágenes también necesitan media:write

Solo lectura da los cuatro permisos de lectura. Publicación añade posts:write, media:write y ai:write, suficiente para una automatización o un agente de IA. Un 403 significa que a la clave le falta el permiso, o que el rol de quien la creó ya no lo permite.

Errores

Todos los errores tienen la misma forma. Decide según code y muestra message.

JSON
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key needs the posts:write scope for posts:create"
  }
}
400
INVALID_REQUEST · INVALID_JSON · WORKSPACE_REQUIRED

El cuerpo o la consulta no encajan con el endpoint. details lista cada campo que está mal. Una llamada desde el navegador sin x-workspace-id recibe WORKSPACE_REQUIRED.

401
UNAUTHENTICATED

Falta la clave, está mal escrita, revocada o caducada. Envía «Authorization: Bearer <key>».

402
ENTITLEMENT_EXCEEDED · AI_LIMIT_REACHED

El espacio de trabajo no tiene un plan activo, se ha quedado sin créditos de IA o su plan no incluye esto. Un propietario puede elegir un plan o comprar créditos en Ajustes, Facturación.

403
FORBIDDEN

La clave no tiene permiso para esta petición, o tu rol no lo permite. Crea una clave con más acceso.

404
NOT_FOUND

No existe ese objeto en este espacio de trabajo. Una clave solo ve el espacio de trabajo en el que se creó.

409
CONCURRENT_MODIFICATION · INVALID_STATE_TRANSITION · CONFLICT · AI_NOT_CONFIGURED

La publicación cambió desde que la leíste, está en un estado que no permite esto (publicar algo ya publicado), un archivo que estás eliminando todavía se usa en una publicación, o la IA no está configurada en esta instalación. Vuelve a obtenerla y reinténtalo.

422
VALIDATION_FAILED · PROVIDER_VALIDATION_FAILED · AI_REFUSED

El contenido no encaja con la cuenta a la que va, o una petición a la IA fue rechazada. GET /providers lista las reglas de cada red.

429
RATE_LIMITED · AI_BUSY

Más de 120 peticiones en un minuto hechas por ti en este espacio de trabajo, o demasiadas peticiones a la IA a la vez. Con RATE_LIMITED, el mensaje dice cuántos segundos hay que esperar; con AI_BUSY, espera un momento.

500
INTERNAL

Algo falló al atender la petición, en SPREVA o en una red social. Reinténtalo en un momento.

503
AI_UNAVAILABLE

El proveedor de IA no está disponible ahora mismo. Reinténtalo en un momento.

Endpoints

Las rutas son relativas a la URL base. El documento OpenAPI describe cada cuerpo y parámetro, y puedes generar un cliente a partir de él:

URL
https://dev-app.spreva.ai/api/openapi.json

Cuentas sociales y redes

  • get /social-accountsLas cuentas sociales conectadas.
  • get /providersLas reglas de cada red: formatos, ubicaciones y límites.

Publicaciones

  • get /postsPublicaciones, filtradas por estado, fechas, cuenta, red o campaña.
  • post /postsCrear un borrador para una o varias cuentas.
  • get /posts/{id}Una publicación con sus cuentas, su validación y sus archivos.
  • patch /posts/{id}Cambiar una publicación. Envía la version que leíste; si cambió desde entonces, la respuesta es 409.
  • delete /posts/{id}Eliminar una publicación.
  • post /posts/{id}/publishPublicar ahora. La respuesta es 202: sigue la publicación, o un webhook, para saber el resultado.
  • post /posts/{id}/scheduleProgramarla a una hora, con una zona horaria.
  • post /posts/{id}/queueAñadirla al siguiente hueco libre de una cola.
  • post /posts/{id}/retryReintentar una cuenta que falló.

Multimedia

  • get /mediaLa biblioteca, con búsqueda y filtros.
  • post /media/uploadsEmpezar una subida: la respuesta dice adónde enviar el archivo.
  • post /media/uploads/{id}/completeTerminar una subida. Después el archivo se comprueba y se procesa.
  • get /media/{id}Un archivo, con su estado y lo que se sabe de él.
  • delete /media/{id}Eliminar un archivo. Un archivo que todavía usa una publicación responde 409.
  • put /media/{id}/alt-textGuardar o borrar el texto alternativo de un archivo.
  • post /media/{id}/alt-text/suggestionSugerir texto alternativo con IA, sin guardarlo.

Estadísticas

  • get /analyticsResultados de un periodo.
  • get /analytics/exportLos mismos resultados en un archivo CSV.

Colas

  • get /queuesLas colas de publicación.
  • post /queuesCrear una cola con sus horarios semanales.
  • patch /queues/{id}Cambiar una cola.
  • delete /queues/{id}Eliminar una cola.

Webhooks

  • get /webhooksLos endpoints de webhook.
  • post /webhooksAñadir un endpoint. La respuesta trae su secreto, solo esta vez.

IA

  • get /aiSi la IA está disponible, los créditos que quedan y lo que cuesta cada acción.
  • post /ai/captionsSugerir nuevas versiones de un texto, traducciones o hashtags, sin guardarlos.
  • post /ai/imagesGenerar una imagen. Consulta GET /media/{id} hasta que esté lista.