Integraciones

Publica en spirkz desde cualquier planificador

La API de integraciones permite que planificadores de terceros (Zapier, Metricool, Buffer y similares) envíen vídeos a spirkz en nombre de un creador. Un vídeo enviado aquí pasa por las mismas reglas y la misma cola de revisión que uno subido desde la app.

URL base: https://server.spirkz.com/api/v1/integrations

Cómo funciona

1
El creador crea una clave de API en la app de spirkz y la pega en el planificador.
2
El planificador llama a POST /videos con un videoUrl público y los detalles. spirkz responde 202 al instante.
3
spirkz descarga el archivo en segundo plano, lo almacena y crea un envío pendiente para el creador.
4
El equipo de spirkz lo revisa. Si se aprueba y scheduledAt aún está por delante, se publica en ese momento; si no, se publica de inmediato.
5
El planificador consulta GET /videos/:id para ver el progreso.

Autenticación

Envía la clave del creador en cada solicitud. Una clave ausente, desconocida o revocada recibe 401. Las claves actúan como el creador que las emitió.

Authorization: Bearer spk_...

Límites de uso, por clave

600

solicitudes por hora, en total

llamadas a POST /videos por hora

Endpoints

GET/me

Prueba de conexión. Llámalo justo después de que el creador pegue su clave.

{ "user": { "id", "name", "username" }, "keyName" }

GET/categoriesGET/languages

Datos para tus selectores: categoryIds válidos (categorías activas; ?locale= para los nombres) y valores de languageSlug.

POST/videos

Envía un vídeo. El cuerpo es JSON:

Campo		Reglas
videoUrl	Obligatorio	`https`, accesible públicamente, ≤ 2000 caracteres. mp4 / mov / webm / avi, ≤ 500 MB. Se rechazan las direcciones privadas o internas.
source	Obligatorio	Quién envía, p. ej. `"zapier"`, `"metricool"`. ≤ 50 caracteres, se guarda en minúsculas.
name	Obligatorio	≤ 150 caracteres.
categoryIds	Obligatorio	De 1 a 5 ids de `GET /categories`.
description	Opcional	≤ 500 caracteres.
languageSlug	Opcional	De `GET /languages`. Por defecto `en`.
tag	Opcional	Array de cadenas, hasta 10 etiquetas, cada una ≤ 40 caracteres.
duration	Opcional	Segundos, entero no negativo.
scheduledAt	Opcional	ISO 8601. Con al menos 10 minutos y como máximo 60 días de antelación. Omitido o `null` = se publica al aprobarse.

202 — data.video con status: "received".
400 / 404 — un campo no es válido. No se guarda nada.
409 — el creador ya tiene 10 vídeos pendientes de envío o de revisión (incluidos los que aún se están descargando).

GET/videosGET/videos/:id

Los vídeos de integración del creador, del más reciente al más antiguo (?limit, ?offset), o uno por id.

{
  "id": "...",
  "source": "zapier",
  "video_url": "https://...",
  "status": "submitted",
  "error": null,
  "created_at": "...",
  "updated_at": "...",
  "userVideo": {
    "id": "...",
    "name": "...",
    "status": "pending",
    "scheduled_at": "2026-10-10T09:00:00.000Z",
    "decline_reason": null,
    "publishedVideoId": null
  }
}

Seguimiento de un vídeo

Descarga — `status`

receivedprocessingsubmittedofailed

En failed, el motivo está en error.

Revisión — `userVideo.status`

pendingscheduledapprovedodeclined

publishedVideoId se establece cuando el vídeo ya está publicado. Un vídeo rechazado incluye un decline_reason.

Ejemplo

curl -X POST https://server.spirkz.com/api/v1/integrations/videos \
  -H "Authorization: Bearer spk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/clip.mp4",
    "source": "zapier",
    "name": "Morning routine",
    "categoryIds": ["<category id>"],
    "description": "Day 1",
    "scheduledAt": "2026-10-10T09:00:00Z"
  }'

Compatibilidad nativa

Cualquier planificador puede integrarse con los endpoints de arriba. Estas herramientas ya son compatibles con spirkz de serie:

NativogenzlEs compatible con spirkz de forma nativa: conecta tu clave de API y programa.genzl.com →

¿Estás creando una integración?

Cuéntanos qué estás haciendo y te ayudaremos a lanzarla.

Escríbenos