Claves de API — tnea_ y tnsr_¶

NumerologyAPI utiliza dos familias de claves de API. Ambas tienen un aspecto similar, se generan con el mismo formato seguro de 80 caracteres y se autentican con el mismo encabezado X-API-Key — pero se facturan de manera diferente y están pensadas para productos distintos.

1. Formato y Seguridad de la Clave¶

Toda clave tiene exactamente 80 caracteres:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• El prefijo de 4 caracteres identifica el tipo de clave; los 75 caracteres restantes se generan con una fuente aleatoria criptográficamente segura.
• Las claves se almacenan con hash SHA-256 en el servidor. La clave en texto plano se muestra solo una vez, en el momento de su creación.
• Si alguna vez se expone una clave, rótala inmediatamente desde el panel de control.

2. Claves de Plataforma (tnea_)¶

Las claves de plataforma son las claves estándar para integrar NumerologyAPI en tu propio producto — sitios web, aplicaciones móviles y servicios de servidor.

Autenticación¶

Envía la clave en cada solicitud con el encabezado X-API-Key:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

Facturación¶

Las llamadas facturables a /api/v1 se deducen del monedero de créditos de tu organización (pago por uso). Puedes recargar el monedero en cualquier momento desde el panel de control.

Regla de canal: las claves de plataforma no deben enviar el encabezado X-Numora-Client. Enviarlo devuelve 403 — ese encabezado está reservado para el canal de escritorio.

3. Claves de Numora Studio (tnsr_)¶

Las claves de Numora Studio autentican la aplicación de escritorio Numora Studio (macOS/Windows) que los profesionales utilizan para generar informes de clientes. Son un hermano de las claves de plataforma con un formato idéntico, pero se facturan contra la asignación del plan de Numora Studio de la organización en lugar de contra los créditos de plataforma.

Aprovisionamiento¶

Una clave tnsr_ se crea de dos maneras:

• a través del flujo de inicio de sesión de la aplicación de escritorio (la página de consentimiento del navegador aprovisiona una clave automáticamente), o
• manualmente en la página Claves de API del panel de control (/api-keys).

Firma de canal (obligatoria)¶

Toda llamada realizada con una clave tnsr_ debe incluir el encabezado de canal de escritorio:

Aplicación en el servidor:

• Clave tnsr_ sin X-Numora-Client → 403.
• Clave tnea_ con X-Numora-Client → 403.

Facturación¶

• Las llamadas facturables a /api/v1 se deducen de la asignación del plan de Numora Studio de la organización (un fondo compartido entre todas las claves tnsr_ de la organización).
• Existe un alternador de reserva de créditos por clave tnsr_: cuando la asignación del plan se agota, la clave puede recurrir a los créditos de plataforma de la organización (desactivado por defecto).
• Si la asignación se agota y no hay ninguna reserva habilitada, las llamadas devuelven 429.

Bloqueo de dispositivo (opcional)¶

Una clave tnsr_ puede bloquearse a dispositivos registrados. Con el bloqueo habilitado, cada solicitud debe llevar un X-Numora-Device-Id registrado en la organización; los dispositivos no registrados son rechazados con 403.

Endpoints exclusivos de escritorio¶

Algunos endpoints están reservados para el canal de escritorio y devuelven 403 para las claves tnea_:

• POST /api/v1/numora/report-bundle — informe completo del cliente en una sola llamada
• POST /api/v1/numora/order — flujo de compra de plan/asignación dentro de la aplicación
• POST /api/v1/numora/devices/register — registra una instalación de escritorio
• GET /api/v1/numora/studio-status — saldos de escritorio y medidores de cuota

Consejo: las respuestas facturables también incluyen los encabezados X-Remaining-Credits y X-Remaining-Tokens para que puedas consultar los saldos en vivo sin llamadas adicionales.

4. Gestión de Claves (Panel de Control)¶

La página Claves de API del panel de control (/api-keys) es el centro de control para ambos tipos de clave.

Roles: los roles admin y developer pueden crear y gestionar claves. finance no puede crear claves de API de producción. Las operaciones financieras (compras de planes, recargas) están limitadas a admin y finance.

Múltiples claves: las organizaciones pueden tener muchas claves de ambos tipos — por ejemplo, una clave tnsr_ por profesional o por instalación de escritorio. Las asignaciones se comparten por organización, por lo que las claves nunca "compiten" por su propio saldo.

5. Buenas Prácticas¶

• Trata las claves como contraseñas. Nunca las incrustes en código del lado del cliente, repositorios públicos o registros.
• Usa variables de entorno o un gestor de secretos en tu backend.
• Rota inmediatamente si una clave se ve comprometida o un miembro del equipo se va.
• Usa una clave tnsr_ por instalación de escritorio para simplificar la gestión de dispositivos y la revocación.
• Habilita el bloqueo de dispositivo en organizaciones de alta seguridad.
• Supervisa el uso en el panel de control para detectar picos inesperados a tiempo.

6. Preguntas Frecuentes¶

¿Puede una clave tnsr_ llamar a endpoints de plataforma regulares? Sí. Las claves de Numora Studio autentican toda la superficie de /api/v1; esas llamadas se facturan contra la asignación del plan de Numora Studio.

¿Puede una clave tnea_ llamar a los endpoints exclusivos de escritorio /numora/*? No. Los endpoints exclusivos de escritorio devuelven 403 para las claves de plataforma.

¿Por qué recibo 403 al llamar con mi clave tnsr_? Lo más probable es que falte el encabezado X-Numora-Client o que el id de la aplicación no coincida. Verifica que cada solicitud incluya X-Numora-Client: numora-studio/<version>.

¿Por qué recibo 403 con mi clave tnea_? Las claves de plataforma no deben llevar el encabezado X-Numora-Client — elimínalo.

¿Qué sucede cuando se agota mi asignación? Las llamadas facturables devuelven 429 a menos que la reserva de créditos esté habilitada en tu clave tnsr_ (o que recargues tu monedero de plataforma para las claves tnea_).

Relacionado¶

• Comenzar
• Precios
• Soluciones Empresariales