API

Playoff Federacions ofrece una API REST para conectar la plataforma con aplicaciones o procesos externos. Esta guía resume el acceso, la autenticación y los casos de uso habituales. La referencia técnica completa —endpoints, parámetros, modelos y respuestas— está disponible en la documentación pública: https://apifederacions.playoffinformatica.com/.

Antes de empezar

La integración debe utilizar la URL de la instancia de Playoff de cada federación. No se deben usar datos reales contra una instancia de demostración.
Recomendamos crear una cuenta técnica específica para la integración y asignarle únicamente los permisos imprescindibles.
Las credenciales y el token no deben incluirse en código cliente, repositorios ni documentación compartida.
Los endpoints y operaciones disponibles dependen del perfil con el que se autentique la petición.

Autenticación

Primero se obtiene un token mediante el endpoint de inicio de sesión correspondiente al perfil. Para una integración gestionada por la federación se utiliza POST /login/federacio con un cuerpo JSON como este:

{
  "usuari": "usuario-de-integracion",
  "contrasenya": "contraseña-segura"
}

La respuesta contiene access_token . Debe enviarse en las peticiones posteriores mediante la cabecera:

Authorization: Bearer <access_token>

La documentación pública también detalla los inicios de sesión disponibles para otros perfiles, como club, federado, consultor o simpatizante. Utilizad el que corresponda al caso de uso y a los permisos necesarios.

Qué se puede integrar

La API incluye operaciones de consulta y, cuando el endpoint y los permisos lo permiten, de gestión. Entre las áreas disponibles se encuentran:

Federados, datos personales, titulaciones y licencias.
Clubes, equipos, modalidades, categorías y subcategorías.
Temporadas, ligas, grupos, jornadas, calendarios, partidos, actas, resultados y clasificaciones.
Arbitrajes, sanciones, tarjetas, goleadores y notificaciones.

Para conocer los requisitos y los campos de cada operación, consultad el endpoint concreto en Swagger antes de implementar la integración.

Flujo habitual para altas de federados y licencias

Obtener el token con una cuenta de federación.
Comprobar si el federado ya existe mediante uno de sus identificadores.
Crear el federado si no existe, o actualizarlo si ya existe.
Crear la licencia indicando el federado y los identificadores del club y de la subcategoría.

Comprobar si existe un federado

Se pueden usar tres identificadores: DNI/NIF, pasaporte/residencia o tarjeta sanitaria/CatSalut. Si la respuesta es 404 , el federado no existe. Si existe, conservad el valor idFederat para las operaciones posteriores.

Crear o actualizar un federado

Una creación correcta devuelve 201 . Para actualizar, utilizad el idFederat recibido; una respuesta 204 indica que la petición se ha procesado correctamente.

Crear una licencia

Los datos mínimos habituales son:

idFederat : identificador del federado.
codiClubExtern : código externo configurado en el club; también puede utilizarse idClub .
codiSubCat : código configurado en la subcategoría; también puede utilizarse idSubCategoria .

Una licencia creada correctamente devuelve 201 .

Recomendaciones para la integración

Tratad los códigos HTTP de error y no repitáis automáticamente una operación de creación sin comprobar antes si se completó.
Guardad de forma segura los identificadores devueltos por la API para relacionar los datos entre ambos sistemas.
Probad primero con datos de prueba y confirmad con soporte los flujos de escritura que afecten a licencias, competición o datos personales.
Si necesitáis una operación no documentada o tenéis dudas sobre los permisos, indicadnos el sistema a conectar y los datos que queréis consultar o actualizar.

Documentación técnica completa

https://apifederacions.playoffinformatica.com/

Ejemplos paso a paso

Se mantienen los ejemplos visuales originales para las operaciones habituales de federados y licencias.

El primer paso es obtener el token con las credenciales de un usuario de federación. El access_token de la respuesta será necesario para las demás peticiones.