*Visión general › Primeros pasos*

# Guía rápida

> Crea una clave de API en la sección API y MCP de los ajustes de Filmo y luego llama a `GET /api/v1/account`. La respuesta te dice la zona horaria, la moneda, los add-ons y los permisos (scopes) con los que construir.

## Requisitos

- 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`](https://docs.filmo.io/es/rest-api/errors/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](https://docs.filmo.io/es/concepts/plans-and-add-ons) explica qué abre cada add-on.

## ¿No eres administrador?

Solo un administrador puede crear una clave, y la clave actúa como esa persona ([Permisos](https://docs.filmo.io/es/concepts/permissions)). Pide una clave a un administrador y dile:

- Los scopes exactos que necesita tu integración. Incluye siempre [`account:read`](https://docs.filmo.io/es/rest-api/guides/scopes#account:read): la primera llamada lo necesita, y sin él recibes 403 [`insufficient_scope`](https://docs.filmo.io/es/rest-api/errors/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](https://docs.filmo.io/es/rest-api/guides/authentication).

## Crear una clave

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. **Añadir una clave** Ponle un nombre que diga para qué sirve y elige sus scopes. Incluye [`account:read`](https://docs.filmo.io/es/rest-api/guides/scopes#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. **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](https://www.filmo.io/es/help/reference/integraciones-y-api/generar-una-clave-de-api) en el centro de ayuda.

## Hacer la primera llamada

Guarda la clave en una variable de entorno y llama a [`GET /api/v1/account`](https://docs.filmo.io/es/rest-api/endpoint-reference/account/get-the-account). Los ejemplos leen `FILMO_API_KEY` y, si está definida, `FILMO_BASE_URL`; la URL base por defecto es `https://app.filmo.io`.

*GET /api/v1/account*

**cURL**

```bash
# 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"
```

**PowerShell**

```text
# 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"
```

**Node**

```javascript
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);
```

**Python**

```python
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`:

*Símbolo del sistema (cmd.exe)*

