Autenticación
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.
| Permiso | Para | Rutas |
|---|---|---|
| (ninguno) | agencias y escuelas | GET /me |
catalog:read | agencias | GET /schools, GET /courses |
quotes:read | agencias | GET /quotes, GET /quotes/{id} |
bookings:read | agencias y escuelas | GET /bookings (agencia: tus reservas; escuela: tu bandeja), GET /bookings/{reference} (agencias) |
students:read | agencias | GET /students, GET /students/{id} |
students:write | agencias | POST /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.
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"curl https://fipeo.net/api/public/v1/oauth/token \
-d grant_type=client_credentials \
-d client_id="$CLIENT_ID" \
-d client_secret="$CLIENT_SECRET"{ "access_token": "fpt_…", "token_type": "Bearer", "expires_in": 3600, "scope": "bookings:read students:read" }Úsalo
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:
400coninvalid_request,unsupported_grant_typeoinvalid_scope;401 invalid_client(conWWW-Authenticate: Basicsi usaste Basic). Fipeo nunca dice por qué un cliente no vale.
Revocar y cambiar el secreto
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 tenerbookings:read);GET /bookings/{reference}contesta404. - 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.