API - Calendario 260 (Core)

Documentación del endpoint REST para conversión al Calendario Maya Tzolkin.

Endpoints Disponibles

POST /api/v1/convert

Convierte una fecha gregoriana al Calendario 260.

Headers Requeridos

Content-Type: application/json
Accept: application/vnd.pit.v1+json
x-pit-key: <tu_clave_api>

Request Body

{
  "from": "gregorian",
  "to": "calendario-260",
  "instant": "2025-09-21T00:00:00Z"
}

Response

{
  "value": {
    "kin": 158,
    "tono": {
      "id": 2,
      "nombre": "Lunar",
      "clave": "lunar"
    },
    "sello": {
      "id": 18,
      "nombre": "Espejo",
      "clave": "espejo"
    },
    "meta": {
      "provisional": false,
      "correlation": "ds",
      "anchorJDN": 2447003,
      "offset": 0,
      "formula": "JDN",
      "correlationSource": "env"
    }
  },
  "meta": {
    "module": "calendario-260",
    "versions": {
      "api": "v1",
      "module": "1.0.0"
    }
  }
}

Ejemplos de Uso

cURL

curl -X POST "https://pit-api.pages.dev/api/v1/convert" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.pit.v1+json" \
  -H "x-pit-key: <tu_clave>" \
  -d '{
    "from": "gregorian",
    "to": "calendario-260",
    "instant": "2025-09-21T00:00:00Z"
  }'

JavaScript

const response = await fetch('https://pit-api.pages.dev/api/v1/convert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/vnd.pit.v1+json',
    'x-pit-key': '<tu_clave>'
  },
  body: JSON.stringify({
    from: 'gregorian',
    to: 'calendario-260',
    instant: '2025-09-21T00:00:00Z'
  })
});

const data = await response.json();
console.log(`Kin: ${data.value.kin}`);

GET /api/v1/calendario-260/:kin/details

Obtiene información detallada de un kin específico del calendario maya.

Headers Requeridos

Accept: application/vnd.pit.v1+json

Parámetros

• kin (number): Número del kin (1-260)

Response

{
  "value": {
    "kin": 158,
    "tono": { "id": 2 },
    "sello": { "id": 18 },
    "onda": { "id": 13, "posicion": 2 },
    "castillo": { "id": 4 },
    "derived": {
      "family": null,
      "portal": null,
      "waveName": null,
      "sealName": null,
      "toneName": null,
      "castleName": null
    },
    "meta": {
      "correlation": "pending-core"
    }
  },
  "meta": {
    "precision": "exact",
    "module": "calendario-260",
    "versions": { "api": "v1", "module": "1.0.0" }
  }
}

Ejemplo de Uso

curl -H "Accept: application/vnd.pit.v1+json" \
  "https://pit-api.pages.dev/api/v1/calendario-260/158/details"

Dataset Completo

La API utiliza un dataset completo de 260 kins con información detallada:

Estructura de Datos

• 20 Sellos: Dragón, Viento, Noche, Semilla, Serpiente, Enlazador, Mano, Estrella, Luna, Perro, Mono, Humano, Caminante, Mago, Águila, Guerrero, Tierra, Espejo, Tormenta, Sol
• 13 Tonos: Magnético, Lunar, Eléctrico, Autoexistente, Entonado, Rítmico, Resonante, Galáctico, Solar, Planetario, Espectral, Cristal, Cósmico
• 4 Colores: Rojo, Blanco, Azul, Amarillo
• 4 Direcciones: Este, Norte, Oeste, Sur
• 5 Castillos: Rojo, Blanco, Azul, Amarillo

Ejemplos de Kins

• Kin 1: Dragón 1 (Rojo) - "Yo nazco para nutrir"
• Kin 158: Espejo 2 (Blanco) - "Yo reflejo para ordenar"
• Kin 260: Sol 13 (Amarillo) - "Yo ilumino para florecer"

Códigos de Error

Código	Descripción
400	Datos de entrada inválidos
401	API key requerida o inválida
404	Endpoint no encontrado
429	Rate limit excedido
500	Error interno del servidor

Rate Limiting

• Límite: 100 requests por minuto por IP
• Headers de respuesta: X-RateLimit-*
• Retry-After: Incluido en respuestas 429

Autenticación

La API requiere una clave API válida en el header x-pit-key. Contacta al administrador para obtener una clave.

Soporte

Para soporte técnico o reportar problemas: - Issues: GitHub Issues - Documentación: PIT Blueprint