Guía rápida

• Una cuenta de Filmo cuyo entorno tiene la API y MCP activados por Filmo; un administrador de la cuenta no puede activarlos. La API y MCP están incluidas en cualquier plan de pago y no son un add-on, y una prueba gratuita (14 días, sin tarjeta) también puede crear claves.
• Un administrador de la cuenta que cree la clave. Si ese no eres tú, lee antes la sección siguiente.
• Los add-ons de los recursos que piensas usar. Una prueba gratuita los desbloquea todos, y cuando termina los endpoints que dependen de un add-on responden 402 addon_required.
• Para los ejemplos: cURL, Windows PowerShell 5.1 o posterior, Node 22 o posterior, o Python 3 con requests.

La URL base es https://app.filmo.io/api/v1. Planes y add-ons explica qué abre cada add-on.

Solo un administrador puede crear una clave, y la clave actúa como esa persona (Permisos). Pide una clave a un administrador y dile:

• Los scopes exactos que necesita tu integración. Incluye siempre account:read: la primera llamada lo necesita, y sin él recibes 403 insufficient_scope.
• Para ponerle a la clave el nombre de la integración y poder encontrarla y revocarla más adelante.
• Para enviarte la clave mediante un gestor de secretos compartido, nunca por correo ni por chat. Se muestra una sola vez y da acceso programático a los datos de la empresa.

De quién es una clave y qué ocurre cuando esa persona se va se explica en Autenticación.

1. 1

   Abrir los ajustes de API y MCP

   En la app de Filmo, como administrador, abre la sección de los ajustes para la API y MCP. En la interfaz en español se lee Ajustes → API y MCP.

2. 2

   Añadir una clave

   Ponle un nombre que diga para qué sirve y elige sus scopes. Incluye account:read y añade solo lo que necesite la integración. Fija una fecha de caducidad si el formulario la ofrece y rotas las claves de forma periódica; una clave sin fecha no caduca nunca.

3. 3

   Copia la clave ahora

   La clave empieza por fk_live_ y se muestra una sola vez; Filmo solo guarda un hash de ella. Guárdala en un gestor de secretos o en una variable de entorno, no en tu código ni en tu repositorio.

Para ver los mismos pasos sin el vocabulario de la API, consulta Generar una clave de API en el centro de ayuda.

Guarda la clave en una variable de entorno y llama a GET /api/v1/account. Los ejemplos leen FILMO_API_KEY y, si está definida, FILMO_BASE_URL; la URL base por defecto es https://app.filmo.io.

# Paste the key when asked; it stays out of your shell history. Works in bash and zsh.
printf 'Filmo API key: '; stty -echo; read -r FILMO_API_KEY; stty echo; echo; export FILMO_API_KEY

FILMO_BASE_URL="${FILMO_BASE_URL:-https://app.filmo.io}"

curl -sS "$FILMO_BASE_URL/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H "Accept-Language: en-US"

# Windows PowerShell 5.1 and PowerShell 7. Paste the key when asked.
$secure = Read-Host "Filmo API key" -AsSecureString
$env:FILMO_API_KEY = [System.Net.NetworkCredential]::new("", $secure).Password
$base = if ($env:FILMO_BASE_URL) { $env:FILMO_BASE_URL } else { "https://app.filmo.io" }

try {
  $response = Invoke-RestMethod -Uri "$base/api/v1/account" `
    -Headers @{ Authorization = "Bearer $env:FILMO_API_KEY"; "Accept-Language" = "en-US" }
  $response.data | ConvertTo-Json -Depth 5
} catch {
  # The body of the problem is in ErrorDetails; the status is in the exception.
  Write-Error $_.ErrorDetails.Message
  exit 1
}

# Alternative with curl.exe (the .exe matters: plain curl is an alias in Windows PowerShell 5.1):
# curl.exe -sS "$base/api/v1/account" -H "Authorization: Bearer $env:FILMO_API_KEY"

const base = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";

const res = await fetch(`${base}/api/v1/account`, {
  headers: {
    Authorization: `Bearer ${process.env.FILMO_API_KEY}`,
    "Accept-Language": "en-US",
  },
});

// Check the status before parsing: a platform error may not be JSON.
if (!res.ok) {
  console.error(res.status, res.headers.get("content-type"), await res.text());
  process.exit(1);
}

const { data } = await res.json();
console.log(data.timezone, data.currency, data.addons, data.apiKey.scopes);

import os
import sys

import requests

base = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")

res = requests.get(
    f"{base}/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}", "Accept-Language": "en-US"},
    timeout=30,
)

# Check the status before parsing: a platform error may not be JSON.
if not res.ok:
    print(res.status_code, res.headers.get("content-type"), res.text, file=sys.stderr)
    sys.exit(1)

account = res.json()["data"]
print(account["timezone"], account["currency"], account["addons"], account["apiKey"]["scopes"])

La pestaña cURL es para shells de macOS y Linux. En Windows PowerShell 5.1, curl es un alias de Invoke-WebRequest y la opción -H falla: usa Invoke-RestMethod como arriba, o llama a curl.exe. En Command Prompt, las variables se escriben %FILMO_API_KEY%, no $FILMO_API_KEY:

rem Command Prompt (cmd.exe): variables are %NAME%, not $NAME.
rem cmd.exe shows the key while you type it: use PowerShell if anyone can see your screen.
set /p FILMO_API_KEY=Filmo API key: 
curl.exe -sS "https://app.filmo.io/api/v1/account" -H "Authorization: Bearer %FILMO_API_KEY%"

Una llamada correcta devuelve 200 con la cuenta dentro del sobre data habitual (los valores de abajo son ficticios):

{
  "data": {
    "name": "Acme Rentals",
    "timezone": "Europe/Madrid",
    "currency": "EUR",
    "country": "ES",
    "language": "en-US",
    "addons": ["crm"],
    "trial": { "active": false, "endsAt": null },
    "apiKey": {
      "id": "example-key-id",
      "name": "Inventory sync",
      "scopes": ["account:read", "items:read", "orders:read"]
    },
    "rateLimits": {
      "global": { "perMinute": 120 },
      "availability": { "perMinute": 30 }
    },
    "api": {
      "version": "1.0.0",
      "docsUrl": "https://docs.filmo.io"
    }
  }
}

Encuentra el síntoma y luego la causa. Los errores son problemas RFC 9457: ramifica según code, nunca según detail. Cita requestId al soporte (Soporte).

• Capacidades y límites: qué cubre la v1, sus límites estrictos y lo que no hace.
• Sincronizar datos: mantén tu sistema sincronizado con Filmo consultando los cambios periódicamente.
• Pasar a producción: la lista de comprobación antes de pasar a producción.
• Guía rápida de MCP: da a un asistente de IA el mismo acceso.