Nueva API de Afirmaciones

Nueva API de Afirmaciones

De bucles infinitos a bienestar instantáneo: la API de Afirmaciones se ha reconstruido para ofrecer positividad diaria y personalizada sin ninguna fricción. Cada afirmación ahora incluye un ID estable, datos limpios y depurados, y un esquema enriquecido, junto con búsqueda, paginación, endpoints de lote y diarios, un kit completo de bienestar y respuestas en texto plano para SMS y asistentes de voz.

🚀 Novedades

  • IDs estables – Cada afirmación lleva un id consistente basado en hash, para que los widgets, las notificaciones y las cachés se mantengan sincronizados.
  • Datos limpios, automáticamente – Los campos de texto y categoría se depuran de espacios en blanco sobrantes antes de llegar a tu app.
  • Categorías inteligentes – Las 19 categorías se derivan directamente del conjunto de datos y se ordenan, sin desviaciones codificadas de forma fija.
  • Errores útiles – Las categorías desconocidas devuelven un 404 claro en lugar de colgarse o entrar en bucle.
  • Esquema más rico – Cada afirmación devuelve id, text, category, mood, lang y length.
  • Encuentra lo que necesitas – Búsqueda y paginación en el endpoint de listado, además de un endpoint de lote configurable.
  • Selecciones diarias deterministas – /today devuelve la misma afirmación del día para todos los usuarios.
  • Kit de bienestar – Personaliza por nombre, reformula pensamientos negativos y combina afirmaciones con ejercicios de respiración.

🛠 Endpoints de la API

1. Listar afirmaciones

GET /v1/affirmations

Parámetros:

  • category (opcional): Filtra la lista por categoría, como confidence o self-love.
  • search (opcional): Búsqueda de texto completo en el texto de las afirmaciones.
  • page (predeterminado: 1): Número de página para la paginación.
  • limit (predeterminado: 10): Resultados por página, hasta un máximo de 50.
  • lang (predeterminado: en): Código de idioma. En esta versión se devuelve contenido en inglés.

2. Afirmación aleatoria

GET /v1/affirmations/random

Parámetros:

  • category (opcional): Devuelve una afirmación aleatoria de una categoría específica.
  • lang (predeterminado: en): Código de idioma. En esta versión se devuelve contenido en inglés.
  • format (predeterminado: json): Usa json para el objeto completo o text para una respuesta en texto plano.

3. Afirmación aleatoria por categoría

GET /v1/affirmations/categories/{category}/random

Parámetros:

  • category (obligatorio): La categoría de la que elegir, como sleep. Las categorías desconocidas devuelven un 404 claro.

4. Listar categorías

GET /v1/affirmations/categories

Devuelve la lista completa y ordenada de categorías, desde anxiety-relief y calm hasta confidence, focus, gratitude, parenting, resilience, self-love, sleep, success y más.

5. Afirmaciones en lote

GET /v1/affirmations/batch

Parámetros:

  • category (opcional): Filtra el lote por categoría.
  • limit (predeterminado: 10): Número de afirmaciones a devolver, hasta un máximo de 50.
  • lang (predeterminado: en): Código de idioma. En esta versión se devuelve contenido en inglés.

6. Afirmación de hoy

GET /v1/affirmations/today

Parámetros:

  • category (opcional): Devuelve la selección diaria determinista dentro de una categoría.
  • lang (predeterminado: en): Código de idioma. En esta versión se devuelve contenido en inglés.

El alias /daily devuelve la misma afirmación del día.

7. Personalizar

POST /v1/affirmations/personalize

Cuerpo:

  • mood (opcional): Estado de ánimo o categoría de la que extraer, como confidence. El valor predeterminado es happiness.
  • goal (opcional): La intención detrás de la afirmación.
  • name (opcional): Un nombre para integrar en la afirmación, por ejemplo “I am confident, Ava.”

8. Reformular un pensamiento negativo

POST /v1/affirmations/reframe

