📚 Documentación de la API Floid - OAuth 2.0

Guía completa para integrar la API de Floid usando autenticación OAuth 2.0

🚀 Inicio Rápido

📋 Prerequisitos

• Credenciales OAuth: Recibirás client_id y client_secret por correo electrónico
• Entorno: HTTPS requerido para producción
• Formato: Todas las respuestas son en formato JSON

🔑 Proceso de Autenticación

1. Obtener Token → Usar credenciales para generar token de acceso
2. Hacer Llamadas → Incluir token en header de autorización
3. Renovar Token → Generar nuevo token cuando expire (3 horas)

🔐 Autenticación OAuth 2.0

1. Obtener Token de Acceso

Endpoint: POST https://api.floid.app/oauth_server/?endpoint=token

Headers:

Content-Type: application/x-www-form-urlencoded

Body (Form Data):

grant_type=client_credentials
client_id=tu_client_id
client_secret=tu_client_secret

Ejemplo con cURL:

curl -X POST 'https://api.floid.app/oauth_server/?endpoint=token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=tu_client_id' \
  -d 'client_secret=tu_client_secret'

Respuesta Exitosa:

{
  "access_token": "oauth_abc123def456...",
  "token_type": "Bearer",
  "expires_in": 10800,
  "scope": "api"
}

Parámetros de Respuesta:

• access_token: Token de acceso a usar en llamadas posteriores
• token_type: Siempre será "Bearer"
• expires_in: Tiempo de vida del token en segundos (3 horas = 10800 segundos)
• scope: Alcance del token (siempre "api")

⚠️ Manejo de Errores

Errores de Autenticación

Credenciales Inválidas

{
  "error": "invalid_client",
  "error_description": "Las credenciales del cliente son inválidas"
}

Token Expirado

{
  "error": "token_expired", 
  "error_description": "El token OAuth ha expirado. Por favor genera un nuevo token.",
  "token_endpoint": "/oauth_server/?endpoint=token"
}

Token Inválido

{
  "error": "invalid_token",
  "error_description": "El token proporcionado no es válido"
}

Falta Header de Autorización

{
  "error": "unauthorized",
  "error_description": "Se requiere autenticación. Incluye el header Authorization."
}

Códigos de Estado HTTP

🔄 Gestión de Tokens

Validar Token (Opcional)

Endpoint: POST https://api.floid.app/oauth_server/?endpoint=introspect

Body:

token=oauth_tu_token_aqui

Respuesta Token Activo:

{
  "active": true,
  "client_id": 44,
  "scope": "api", 
  "token_type": "Bearer",
  "expires_in": 8450
}

Respuesta Token Inactivo:

{
  "active": false
}

Revocar Token

Endpoint: POST https://api.floid.app/oauth_server/?endpoint=revoke

Body:

token=oauth_tu_token_aqui

Respuesta:

{
  "revoked": true
}

🔧 Información Técnica

Especificaciones

• Protocolo: OAuth 2.0 (RFC 6749)
• Grant Type: Client Credentials
• Token Type: Bearer (RFC 6750)
• Formato: JSON
• Codificación: UTF-8
• Vida del Token: 3 horas (10800 segundos)

Límites y Restricciones

• Tiempo de Vida del Token: 3 horas
• Tokens Concurrentes: 1 token activo por cliente
• Protocolo: Solo HTTPS en producción
• Tamaño Máximo del Payload: 1MB

Headers Requeridos

Authorization: Bearer {access_token}
Content-Type: application/json
User-Agent: TuApp/1.0

🛠️ Mejores Prácticas

✅ Recomendaciones

1. Gestión de Tokens

   • Almacena el token de forma segura
   • Renueva automáticamente antes de que expire
   • Nunca hardcodees credenciales en el código

2. Manejo de Errores

   • Implementa retry logic para errores 5xx
   • Maneja específicamente errores 401 (renovar token)
   • Loggea errores para debugging

3. Seguridad

   • Usa HTTPS siempre
   • Almacena credenciales en variables de entorno
   • No expongas tokens en logs o URLs

4. Rendimiento

   • Reutiliza conexiones HTTP
   • Implementa caching cuando sea apropiado
   • Monitorea el tiempo de expiraci��n del token

❌ Evita

• ❌ Solicitar nuevo token en cada llamada
• ❌ Ignorar códigos de error HTTP
• ❌ Almacenar credenciales en código
• ❌ Usar HTTP en producción
• ❌ No manejar expiración de tokens

📞 Soporte

🐛 Reportar Problemas

Si encuentras algún problema con la integración:

1. Verifica tu implementación contra esta documentación
2. Revisa los códigos de error en la sección de manejo de errores
3. Contacta al equipo técnico con:
   • Descripción del problema
   • Código de respuesta HTTP
   • Mensaje de error (sin incluir credenciales)
   • Timestamp del incidente

📋 Información para Soporte

Al contactar soporte, incluye:

• ✅ Descripción del problema
• ✅ Pasos para reproducir
• ✅ Código de error recibido
• ✅ Timestamp del incidente
• ❌ No incluyas credenciales ni tokens

🎉 ¡Ya estás listo para integrar con la API de Floid!

Sigue los ejemplos de código y las mejores prácticas para una integración exitosa. Para más ayuda, consulta la sección de soporte.