Saltar al contenido
Fipeo

Fipeo para desarrolladores

Autenticación

Acceso anticipado. La API, los webhooks y el widget están apagados para la mayoría de las cuentas mientras los probamos con las primeras escuelas y agencias. Esta documentación es pública para que puedas planear tu integración: escríbenos a [email protected] y te lo encendemos.

Hay dos formas de autenticarse. Las dos mandan un token en la cabecera Authorization y dan exactamente el mismo acceso: usa una clave de API para tus propios programas, Zapier o Make, y OAuth 2.0 cuando un producto que usas solo sabe OAuth.

Claves de API

  • Las crea en Integraciones › Claves de API el titular o un administrador de la agencia, o la cuenta principal de la escuela.
  • Son fpk_ seguido de unos 43 caracteres. La clave se enseña una vez; Fipeo solo guarda su huella SHA-256 y sus 12 primeros caracteres, para que la reconozcas.
  • Mándala como Authorization: Bearer fpk_…, nunca en la URL. La API no usa cookies.
  • Fecha de caducidad opcional, hasta 2 años. Puedes revocar una clave cuando quieras y deja de funcionar al momento.
  • Una clave también deja de funcionar si se suspende la cuenta, o si la persona que la creó deja la agencia o deja de ser administradora: crea las claves con una cuenta que vaya a seguir.
  • Cada clave tiene en el panel su registro de uso (peticiones y errores por día y ruta, 30 días).

Permisos

Cada clave o aplicación OAuth tiene una lista de permisos. Cada ruta necesita el suyo; sin él la respuesta es 403 insufficient_scope. Una escuela solo puede tener bookings:read.

PermisoParaRutas
(ninguno)agencias y escuelasGET /me
catalog:readagenciasGET /schools, GET /courses
quotes:readagenciasGET /quotes, GET /quotes/{id}
bookings:readagencias y escuelasGET /bookings (agencia: tus reservas; escuela: tu bandeja), GET /bookings/{reference} (agencias)
students:readagenciasGET /students, GET /students/{id}
students:writeagenciasPOST /students

Acuerdo de encargo del tratamiento: cuando es obligatorio, students y quotes contestan 403 dpa_required hasta que el titular de la cuenta lo acepta en el panel, igual que en el propio panel.

OAuth 2.0 client credentials

Para programas que se autentican con OAuth (CRM, iPaaS, programas de reservas). En Integraciones › Aplicaciones OAuth crea una aplicación con un nombre y sus permisos. Recibes un identificador de cliente (fpc_…) y un secreto de cliente (fps_…, se enseña una vez). Puedes tener hasta 5 aplicaciones activas.

Pide un token

Autentica el cliente con HTTP Basic, o con client_id y client_secret en el cuerpo (form-urlencoded o JSON), nunca las dos cosas. scope es opcional: una parte de los permisos de la aplicación separados por espacios; sin él recibes todos.

HTTP Basic
curl https://fipeo.net/api/public/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="bookings:read students:read"
Credenciales en el cuerpo
curl https://fipeo.net/api/public/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"
200 OK
{ "access_token": "fpt_…", "token_type": "Bearer", "expires_in": 3600, "scope": "bookings:read students:read" }

Úsalo

bash
curl https://fipeo.net/api/public/v1/bookings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
  • El token dura una hora (expires_in: 3600). No hay refresh token: pide otro cuando caduque. Reutilízalo mientras tanto: una aplicación puede tener como mucho 20 tokens activos.
  • Tiene los mismos límites que una clave (contados por aplicación), los mismos permisos y las mismas respuestas.
  • Los errores siguen el RFC 6749 §5.2: 400 con invalid_request, unsupported_grant_type o invalid_scope; 401 invalid_client (con WWW-Authenticate: Basic si usaste Basic). Fipeo nunca dice por qué un cliente no vale.

Revocar y cambiar el secreto

Revocar un token (RFC 7009)
curl https://fipeo.net/api/public/v1/oauth/revoke \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d token="$ACCESS_TOKEN"

En el panel también puedes dar a la aplicación un secreto nuevo y mantener el anterior entre 0 y 24 horas mientras lo cambias en tu programa (0 lo corta ya y revoca los tokens), revocar todos sus tokens o revocar la aplicación entera.

Quién ve qué

  • Una clave solo ve su organización. Todo lo demás, aunque exista, contesta 404 not_found.
  • Las rutas de agencias con una clave de escuela contestan 403 insufficient_scope (una clave de escuela solo puede tener bookings:read); GET /bookings/{reference} contesta 404.
  • Lo que sale es una lista cerrada de campos: nunca salen comisiones, precios netos, el precio de la escuela de un presupuesto, pagos ni notas internas, y un segundo filtro quita cualquier campo que pudiera llevarlos.