API de tarot

Dada una pregunta opcional y una semilla opcional, el endpoint extrae cartas del mazo completo de 78 cartas para la disposición de tres cartas, con cada carta cayendo en una posición definida y orientada hacia arriba o invertida. La respuesta describe la tirada en sí, devuelve la semilla entera utilizada, y enumera las cartas extraídas: cada una con su etiqueta de posición, su orientación y el significado asociado a esa carta en esa orientación. La semilla es el corazón del diseño: omítela y el servidor genera una por ti y la devuelve; suminístrala y regeneras una tirada idéntica, lo que hace que las lecturas sean compartibles, comprobables y auditables. El indicador allowReversed decide si las inversiones son posibles siquiera. Otras tiradas —de una carta, Cruz Celta, herradura, relación y año por delante— son endpoints hermanos impulsados por el mismo mazo y el mismo mecanismo de sembrado.

curl -X POST https://api.astroway.info/v1/tarot/rider-waite/draw/three-card \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "question": "How will my new project unfold?"
}'

{
  "ok": true,
  "data": {
    "spread": {
      "slug": "three-card",
      "name": "Three Card",
      "cardCount": 3
    },
    "seed": 4044793529,
    "drawn": [
      {
        "position": {
          "index": 0,
          "name": "Past"
        },
        "card": {
          "slug": "knight-of-wands",
          "name": "Knight of Wands"
        },
        "reversed": false,
        "meaning": "…"
      }
    ]
  }
}

Recurre a esto cuando quieras una lectura de tarot que puedas reproducir a demanda en lugar de una tirada aleatoria única. Captura la semilla devuelta y podrás volver a renderizar las mismas tres cartas exactas más tarde —en un enlace compartido, una lectura guardada, una prueba de regresión o un ticket de soporte— sin almacenar tú mismo la lista de cartas. Usa una semilla fija en las pruebas para que tu interfaz y tu copia se rendericen de forma determinista, y deja que el servidor acuñe una semilla nueva en producción para una variedad genuina. Recurre a la tirada de tres cartas específicamente cuando quieras una estructura compacta de estilo pasado/presente/futuro; cambia a un endpoint hermano cuando una disposición con más posiciones se ajuste mejor a la experiencia.

Las imágenes de las cartas son del mazo Rider-Waite-Smith (A. E. Waite y Pamela Colman Smith, 1909), que es de dominio público. Establece allowReversed en false para extraer solo cartas hacia arriba, útil para lecturas amigables para principiantes donde los significados invertidos añadirían confusión. La misma semilla reproduce una tirada solo para la misma tirada y el mismo ajuste de allowReversed.