Cuerpo:

  • negativeThought (obligatorio): El pensamiento a reformular, por ejemplo “I always fail”.

Devuelve una declaración reformulada junto con una afirmación de resilience que le corresponde.

9. Paquete de afirmación + respiración

GET /v1/affirmations/bundle

Parámetros:

  • category (opcional): La categoría de la que extraer. La categoría sleep devuelve el ejercicio de respiración 4-7-8; todas las demás categorías devuelven box breathing.

10. Horario sugerido

GET /v1/affirmations/schedule

Parámetros:

  • timezone (opcional): Etiqueta de zona horaria para las franjas sugeridas, por ejemplo Europe/Berlin. El valor predeterminado es UTC.

📦 Ejemplos de respuesta

Afirmación aleatoria:

{
  "id": 1874329517,
  "text": "I am confident, capable, and ready for today.",
  "category": "confidence",
  "mood": "confidence",
  "lang": "en",
  "length": 42
}

Afirmación personalizada:

{
  "id": 55123874,
  "text": "I am confident, Ava.",
  "category": "confidence",
  "mood": "confidence",
  "lang": "en",
  "length": 20
}

Pensamiento reformulado:

{
  "reframe": "Even though \"I always fail\", I choose to believe: I am learning and growing every day.",
  "affirmation": {
    "id": 912345678,
    "text": "I am learning and growing every day.",
    "category": "resilience",
    "mood": "resilience",
    "lang": "en",
    "length": 36
  }
}

Paquete de bienestar:

{
  "affirmation": {
    "id": 44556677,
    "text": "I release the day and welcome rest.",
    "category": "sleep",
    "mood": "sleep",
    "lang": "en",
    "length": 36
  },
  "breathing": {
    "name": "4-7-8",
    "steps": ["Inhale 4s", "Hold 7s", "Exhale 8s"]
  }
}

Horario sugerido:

{
  "morning": "08:00 Europe/Berlin",
  "evening": "21:00 Europe/Berlin",
  "timezone": "Europe/Berlin"
}

✨ Respuestas en múltiples formatos

El endpoint aleatorio habla tanto JSON como texto plano. Usa ?format=json (el predeterminado) para el objeto estructurado completo en apps web y móviles, o ?format=text para una cadena lista para enviar en flujos de SMS, asistentes de voz y widgets.

🎯 Creada para

  • Desarrolladores que crean apps de bienestar, chatbots y funciones de motivación y quieren una API estable y bien documentada.
  • Product managers que aumentan la interacción con notificaciones diarias, rachas y contenido diario determinista.
  • Creadores de apps de bienestar que necesitan contenido de afirmaciones fiable y categorizado a escala.
  • Equipos empresariales que esperan endpoints escalables al estilo SDK con incorporación lista para Postman.

🌟 ¿Por qué elegir la API de Afirmaciones?

  • Fiable por diseño: IDs estables, datos depurados y 404 claros significan menos sorpresas en producción.
  • Profundidad cuando la necesitas: 19 categorías que abarcan desde anxiety relief hasta self-love.
  • Más de una llamada: Personalización, reformulación, paquetes de respiración y programación en una sola API.
  • Amigable para desarrolladores: Búsqueda, paginación, procesamiento por lotes, respuestas en múltiples formatos y fragmentos de código listos para usar.
  • Lista para el bienestar: 99.99% de disponibilidad con respuestas de baja latencia para los momentos positivos del día a día.

🚀 Empieza ahora

  • Colección de Postman: Importa docs/affirmations-postman.json para explorar cada endpoint con un solo clic.
  • Fragmentos de código: Copia ejemplos listos para ejecutar en cURL, JavaScript y Python desde docs/affirmations-snippets.md.
  • Lista para LLM: docs/llms.txt ofrece a los agentes de IA un resumen estructurado de la API.

Empieza hoy mismo a crear momentos positivos: llama al endpoint today para obtener una afirmación diaria determinista y luego añade personalización y paquetes de respiración para completar la experiencia de bienestar.