```text
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):

*200 OK*

```json
{
  "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"
    }
  }
}
```

## Leer la respuesta

| Campo | Qué hacer con ello |
| --- | --- |
| `timezone` | La zona horaria del negocio. Una fecha sin hora como 2026-10-17 en un filtro se lee en ella. Cuando escribas, envía instantes con desplazamiento. |
| `currency` | La moneda de la cuenta. Los importes son cadenas decimales con dos decimales, y un documento puede llevar su propia moneda. |
| `language` | El idioma por defecto de los mensajes de error de esta clave, salvo que `Accept-Language` indique otro. No ramifiques nunca según el texto del mensaje. |
| `addons` | Los add-ons que tiene hoy la cuenta. Un recurso que depende de un add-on que no figura en la lista responde 402. Mientras la prueba está activa todos los add-ons están desbloqueados, así que no decidas a partir de esta lista hasta que la prueba haya terminado. |
| `trial` | Mientras `active` es true, todos los add-ons están desbloqueados; `endsAt` es cuándo termina eso. |
| `apiKey` | La clave que hizo la llamada: su nombre y sus `scopes`. El secreto nunca se devuelve. |
| `rateLimits` | Peticiones por minuto: la cuota global y la cuota separada de las consultas de disponibilidad. |
| `api` | La versión del contrato con la que se sirve a esta cuenta, y dónde está su documentación. |

## Si falla la primera llamada

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](https://docs.filmo.io/es/further-reading/support)).

| Síntoma | Causa y solución | Error |
| --- | --- | --- |
| 401 y el detalle dice que la cabecera Authorization falta o está mal formada | La cabecera debe ser exactamente `Authorization: Bearer <key>`, con la palabra `Bearer` y un espacio. Se rechaza una clave sola, `Token` o `Basic`. | `unauthorized` |
| 401 para una clave que funcionaba | La clave es incorrecta, se revocó o ha caducado. Comprueba cómo llegó a tu shell y emite una nueva si hace falta. | `api_key_invalid`, `api_key_revoked`, `api_key_expired` |
| 404, o una respuesta que no es un cuerpo de problema de Filmo | Toda ruta empieza por `/api/v1`, no por `/v1`. Usa `https://app.filmo.io/api/v1/account`. | Ninguno |
| 401 después de que el propietario de la clave cambie de rol o se vaya | La persona que creó la clave ya no es administradora, o está desactivada. La clave está bien; vuelve a emitirla desde una cuenta que siga siendo administradora. | `api_key_owner_not_admin`, `api_key_owner_inactive` |
| 403 en la primera llamada | La clave no incluye `account:read`. `requiredScope` en el cuerpo lo nombra. Crea una clave que lo incluya. | `insufficient_scope` |
| 400 en una escritura posterior que lleva una fecha | Una fecha y hora en una escritura necesita un desplazamiento: 2026-10-17T09:00:00+02:00, no 2026-10-17T09:00:00. Solo un campo que es una fecha simple, como `invoiceDate` en `PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`, admite una fecha sin hora. `errors[].path` apunta al campo. | `validation_error` |
| 402 en lugar de 403 | Un 402 trata de un add-on: la cuenta no tiene el add-on del módulo al que pertenece ese recurso, y ningún rol lo evita. Un 403 trata de la clave o de su propietario. Consulta Permisos. | `addon_required`, `forbidden` |
| El navegador bloquea la llamada (CORS) | No llames a la API desde una página web. En producción la API permite llamadas entre orígenes desde el navegador solo desde https://docs.filmo.io, así que un navegador bloquea la llamada desde cualquier otro origen; y las claves son para servidores, porque una clave en un navegador queda expuesta. | Ninguno: lo detiene el navegador |
| El `detail` está en español | Sin `Accept-Language`, un 401 por una clave ausente o desconocida llega en español, porque no hay propietario al que preguntar; cualquier otro error usa el idioma preferido del propietario de la clave. Envía siempre `Accept-Language: en-US` (`es-ES` y `en-US` están garantizados) y no bases lógica en `detail`. | Cualquiera |
| La respuesta no es `application/problem+json`, por ejemplo un 413 o un 504 | Respondió la plataforma que está delante de la API, no la API. Comprueba el estado y `Content-Type` antes de interpretar la respuesta; no des por hecho un cuerpo JSON. Reintenta un 504 tras una pausa. | No es un código de Filmo. Los fallos de servidor de la API son `internal_error` y `service_unavailable` |
| PowerShell 5.1: `curl` falla con `-H` | `curl` es un alias de `Invoke-WebRequest`. Usa `Invoke-RestMethod`, o `curl.exe`. | Ninguno: la shell falla antes |
| cmd: la clave no se envía | `$FILMO_API_KEY` no se expande en el Símbolo del sistema, así que la cabecera lleva ese texto literal y la clave se rechaza. Escribe `%FILMO_API_KEY%`. | `api_key_invalid` |
| En un comando cURL, `Idempotency-Key` sale vacía | `uuidgen` no existe en Windows ni en las imágenes mínimas de Debian y Alpine, así que `$(uuidgen)` en una opción `-H` se expande a nada. Genera el id en tu lenguaje: `crypto.randomUUID()` en Node, `uuid.uuid4()` en Python, `[guid]::NewGuid()` en PowerShell. | Ninguno: el reintento no está protegido |

## Siguientes pasos

- [Capacidades y límites](https://docs.filmo.io/es/further-reading/capabilities-and-limits): qué cubre la v1, sus límites estrictos y lo que no hace.
- [Sincronizar datos](https://docs.filmo.io/es/rest-api/guides/syncing-data): mantén tu sistema sincronizado con Filmo consultando los cambios periódicamente.
- [Pasar a producción](https://docs.filmo.io/es/rest-api/guides/going-live): la lista de comprobación antes de pasar a producción.
- [Guía rápida de MCP](https://docs.filmo.io/es/mcp/quickstart): da a un asistente de IA el mismo acceso.

---

URL canónica: https://docs.filmo.io/es/quickstart  
Última actualización: 2026-10-09