📚 Documentación

IA Profesional. Integración Simple. Resultados Reales.

Bienvenido a la documentación oficial de las APIs de ApisDom. Aquí encontrarás todo lo necesario para integrar nuestros servicios de inteligencia artificial en tus aplicaciones.

---

Nuestras APIs

API	Descripción	Modelo
🎭 [Sentiment API]	Detecta emociones en texto (positivo/negativo)	DistilBERT (SST-2)
🛡️ [Moderation API]	Identifica contenido tóxico e inapropiado	Toxic-BERT (Jigsaw)
📈 [Prediction API]	Predicciones de series temporales	Chronos-2 (Amazon)
⚡ [Recommendations API]	Recomendaciones personalizadas por similitud semántica	all-MiniLM-L6-v2

---

⚡ Inicio Rápido

Paso 1: Obtén tu API Key

1. Regístrate en apisdom.com y obten 1250 llamadas Gratis
2. Ve al Dashboard
3. Copia tu API Key

Tu panel de usuario:

▶ Ver recorrido: Panel de Usuario

Paso 2: Tu Primera Llamada

curl -X POST "https://apisdom.com/api/v1/sentiment" \
  -H "X-API-Key: TU_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"text": "This product is amazing!"}'

Respuesta

La respuesta es ANIDADA con dos objetos principales: _metadata y response.

{
  "_metadata": {
    "provider": "ApisDom",
    "tagline": "Inteligencia artificial transparente",
    "website": "https://apisdom.com",
    "timestamp": "2026-01-21T10:00:00.000Z",
    "service": "Sentiment Analysis",
    "channel": "ApisDom Platform",
    "request_id": "sent_1768954704623_abc123",
    "documentation": "https://apisdom.com/documentacion"
  },
  "response": {
    "text": "This product is amazing!",
    "sentiment": "positive",
    "score": 0.9721,
    "warning": null,
    "info_message": null
  }
}

⚠️ Importante: Todas las APIs devuelven esta estructura anidada. Accede a los datos mediante resultado['response'] o resultado.response.

---

🔐 Autenticación

Todas las APIs requieren tu API Key en el header X-API-Key:

X-API-Key: tu_api_key_aqui

Obtener tu API Key

1. Inicia sesión en tu Dashboard
2. Ve a "API Keys"
3. Genera o copia tu API Key

Seguridad

• Las API Keys son permanentes y están vinculadas a tu cuenta
• NO compartas tu API Key públicamente
• NO la incluyas en código público (GitHub, etc.)
• Guárdala de forma segura (variables de entorno, secrets manager)

---

💳 Planes y Precios

Consulta los planes disponibles y precios actualizados en: apisdom.com/pricing

Sobre los Créditos

• Los créditos se descuentan DESPUÉS de ejecutar el modelo IA exitosamente
• Si hay un error en el procesamiento, el crédito NO se consume
• Cada llamada a la API consume 1 crédito

---

📊 Headers Informativos

La API devuelve headers que te permiten controlar tu consumo programáticamente:

Header	Descripción
X-RateLimit-Limit	Tu límite de peticiones por minuto
X-RateLimit-Remaining	Peticiones restantes en la ventana actual
Retry-After	Segundos a esperar si recibes 429

---

❄️ Cold Start

Para optimizar costes, los microservicios de IA escalan a cero cuando no hay actividad.

💡 Nota: La primera petición puede tardar ~20 segundos mientras el servicio arranca. Las peticiones siguientes serán < 500ms mientras el servicio permanezca activo.

---

⚠️ Códigos de Error

Código	Estado	Significado	Solución
200	✅ Éxito	Todo correcto	Procesar respuesta
400	❌ Request inválido	Formato JSON incorrecto	Revisar parámetros enviados
401	🔒 No autorizado	API Key inválida o revocada	Verificar API Key en dashboard
402	💳 Sin créditos	Créditos agotados	Consultar planes
422	❌ Datos inválidos	Campos requeridos faltantes	Revisar campos requeridos
429	⏱️ Rate limit	Límite de peticiones excedido	Esperar según Retry-After
500	🔥 Error servidor	Error interno	Reintentar en 30s

Ejemplo de Error 402

{
  "detail": "Créditos insuficientes. Consulta planes en apisdom.com/pricing"
}

---

🩺 Health Checks

Cada API expone un endpoint de health check (sin autenticación):

API	Endpoint
Sentiment	GET https://apisdom.com/api/v1/sentiment
Moderation	GET https://apisdom.com/api/v1/moderacion
Prediction	GET https://apisdom.com/api/v1/predictions
Recommendations	GET https://apisdom.com/api/v1/recommendations/health

{
  "status": "healthy",
  "service": "sentiment",
  "valid": true,
  "timestamp": "2026-01-21T10:00:00.000Z",
  "provider": "ApisDom"
}

---

⚡ Límites por Request

API	Campo	Límite
Sentiment	text	1-5,000 caracteres
Moderation	text	1-5,000 caracteres
Prediction	dates / values	10-5,000 puntos
Prediction	periods	1-365 días
Recommendations	query	3-500 caracteres
Recommendations	contents	1-100 items (máx 1,000 chars/item)
Recommendations	top_k	1-20 resultados

Nota: Los modelos BERT procesan máximo 512 tokens. Textos más largos serán truncados y recibirás un warning en la respuesta.

---

💻 Ejemplos de Código

Python - Análisis de Sentimiento

import requests

API_URL = "https://apisdom.com/api/v1/sentiment"
API_KEY = "tu_api_key_aqui"

def analizar_sentimiento(texto):
    response = requests.post(
        API_URL,
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={"text": texto}
    )
    response.raise_for_status()
    return response.json()

# Uso
resultado = analizar_sentimiento("This product is excellent!")

# IMPORTANTE: Acceder al objeto 'response' anidado
datos = resultado['response']
print(f"Sentimiento: {datos['sentiment']}")
print(f"Confianza: {datos['score']:.0%}")
print(f"Request ID: {resultado['_metadata']['request_id']}")

# Output:
# Sentimiento: positive
# Confianza: 97%
# Request ID: sent_1768954704623_abc123

JavaScript - Moderar Contenido

const API_URL = 'https://apisdom.com/api/v1/moderacion';
const API_KEY = 'tu_api_key_aqui';

async function moderarContenido(texto) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text: texto })
  });
  
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

// Uso
const resultado = await moderarContenido('Thank you for your help!');

// IMPORTANTE: Acceder al objeto 'response' anidado
const datos = resultado.response;
console.log(`Es tóxico: ${datos.is_toxic}`);
console.log(`Score: ${(datos.toxicity_score * 100).toFixed(0)}%`);

// Output:
// Es tóxico: false
// Score: 2%

cURL - Predecir Serie Temporal

curl -X POST "https://apisdom.com/api/v1/predictions" \
  -H "X-API-Key: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "dates": ["2024-01-01","2024-01-02","2024-01-03","2024-01-04","2024-01-05",
              "2024-01-06","2024-01-07","2024-01-08","2024-01-09","2024-01-10"],
    "values": [100,105,102,108,115,112,120,118,125,130],
    "periods": 5
  }'

# La respuesta incluye _metadata y response anidados

cURL - Obtener Recomendaciones

curl -X POST "https://apisdom.com/api/v1/recommendations" \
  -H "X-API-Key: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning tutorials",
    "contents": [
      "Python ML basics for beginners",
      "JavaScript introduction and syntax",
      "Deep Learning with PyTorch guide",
      "Data Science with pandas",
      "React frontend development"
    ],
    "top_k": 3
  }'

# Respuesta: Lista de contenidos ordenados por similitud semántica

---

🏗️ Cliente Robusto para Producción

Este código maneja TODOS los casos de error reales que puede devolver la API:

import time
import requests
from typing import Any

class ApisDomClient:
    """
    Cliente robusto para APIs de ApisDom.
    Maneja: retry, backoff exponencial, rate limit, sin créditos.
    """
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            "X-API-Key": api_key,
            "Content-Type": "application/json"
        })
        self.base_url = "https://apisdom.com/api/v1"
    
    def _request_with_retry(
        self, 
        method: str, 
        endpoint: str, 
        json_data: dict | None = None,
        max_retries: int = 3
    ) -> dict[str, Any]:
        """Ejecuta request con reintentos y manejo de errores."""
        url = f"{self.base_url}/{endpoint}"
        
        for attempt in range(max_retries):
            try:
                response = self.session.request(
                    method, url, json=json_data, timeout=30
                )
                
                # Éxito
                if response.status_code == 200:
                    return response.json()
                
                # Sin créditos - no reintentar
                if response.status_code == 402:
                    raise CreditosInsuficientesError(
                        "Sin créditos. Consulta planes en: https://apisdom.com/pricing"
                    )
                
                # API Key inválida - no reintentar
                if response.status_code == 401:
                    raise ApiKeyInvalidaError(
                        "API Key inválida. Verifica en tu Dashboard."
                    )
                
                # Rate limit - esperar y reintentar
                if response.status_code == 429:
                    retry_after = int(response.headers.get("Retry-After", 60))
                    print(f"Rate limit. Esperando {retry_after}s...")
                    time.sleep(retry_after)
                    continue
                
                # Error servidor - backoff exponencial
                if response.status_code >= 500:
                    wait_time = (2 ** attempt) * 1
                    print(f"Error {response.status_code}. Retry en {wait_time}s...")
                    time.sleep(wait_time)
                    continue
                
                response.raise_for_status()
                
            except requests.exceptions.Timeout:
                if attempt < max_retries - 1:
                    wait_time = (2 ** attempt) * 2
                    print(f"Timeout. Retry en {wait_time}s...")
                    time.sleep(wait_time)
                    continue
                raise
        
        raise Exception(f"Falló después de {max_retries} intentos")
    
    def analizar_sentimiento(self, texto: str) -> dict:
        """Analiza el sentimiento de un texto."""
        result = self._request_with_retry("POST", "sentiment", {"text": texto})
        return result['response']  # Devuelve solo los datos útiles
    
    def moderar_contenido(self, texto: str) -> dict:
        """Modera contenido para detectar toxicidad."""
        result = self._request_with_retry("POST", "moderacion", {"text": texto})
        return result['response']
    
    def predecir_serie(
        self, 
        dates: list[str], 
        values: list[float], 
        periods: int = 7
    ) -> dict:
        """Predice valores futuros de una serie temporal."""
        result = self._request_with_retry(
            "POST", 
            "predictions", 
            {"dates": dates, "values": values, "periods": periods}
        )
        return result['response']
    
    def obtener_recomendaciones(
        self,
        query: str,
        contents: list[str],
        top_k: int = 5
    ) -> dict:
        """Genera recomendaciones personalizadas por similitud semántica."""
        result = self._request_with_retry(
            "POST",
            "recommendations",
            {"query": query, "contents": contents, "top_k": top_k}
        )
        return result['response']


class CreditosInsuficientesError(Exception):
    """Error cuando no hay créditos disponibles."""
    pass


class ApiKeyInvalidaError(Exception):
    """Error cuando la API Key es inválida o está revocada."""
    pass


# Ejemplo de uso
if __name__ == "__main__":
    client = ApisDomClient("tu_api_key_aqui")
    
    # Sentiment
    sentiment = client.analizar_sentimiento("This product is great!")
    print(f"Sentimiento: {sentiment['sentiment']} ({sentiment['score']:.0%})")
    
    # Moderation
    moderation = client.moderar_contenido("Thank you for your help!")
    print(f"Es tóxico: {moderation['is_toxic']}")
    
    # Recommendations
    recommendations = client.obtener_recomendaciones(
        query="machine learning tutorials",
        contents=[
            "Python ML basics",
            "JavaScript intro",
            "Deep Learning with PyTorch"
        ],
        top_k=3
    )
    print(f"Top recomendación: {recommendations['results'][0]['item']}")

---

✅ Checklist Pre-Producción

Antes de ir a producción, verifica que tu aplicación:

Elemento	Descripción
☐ Maneja 401	Redirige a login o muestra error de API Key
☐ Maneja 402	Muestra mensaje "Sin créditos" en UI
☐ Maneja 429	Implementa retry con header Retry-After
☐ Maneja 500	Implementa retry con backoff exponencial
☐ Accede a response	Usa resultado['response'] para los datos
☐ API Key segura	No expuesta en código público
☐ Cachea resultados	Opcional, ahorra créditos en llamadas idénticas
☐ Revisa warning	Verifica truncamiento en textos largos

---

💡 Buenas Prácticas

✅ Recomendado

• Implementar reintentos con backoff exponencial para errores 429/500
• Cachear resultados idénticos para ahorrar créditos
• Validar datos antes de enviarlos a la API
• Manejar el código 402 en tu UI (mostrar mensaje al usuario)
• Revisar el campo warning en las respuestas
• Usar variables de entorno para la API Key

❌ Evitar

• Exponer la API Key en código frontend o repositorios públicos
• Ignorar los headers de rate limit
• No manejar errores 402 (sin créditos)
• Enviar textos sin validar longitud

---

📄 Documentación Detallada

API	Documentación
🎭 Sentiment	[SENTIMENT] - Guía completa
🛡️ Moderation	[MODERATION]- Guía completa
📈 Prediction	[PREDICTION] - Guía completa
⚡ Recommendations	[RECOMMENDATIONS] - Guía completa

---

💬 ¿Necesitas Ayuda?

📧 soporte@apisdom.com

---

Última actualización de documentación: Abril 2026

ApisDom · Inteligencia Artificial Transparente

Detecta automáticamente si un texto expresa emociones positivas o negativas utilizando el modelo DistilBERT (fine-tuned en SST-2).

⚠️ Limitaciones Conocidas (Leer antes de usar)

1. Modelo Binario: El modelo ha sido entrenado con críticas de cine (SST-2). Está diseñado para detectar polaridad fuerte (Positivo vs Negativo). No existe clase "neutral" nativa.
2. Textos Neutros/Fácticos: Debido a la naturaleza del dataset de entrenamiento, el modelo tiende a forzar una clasificación positiva o negativa incluso en textos puramente informativos (ej: "El paquete llegó hoy"). No se recomienda para clasificar textos fácticos sin carga emocional.
3. Idioma: Optimizado exclusivamente para Inglés. Funciona con español pero con menor precisión.

Casos de Uso Recomendados

✅ Análisis de Reviews de productos (E-commerce)
✅ Feedback de clientes (Quejas vs Felicitaciones)
✅ Moderación de comentarios polarizados

Casos de Uso NO Recomendados

❌ Clasificación de noticias o hechos objetivos
❌ Detección de sarcasmo sutil
❌ Textos que requieran clasificación "neutral"

---

📍 Información General

Propiedad	Valor
URL Base	https://apisdom.com/api/v1
Método	POST
Autenticación	API Key (Header X-API-Key)
Tipo de Crédito	text
Coste por llamada	1 crédito
Modelo IA	DistilBERT (fine-tuned en SST-2 - binario: solo positive/negative)
Límite de tokens	512 tokens (textos largos serán truncados)
Datos de entrenamiento	Stanford Sentiment Treebank (SST-2) - Solo reseñas de cine

📊 Headers Informativos

La API devuelve headers que te permiten controlar tu consumo:

Header	Descripción
X-RateLimit-Limit	Tu límite de peticiones por minuto
X-RateLimit-Remaining	Peticiones restantes en la ventana actual
Retry-After	Segundos a esperar si recibes 429

❄️ Cold Start

Para optimizar costes, los microservicios de IA escalan a cero cuando no hay actividad.

💡 Nota: La primera petición puede tardar más de lo normal mientras el servicio arranca. Las peticiones siguientes serán mucho más rápidas mientras el servicio permanezca activo.

💳 Planes y Precios

Consulta los planes disponibles y precios actualizados en: apisdom.com/pricing

---

🔐 Autenticación

Todas las peticiones requieren tu API Key en el header X-API-Key:

X-API-Key: tu_api_key_aqui

Puedes obtener tu API Key desde el panel de usuario en apisdom.com/dashboard.

---

📥 Endpoint: Analizar Sentimiento

POST https://apisdom.com/api/v1/sentiment

Request Body

Campo	Tipo	Requerido	Descripción
text	string	✅ Sí	Texto a analizar. Mínimo 1 carácter, máximo 5000.

Ejemplo de Request

{
  "text": "Este producto es absolutamente increíble. La calidad supera todas mis expectativas y el envío fue rapidísimo. ¡Muy recomendado!"
}

Response Exitosa (200 OK)

La respuesta es ANIDADA con dos objetos principales: _metadata y response.

{
  "_metadata": {
    "provider": "ApisDom",
    "tagline": "Inteligencia artificial transparente",
    "website": "https://apisdom.com",
    "timestamp": "2026-01-21T10:00:00.000Z",
    "service": "Sentiment Analysis",
    "channel": "ApisDom Platform",
    "request_id": "sent_1768954704623_4cj49l3",
    "documentation": "https://apisdom.com/documentacion"
  },
  "response": {
    "text": "Este producto es absolutamente increíble. La calidad supera todas mis expectativas y el envío fue rapidísimo. ¡Muy recomendado!",
    "sentiment": "positive",
    "score": 0.9847,
    "warning": null,
    "info_message": null
  }
}

Campos de la Respuesta

Nivel Raíz:

Campo	Tipo	Descripción
_metadata	object	Información del proveedor y tracking de la petición
response	object	El resultado del análisis de sentimiento

Dentro de _metadata:

Campo	Tipo	Descripción
provider	string	Siempre "ApisDom"
timestamp	string	Timestamp ISO 8601 de la petición
request_id	string	Identificador único de esta petición
service	string	Nombre del servicio ("Sentiment Analysis")
channel	string	Canal de distribución ("ApisDom Platform")

Dentro de response:

Campo	Tipo	Descripción
text	string	El texto que fue analizado
sentiment	string	Sentimiento detectado: positive o negative únicamente (modelo binario)
score	float	Confianza del modelo (0.0 a 1.0). Cuanto más cercano a 1, mayor certeza.
warning	string | null	Aviso si el texto fue truncado (textos muy largos)
info_message	string | null	Información adicional sobre el análisis

⚠️ Importante: El campo sentiment SOLO devolverá positive o negative. Este es un modelo de clasificación binaria entrenado con reseñas de cine (SST-2). No existe clase "neutral" nativa.

---

💻 Ejemplos de Código

Python

import requests

API_URL = "https://apisdom.com/api/v1/sentiment"
API_KEY = "tu_api_key_aqui"

def analizar_sentimiento(texto):
    """
    Analiza el sentimiento de un texto.
    
    Args:
        texto: String con el texto a analizar (máx 5000 caracteres)
    
    Returns:
        dict con _metadata y response conteniendo sentiment, score y detalles
    """
    response = requests.post(
        API_URL,
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={"text": texto}
    )
    
    if response.status_code == 200:
        return response.json()
    elif response.status_code == 402:
        raise Exception("Sin créditos. Consulta planes en apisdom.com/pricing")
    else:
        raise Exception(f"Error: {response.status_code} - {response.text}")

# Ejemplo de uso
resultado = analizar_sentimiento("Me encanta este servicio, funciona perfecto!")

# IMPORTANTE: Acceder a los datos dentro del objeto 'response'
datos = resultado['response']
print(f"Sentimiento: {datos['sentiment']}")
print(f"Confianza: {datos['score']:.2%}")
print(f"Request ID: {resultado['_metadata']['request_id']}")

# Output:
# Sentimiento: positive
# Confianza: 97.32%
# Request ID: sent_1768954704623_4cj49l3

JavaScript / Node.js

const API_URL = 'https://apisdom.com/api/v1/sentiment';
const API_KEY = 'tu_api_key_aqui';

async function analizarSentimiento(texto) {
  /**
   * Analiza el sentimiento de un texto.
   * @param {string} texto - Texto a analizar (máx 5000 caracteres)
   * @returns {Promise<Object>} - Resultado con _metadata y response
   */
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text: texto })
  });

  if (response.status === 402) {
    throw new Error('Sin créditos. Consulta planes en apisdom.com/pricing');
  }

  if (!response.ok) {
    throw new Error(`Error: ${response.status}`);
  }

  return response.json();
}

// Ejemplo de uso
analizarSentimiento('El producto llegó roto y nadie me ayuda')
  .then(resultado => {
    // IMPORTANTE: Acceder al objeto 'response' anidado
    const datos = resultado.response;
    console.log(`Sentimiento: ${datos.sentiment}`);
    console.log(`Confianza: ${(datos.score * 100).toFixed(2)}%`);
    console.log(`Request ID: ${resultado._metadata.request_id}`);
    // Output:
    // Sentimiento: negative
    // Confianza: 94.56%
    // Request ID: sent_1768954704623_4cj49l3
  })
  .catch(console.error);

cURL

curl -X POST "https://apisdom.com/api/v1/sentiment" \
  -H "X-API-Key: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{"text": "La atención al cliente fue excelente, resolvieron mi problema en minutos."}'

# La respuesta incluye _metadata y response anidados:
# {
#   "_metadata": { "provider": "ApisDom", "request_id": "...", ... },
#   "response": { "sentiment": "positive", "score": 0.9847, ... }
# }

PHP

<?php
$api_url = 'https://apisdom.com/api/v1/sentiment';
$api_key = 'tu_api_key_aqui';

function analizarSentimiento($texto) {
    global $api_url, $api_key;
    
    $ch = curl_init($api_url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $api_key,
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode(['text' => $texto])
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 402) {
        throw new Exception('Sin créditos. Consulta planes en apisdom.com/pricing');
    }
    
    return json_decode($response, true);
}

// Ejemplo de uso
$resultado = analizarSentimiento('El servicio técnico tardó mucho pero al final lo solucionaron');

// IMPORTANTE: Acceder al objeto 'response' anidado
$datos = $resultado['response'];
echo "Sentimiento: " . $datos['sentiment'] . "\n";
echo "Confianza: " . number_format($datos['score'] * 100, 2) . "%\n";
echo "Request ID: " . $resultado['_metadata']['request_id'] . "\n";

// Output:
// Sentimiento: positive
// Confianza: 62.18%
// Request ID: sent_1768954704623_4cj49l3
?>

C# / .NET

using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

public class SentimentApiClient
{
    private readonly HttpClient _client;
    private const string API_URL = "https://apisdom.com/api/v1/sentiment";

    public SentimentApiClient(string apiKey)
    {
        _client = new HttpClient();
        _client.DefaultRequestHeaders.Add("X-API-Key", apiKey);
    }

    public async Task<SentimentApiResponse> AnalizarSentimientoAsync(string texto)
    {
        var content = new StringContent(
            JsonSerializer.Serialize(new { text = texto }),
            Encoding.UTF8,
            "application/json"
        );

        var response = await _client.PostAsync(API_URL, content);

        if (response.StatusCode == System.Net.HttpStatusCode.PaymentRequired)
        {
            throw new Exception("Sin créditos. Consulta planes en apisdom.com/pricing");
        }

        response.EnsureSuccessStatusCode();
        
        var json = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<SentimentApiResponse>(json);
    }
}

// IMPORTANTE: La respuesta es ANIDADA - necesitas estas clases
public class SentimentApiResponse
{
    [JsonPropertyName("_metadata")]
    public SentimentMetadata Metadata { get; set; }
    
    [JsonPropertyName("response")]
    public SentimentResult Response { get; set; }
}

public class SentimentMetadata
{
    [JsonPropertyName("provider")]
    public string Provider { get; set; }
    
    [JsonPropertyName("request_id")]
    public string RequestId { get; set; }
    
    [JsonPropertyName("timestamp")]
    public string Timestamp { get; set; }
}

public class SentimentResult
{
    [JsonPropertyName("text")]
    public string Text { get; set; }
    
    [JsonPropertyName("sentiment")]
    public string Sentiment { get; set; }
    
    [JsonPropertyName("score")]
    public double Score { get; set; }
    
    [JsonPropertyName("warning")]
    public string? Warning { get; set; }
    
    [JsonPropertyName("info_message")]
    public string? InfoMessage { get; set; }
}

// Ejemplo de uso
var client = new SentimentApiClient("tu_api_key_aqui");
var apiResponse = await client.AnalizarSentimientoAsync("¡Producto de primera calidad!");

// Acceder a los datos dentro del objeto Response
Console.WriteLine($"Sentimiento: {apiResponse.Response.Sentiment}");
Console.WriteLine($"Confianza: {apiResponse.Response.Score:P2}");
Console.WriteLine($"Request ID: {apiResponse.Metadata.RequestId}");

// Output:
// Sentimiento: positive
// Confianza: 99.99%
// Request ID: sent_1768954865380_hh3t7b1

---

📊 Casos de Uso Prácticos

1. Análisis de Reseñas de Productos

reseñas = [
    "Excelente relación calidad-precio",
    "Llegó tarde y con el embalaje dañado",
    "Hace lo que promete, nada más",
]

for reseña in reseñas:
    api_result = analizar_sentimiento(reseña)
    # Acceder al objeto 'response' anidado
    datos = api_result['response']
    print(f"'{reseña[:30]}...' → {datos['sentiment']} ({datos['score']:.0%})")

# Output (nota: el modelo tiende a alta confianza):
# 'Excelente relación calidad-pr...' → positive (99%)
# 'Llegó tarde y con el embalaje...' → negative (99%)
# 'Hace lo que promete, nada más...' → positive (87%)
# ⚠️ Nota: textos "neutros" suelen clasificarse como positive debido al modelo binario

2. Clasificación Automática de Tickets de Soporte

def priorizar_ticket(mensaje):
    """Asigna prioridad según el sentimiento del cliente."""
    api_result = analizar_sentimiento(mensaje)
    # Acceder al objeto 'response' anidado
    resultado = api_result['response']
    
    if resultado['sentiment'] == 'negative' and resultado['score'] > 0.8:
        return "🔴 URGENTE - Cliente muy insatisfecho"
    elif resultado['sentiment'] == 'negative':
        return "🟡 ALTA - Cliente insatisfecho"
    else:
        return "🟢 NORMAL"

ticket = "Llevo 3 días esperando respuesta y nadie me ayuda. Es inaceptable."
print(priorizar_ticket(ticket))
# Output: 🔴 URGENTE - Cliente muy insatisfecho

3. Dashboard de Satisfacción en Tiempo Real

async function actualizarDashboard(comentarios) {
  const apiResults = await Promise.all(
    comentarios.map(c => analizarSentimiento(c))
  );
  
  // Extraer el objeto 'response' de cada resultado de la API
  const resultados = apiResults.map(r => r.response);
  
  const stats = {
    positivos: resultados.filter(r => r.sentiment === 'positive').length,
    negativos: resultados.filter(r => r.sentiment === 'negative').length,
    promedioConfianza: resultados.reduce((a, b) => a + b.score, 0) / resultados.length
  };
  
  console.log('📊 Resumen de Satisfacción:');
  console.log(`   ✅ Positivos: ${stats.positivos}`);
  console.log(`   ❌ Negativos: ${stats.negativos}`);
  console.log(`   📊 Confianza promedio: ${(stats.promedioConfianza * 100).toFixed(1)}%`);
  
  return stats;
}

---

⚠️ Códigos de Error

Código	Significado	Solución
400	Texto inválido (vacío o muy largo)	Asegúrate de enviar entre 1 y 5000 caracteres
401	API Key inválida	Verifica tu API Key en el dashboard
402	Sin créditos disponibles	Consulta planes en apisdom.com/pricing
429	Límite de peticiones excedido	Espera antes de reintentar (ver headers de rate limit)
500	Error interno del servidor	Reintenta en unos segundos. Si persiste, contacta soporte

---

🔬 Transparencia Técnica

Política de ApisDom: Creemos que los desarrolladores merecen saber exactamente cómo funcionan las APIs que usan. Esta sección documenta los detalles técnicos verificados directamente del código fuente.

Cómo Funciona Internamente

Tu texto → Tokenización (DistilBERT) → Inferencia → Normalización → Respuesta
         ↓                           ↓             ↓
         512 tokens máx          CPU-bound      POSITIVE → positive
                                 (threadpool)   NEGATIVE → negative

Detalles Verificados del Código

Aspecto	Valor Real	Archivo Fuente
Modelo	distilbert-base-uncased-finetuned-sst-2-english	sentiment_service.py
Pipeline	sentiment-analysis de HuggingFace	sentiment_service.py
Truncamiento	512 tokens (automático)	sentiment_service.py línea 47
Labels originales	POSITIVE, NEGATIVE → normalizados a minúsculas	sentiment_service.py líneas 64-67
Clases de salida	SOLO BINARIO - positive o negative (sin neutral)	Arquitectura del modelo
Ejecución	run_in_threadpool (no bloquea async)	sentiment_service.py línea 51

⚠️ Importante: No Existe Clase Neutral Nativa

Este modelo es binario (positive/negative únicamente). Fue entrenado con el dataset SST-2 (Stanford Sentiment Treebank) que solo contiene reseñas de películas positivas y negativas. El modelo NO tiene clase "neutral".

Comportamiento observado con texto neutral:

• Input: "El clima está agradable hoy" (objetivamente neutral)
• Output: {"sentiment": "positive", "score": 0.9965}
• El modelo fuerza una clasificación y tiende a ser muy confiado incluso con texto ambiguo

Esta es una característica conocida de las redes neuronales llamada "sobreconfianza" (ver: On Calibration of Modern Neural Networks, ICML 2017).

---

📝 Notas Importantes

Sobre el Modelo DistilBERT

El modelo distilbert-base-uncased-finetuned-sst-2-english está entrenado para textos en inglés y ofrece rendimiento óptimo en este idioma.

Limitaciones conocidas:

• ⚠️ Modelo solo binario: Devuelve positive o negative - NO existe clase neutral
• El modelo fue entrenado con reseñas de cine (dataset SST-2, ~11,855 ejemplos)
• Puede no generalizar bien a otros dominios (redes sociales, texto técnico, etc.)
• Sarcasmo e ironía pueden ser mal interpretados
• Sobreconfianza: Los scores tienden a ser muy altos (>95%) incluso para texto ambiguo
• Texto neutral/fáctico típicamente se clasifica como "positive" con alta confianza

Mejores casos de uso:

• Reseñas de productos (similar a datos de entrenamiento)
• Feedback de clientes con sentimiento claro
• Clasificación de tickets de soporte (positivo vs negativo)

No recomendado para:

• Detectar declaraciones verdaderamente neutrales/fácticas
• Sentimiento financiero o de noticias (dominio diferente)
• Análisis emocional con matices

Sobre el Truncamiento de Texto

El modelo BERT tiene un límite de 512 tokens (~400 palabras). Si tu texto es más largo:

• Se analizarán los primeros 512 tokens
• Recibirás un warning en la respuesta indicando el truncamiento
• El análisis seguirá siendo válido pero parcial

Recomendación: Para textos largos, divídelos en párrafos y analiza cada uno por separado.

Sobre el Tiempo de Respuesta

La primera petición tras inactividad puede tardar ~20 segundos (cold start). Una vez activo, las respuestas son < 500ms.

---

💬 ¿Necesitas Ayuda?

📧 soporte@apisdom.com

---

⚖️ Aviso Legal

Nota de Transparencia: Esta API utiliza el modelo de código abierto distilbert-base-uncased-finetuned-sst-2-english de Hugging Face. Los resultados reflejan las capacidades y limitaciones inherentes del modelo, el cual fue entrenado exclusivamente con el dataset SST-2 (críticas de cine en inglés). ApisDom no modifica ni re-entrena el modelo base; proporcionamos una interfaz optimizada para su consumo vía API.

Los scores de confianza (0.0-1.0) representan la certeza del modelo, no una medida absoluta de precisión. Para aplicaciones críticas, se recomienda validación humana adicional.

Última actualización de documentación: Enero 2026

ApisDom · Inteligencia Artificial Transparente

Esta API utiliza Chronos-2 (modelo pre-entrenado de Amazon Science para forecasting zero-shot) para generar predicciones precisas de series temporales con intervalos de confianza del 90%.

⚠️ Limitaciones Conocidas (Leer antes de usar)

1. Modelo Pre-entrenado: Chronos-2 es zero-shot (no entrena en cada petición). Los tiempos de respuesta son rápidos (1-5 segundos).
2. Datos Mínimos Requeridos: Se requieren al menos 10 puntos de datos. Para predicciones confiables, se recomiendan 30+ puntos.
3. Horizonte Máximo: Predicciones limitadas a 365 períodos en el futuro.
4. Detección de Estacionalidad: Automáticamente aprendida del contexto histórico (sin configuración manual).
5. Validación MAPE: Usa el parámetro validate_periods para obtener MAPE real mediante backtesting.

Casos de Uso Recomendados

🧩 Producto en Producción (Referencia Real)

Viral
Plataforma pública de analítica predictiva construida sobre esta API.
Muestra resultados reales de forecasting, intervalos de confianza (lower/upper) y ausencia de maquillaje de métricas.

🔗 https://viral.apisdom.com

✅ Pronóstico de ventas e ingresos
✅ Predicción de tráfico web
✅ Gestión de inventario y planificación de demanda
✅ Planificación de recursos y capacidad
✅ Proyecciones de presupuesto

Casos de Uso NO Recomendados

❌ Predicción de precios de bolsa o criptomonedas (muy volátiles)
❌ Extrapolación de un solo punto de datos
❌ Datos sin patrón temporal

---

📍 Información General

Propiedad	Valor
URL Base	https://apisdom.com/api/v1
Método	POST
Autenticación	API Key (Header X-API-Key)
Tipo de Crédito	prediction
Coste por llamada	1 crédito
Motor IA	Chronos-2 (Amazon Science zero-shot forecasting)
Límites de datos	Mínimo 10, máximo 5000 puntos de datos
Horizonte máximo	365 períodos
Intervalos de confianza	90% (quantiles 5% y 95%)

📊 Headers Informativos

La API devuelve headers que te permiten controlar tu consumo:

Header	Descripción
X-RateLimit-Limit	Tu límite de peticiones por minuto
X-RateLimit-Remaining	Peticiones restantes en la ventana actual
Retry-After	Segundos a esperar si recibes 429

❄️ Cold Start

Para optimizar costes, los microservicios de IA escalan a cero cuando no hay actividad.

💡 Nota: La primera petición puede tardar más de lo normal (hasta 20-30 segundos) mientras el servicio arranca. Las peticiones siguientes serán más rápidas (2-15 segundos dependiendo del tamaño de datos) mientras el servicio permanezca activo.

💳 Planes y Precios

Consulta los planes disponibles y precios actualizados en: apisdom.com/pricing

---

🔐 Autenticación

Todas las peticiones requieren tu API Key en el header X-API-Key:

X-API-Key: tu_api_key_aqui

Puedes obtener tu API Key desde el panel de usuario en apisdom.com/dashboard.

---

🏥 Health Check

Endpoint para verificar que el servicio está disponible. No requiere autenticación.

GET https://apisdom.com/api/health/predicciones

Response (200 OK)

{
  "status": "healthy",
  "model": "chronos-2",
  "service": "prediction"
}

---

📥 Endpoint: Generar Predicción

POST https://apisdom.com/api/v1/predictions

Request Body

Campo	Tipo	Requerido	Default	Descripción
dates	string[]	✅ Si	-	Lista de fechas en formato YYYY-MM-DD. Minimo 10, maximo 5000.
values	float[]	✅ Si	-	Lista de valores numericos correspondientes. Debe tener la misma longitud que dates.
periods	int	❔ Opcional	7	Numero de periodos futuros a predecir. Minimo 1, maximo 365.
validate_periods	int	❔ Opcional	null	Periodos para backtesting MAPE (1-30). Si se proporciona, retorna MAPE real.
is_open	bool[]	❔ Opcional	null	Indica si el negocio estaba operativo cada dia. Debe tener la misma longitud que dates. Si se proporciona, los dias con false se tratan como datos ausentes.

Validaciones Importantes

• dates y values deben tener exactamente la misma longitud
• Minimo 10 puntos de datos (para contexto historico suficiente)
• Maximo 5000 puntos de datos
• Fechas deben estar en orden cronologico
• Los valores pueden ser enteros o decimales
• Si se proporciona is_open, debe tener exactamente la misma longitud que dates

Representacion de datos operativos (is_open)

El campo is_open es opcional y permite distinguir entre dias sin actividad (negocio cerrado) y dias con ventas reales de cero.

Si NO envias is_open: Todo funciona como siempre. Los valores 0 se interpretan como datos reales. No necesitas cambiar nada en tu integracion actual.

Si envias is_open: Puedes indicar exactamente que dias el negocio estaba operativo.

is_open	value	Interpretacion	Tratamiento
false	cualquier valor	Negocio cerrado	Ignorado (NaN)
true	numero	Negocio abierto	Se usa el valor
no definido	numero	Comportamiento por defecto	Se usa el valor

Recomendacion para mayor precision:

• Usa is_open: false cuando el negocio no podia vender (cerrado, festivo, inventario)
• Usa value: 0 con is_open: true cuando el negocio estaba abierto pero no hubo ventas
• Si no necesitas esta distincion, simplemente no envies is_open

Ejemplo con is_open:

{
  "dates": ["2026-04-07", "2026-04-08", "2026-04-09", "2026-04-10"],
  "values": [5200, 0, 0, 4800],
  "is_open": [true, false, true, true],
  "periods": 7
}

En este ejemplo:

• 7 abril: 5200 ventas (abierto, dato real)
• 8 abril: 0 (cerrado, se ignora en la prediccion)
• 9 abril: 0 (abierto, 0 ventas reales, dato real)
• 10 abril: 4800 ventas (abierto, dato real)

Error de validacion: Si is_open tiene longitud diferente a dates:

{
  "detail": "is_open debe tener la misma longitud que dates. dates: 91, is_open: 10"
}

Codigo HTTP: 422 Unprocessable Entity

Ejemplo de Request

{
  "dates": [
    "2026-01-01", "2026-01-02", "2026-01-03", "2026-01-04", "2026-01-05",
    "2026-01-06", "2026-01-07", "2026-01-08", "2026-01-09", "2026-01-10",
    "2026-01-11", "2026-01-12", "2026-01-13", "2026-01-14", "2026-01-15"
  ],
  "values": [
    120.5, 135.2, 128.7, 142.1, 155.3,
    148.9, 160.0, 172.4, 165.8, 180.2,
    175.6, 188.9, 195.3, 201.7, 210.5
  ],
  "periods": 7
}

Response Exitosa (200 OK)

La respuesta es ANIDADA con dos objetos principales: _metadata y response.

{
  "_metadata": {
    "provider": "ApisDom",
    "tagline": "Inteligencia artificial transparente",
    "website": "https://apisdom.com",
    "timestamp": "2026-01-21T12:30:00.000Z",
    "service": "Time Series Prediction",
    "channel": "ApisDom Platform",
    "request_id": "pred_1768954704623_abc123",
    "documentation": "https://apisdom.com/documentacion"
  },
  "response": {
    "predictions": [
      {"date": "2026-01-16", "value": 218.34, "lower": 196.51, "upper": 240.17},
      {"date": "2026-01-17", "value": 225.12, "lower": 202.61, "upper": 247.63},
      {"date": "2026-01-18", "value": 231.89, "lower": 208.70, "upper": 255.08},
      {"date": "2026-01-19", "value": 238.45, "lower": 214.61, "upper": 262.30},
      {"date": "2026-01-20", "value": 245.01, "lower": 220.51, "upper": 269.51},
      {"date": "2026-01-21", "value": 251.78, "lower": 226.60, "upper": 276.96},
      {"date": "2026-01-22", "value": 258.34, "lower": 232.51, "upper": 284.17}
    ],
    "mape": null,
    "quality_warning": null,
    "info_message": null
  }
}

Campos de la Respuesta

Nivel Raíz:

Campo	Tipo	Descripción
_metadata	object	Información del proveedor y tracking de la petición
response	object	El resultado de la predicción

Dentro de _metadata:

Campo	Tipo	Descripción
provider	string	Siempre "ApisDom"
timestamp	string	Timestamp ISO 8601 de la petición
request_id	string	Identificador único de esta petición
service	string	Nombre del servicio ("Time Series Prediction")
channel	string	Canal de distribución ("ApisDom Platform")

Dentro de response:

Campo	Tipo	Descripción
predictions	array	Lista de predicciones con fecha y valores
predictions[].date	string	Fecha predicha en formato YYYY-MM-DD
predictions[].value	float	Valor predicho (mediana, percentil 50%)
predictions[].lower	float	Límite inferior del intervalo de confianza 90% (percentil 5%)
predictions[].upper	float	Límite superior del intervalo de confianza 90% (percentil 95%)
mape	float | null	Mean Absolute Percentage Error. Retorna valor REAL solo si se proporcionó validate_periods, de lo contrario null.
quality_warning	string | null	Aviso si hay datos insuficientes para validación MAPE (requiere parámetro validate_periods)
info_message	string | null	Para usuarios free tier: aviso de cold start. null para planes de pago.

Sobre intervalos de confianza: Los campos lower y upper representan intervalos de confianza del 90% calculados mediante regresión cuantílica con Chronos-2 (percentiles 5% y 95%). Esto significa que hay un 90% de probabilidad de que el valor real caiga dentro del rango [lower, upper].

Interpretando el MAPE

El MAPE (Mean Absolute Percentage Error) se devuelve como valor decimal (0.0 a 1.0):

MAPE (valor)	Error (%)	Interpretación	Confiabilidad
< 0.05	< 5%	Excelente	⭐⭐⭐⭐⭐ Muy alta
0.05-0.10	5-10%	Bueno	⭐⭐⭐⭐ Alta
0.10-0.20	10-20%	Aceptable	⭐⭐⭐ Media
0.20-0.40	20-40%	Regular	⭐⭐ Baja
> 0.40	> 40%	Deficiente	⭐ Muy baja - Considera usar más datos

⚠️ Importante: El MAPE solo se calcula cuando proporcionas validate_periods. Sin él, mape será null. Para obtener MAPE real, usa backtesting:

{
  "dates": ["2026-01-01", "2026-01-02", ..., "2026-01-30"],
  "values": [120.5, 135.2, ..., 210.5],
  "periods": 7,
  "validate_periods": 5
}

---

💻 Ejemplos de Código

Python

import requests
from typing import List

API_URL = "https://apisdom.com/api/v1/predictions"
API_KEY = "tu_api_key_aqui"

def predecir(fechas: List[str], valores: List[float], periodos: int = 7) -> dict:
    """
    Genera predicciones para una serie temporal.
    
    Args:
        fechas: Lista de fechas en formato 'YYYY-MM-DD'
        valores: Lista de valores numéricos
        periodos: Número de periodos futuros a predecir (1-365)
    
    Returns:
        dict con _metadata y response conteniendo predictions y mape
    """
    if len(fechas) != len(valores):
        raise ValueError("fechas y valores deben tener la misma longitud")
    if len(fechas) < 10:
        raise ValueError("Se necesitan al menos 10 puntos de datos")
    if not 1 <= periodos <= 365:
        raise ValueError("periodos debe estar entre 1 y 365")
    
    response = requests.post(
        API_URL,
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={
            "dates": fechas,
            "values": valores,
            "periods": periodos
        }
    )
    
    if response.status_code == 200:
        return response.json()
    elif response.status_code == 402:
        raise Exception("Sin créditos. Consulta planes en apisdom.com/pricing")
    else:
        raise Exception(f"Error: {response.status_code} - {response.text}")

# Ejemplo de uso
fechas = [
    "2026-01-01", "2026-01-02", "2026-01-03", "2026-01-04", "2026-01-05",
    "2026-01-06", "2026-01-07", "2026-01-08", "2026-01-09", "2026-01-10",
    "2026-01-11", "2026-01-12", "2026-01-13", "2026-01-14", "2026-01-15"
]
valores = [120.5, 135.2, 128.7, 142.1, 155.3, 148.9, 160.0, 172.4, 165.8, 180.2, 175.6, 188.9, 195.3, 201.7, 210.5]

resultado = predecir(fechas, valores, periodos=7)

# IMPORTANTE: Acceder a los datos dentro del objeto 'response'
datos = resultado['response']
if datos['mape'] is not None:
    print(f"MAPE: {datos['mape']:.1%}")
else:
    print("MAPE: No calculado (usa validate_periods para obtener MAPE real)")
print(f"Request ID: {resultado['_metadata']['request_id']}")
print("\nPredicciones:")
for pred in datos['predictions']:
    print(f"  {pred['date']}: {pred['value']:.2f} [{pred['lower']:.2f} - {pred['upper']:.2f}]")

# Output (sin validate_periods):
# MAPE: No calculado (usa validate_periods para obtener MAPE real)
# Request ID: pred_1768954704623_abc123
# 
# Predicciones:
#   2026-01-16: 218.34 [196.51 - 240.17]
#   2026-01-17: 225.12 [202.61 - 247.63]
#   ...

JavaScript / Node.js

const API_URL = 'https://apisdom.com/api/v1/predictions';
const API_KEY = 'tu_api_key_aqui';

async function predecir(fechas, valores, periodos = 7) {
  /**
   * Genera predicciones para una serie temporal.
   * @param {string[]} fechas - Lista de fechas 'YYYY-MM-DD'
   * @param {number[]} valores - Lista de valores numéricos
   * @param {number} periodos - Periodos a predecir (1-365)
   * @returns {Promise<Object>} - Resultado con _metadata y response
   */
  if (fechas.length !== valores.length) {
    throw new Error('fechas y valores deben tener la misma longitud');
  }
  if (fechas.length < 10) {
    throw new Error('Se necesitan al menos 10 puntos de datos');
  }
  if (periodos < 1 || periodos > 365) {
    throw new Error('periodos debe estar entre 1 y 365');
  }

  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ dates: fechas, values: valores, periods: periodos })
  });

  if (response.status === 402) {
    throw new Error('Sin créditos. Consulta planes en apisdom.com/pricing');
  }

  if (!response.ok) {
    throw new Error(`Error: ${response.status}`);
  }

  return response.json();
}

// Ejemplo de uso
const fechas = [
  '2026-01-01', '2026-01-02', '2026-01-03', '2026-01-04', '2026-01-05',
  '2026-01-06', '2026-01-07', '2026-01-08', '2026-01-09', '2026-01-10',
  '2026-01-11', '2026-01-12', '2026-01-13', '2026-01-14', '2026-01-15'
];
const valores = [120.5, 135.2, 128.7, 142.1, 155.3, 148.9, 160.0, 172.4, 165.8, 180.2, 175.6, 188.9, 195.3, 201.7, 210.5];

predecir(fechas, valores, 7)
  .then(resultado => {
    // IMPORTANTE: Acceder al objeto 'response' anidado
    const datos = resultado.response;
    if (datos.mape !== null) {
      console.log(`MAPE: ${(datos.mape * 100).toFixed(1)}%`);
    } else {
      console.log('MAPE: No calculado (usa validate_periods para obtener MAPE real)');
    }
    console.log(`Request ID: ${resultado._metadata.request_id}`);
    console.log('\nPredicciones:');
    datos.predictions.forEach(p => {
      console.log(`  ${p.date}: ${p.value.toFixed(2)} [${p.lower.toFixed(2)} - ${p.upper.toFixed(2)}]`);
    });
  })
  .catch(console.error);

cURL

curl -X POST "https://apisdom.com/api/v1/predictions" \
  -H "X-API-Key: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "dates": [
      "2026-01-01", "2026-01-02", "2026-01-03", "2026-01-04", "2026-01-05",
      "2026-01-06", "2026-01-07", "2026-01-08", "2026-01-09", "2026-01-10",
      "2026-01-11", "2026-01-12", "2026-01-13", "2026-01-14", "2026-01-15"
    ],
    "values": [120.5, 135.2, 128.7, 142.1, 155.3, 148.9, 160.0, 172.4, 165.8, 180.2, 175.6, 188.9, 195.3, 201.7, 210.5],
    "periods": 7
  }'

# La respuesta incluye _metadata y response anidados:
# {
#   "_metadata": { "provider": "ApisDom", "request_id": "...", ... },
#   "response": { "predictions": [...], "mape": null, ... }
# }

PHP

<?php
$api_url = 'https://apisdom.com/api/v1/predictions';
$api_key = 'tu_api_key_aqui';

function predecir($fechas, $valores, $periodos = 7) {
    global $api_url, $api_key;
    
    // Validaciones
    if (count($fechas) !== count($valores)) {
        throw new Exception('fechas y valores deben tener la misma longitud');
    }
    if (count($fechas) < 10) {
        throw new Exception('Se necesitan al menos 10 puntos de datos');
    }
    if ($periodos < 1 || $periodos > 365) {
        throw new Exception('periodos debe estar entre 1 y 365');
    }
    
    $ch = curl_init($api_url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $api_key,
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'dates' => $fechas,
            'values' => $valores,
            'periods' => $periodos
        ])
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 402) {
        throw new Exception('Sin créditos. Consulta planes en apisdom.com/pricing');
    }
    
    return json_decode($response, true);
}

// Ejemplo de uso
$fechas = [
    '2026-01-01', '2026-01-02', '2026-01-03', '2026-01-04', '2026-01-05',
    '2026-01-06', '2026-01-07', '2026-01-08', '2026-01-09', '2026-01-10',
    '2026-01-11', '2026-01-12', '2026-01-13', '2026-01-14', '2026-01-15'
];
$valores = [120.5, 135.2, 128.7, 142.1, 155.3, 148.9, 160.0, 172.4, 165.8, 180.2, 175.6, 188.9, 195.3, 201.7, 210.5];

try {
    $resultado = predecir($fechas, $valores, 7);
    
    // IMPORTANTE: Acceder al objeto 'response' anidado
    $datos = $resultado['response'];
    if ($datos['mape'] !== null) {
        echo "MAPE: " . number_format($datos['mape'] * 100, 1) . "%\n";
    } else {
        echo "MAPE: No calculado (usa validate_periods para obtener MAPE real)\n";
    }
    echo "Request ID: " . $resultado['_metadata']['request_id'] . "\n\n";
    
    echo "Predicciones:\n";
    foreach ($datos['predictions'] as $pred) {
        echo "  {$pred['date']}: " . number_format($pred['value'], 2) . 
             " [" . number_format($pred['lower'], 2) . " - " . number_format($pred['upper'], 2) . "]\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

C# / .NET

using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

public class PredictionApiClient
{
    private readonly HttpClient _client;
    private const string API_URL = "https://apisdom.com/api/v1/predictions";

    public PredictionApiClient(string apiKey)
    {
        _client = new HttpClient();
        _client.DefaultRequestHeaders.Add("X-API-Key", apiKey);
    }

    public async Task<PredictionApiResponse> PredecirAsync(
        List<string> fechas, 
        List<double> valores, 
        int periodos = 7)
    {
        // Validaciones
        if (fechas.Count != valores.Count)
            throw new ArgumentException("fechas y valores deben tener la misma longitud");
        if (fechas.Count < 10)
            throw new ArgumentException("Se necesitan al menos 10 puntos de datos");
        if (periodos < 1 || periodos > 365)
            throw new ArgumentException("periodos debe estar entre 1 y 365");

        var request = new { dates = fechas, values = valores, periods = periodos };
        var content = new StringContent(
            JsonSerializer.Serialize(request),
            Encoding.UTF8,
            "application/json"
        );

        var response = await _client.PostAsync(API_URL, content);

        if (response.StatusCode == System.Net.HttpStatusCode.PaymentRequired)
        {
            throw new Exception("Sin créditos. Consulta planes en apisdom.com/pricing");
        }

        response.EnsureSuccessStatusCode();
        
        var json = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<PredictionApiResponse>(json);
    }
}

// IMPORTANTE: La respuesta es ANIDADA - necesitas estas clases
public class PredictionApiResponse
{
    [JsonPropertyName("_metadata")]
    public PredictionMetadata Metadata { get; set; }
    
    [JsonPropertyName("response")]
    public PredictionResult Response { get; set; }
}

public class PredictionMetadata
{
    [JsonPropertyName("provider")]
    public string Provider { get; set; }
    
    [JsonPropertyName("request_id")]
    public string RequestId { get; set; }
    
    [JsonPropertyName("timestamp")]
    public string Timestamp { get; set; }
}

public class PredictionResult
{
    [JsonPropertyName("predictions")]
    public List<Prediction> Predictions { get; set; }
    
    [JsonPropertyName("mape")]
    public double? Mape { get; set; }  // Nullable - solo se establece si se proporcionó validate_periods
    
    [JsonPropertyName("quality_warning")]
    public string? QualityWarning { get; set; }
    
    [JsonPropertyName("info_message")]
    public string? InfoMessage { get; set; }
}

public class Prediction
{
    [JsonPropertyName("date")]
    public string Date { get; set; }
    
    [JsonPropertyName("value")]
    public double Value { get; set; }
    
    [JsonPropertyName("lower")]
    public double Lower { get; set; }
    
    [JsonPropertyName("upper")]
    public double Upper { get; set; }
}

// Ejemplo de uso
var client = new PredictionApiClient("tu_api_key_aqui");

var fechas = new List<string> {
    "2026-01-01", "2026-01-02", "2026-01-03", "2026-01-04", "2026-01-05",
    "2026-01-06", "2026-01-07", "2026-01-08", "2026-01-09", "2026-01-10",
    "2026-01-11", "2026-01-12", "2026-01-13", "2026-01-14", "2026-01-15"
};
var valores = new List<double> { 120.5, 135.2, 128.7, 142.1, 155.3, 148.9, 160.0, 172.4, 165.8, 180.2, 175.6, 188.9, 195.3, 201.7, 210.5 };

var apiResponse = await client.PredecirAsync(fechas, valores, 7);

// Acceder a los datos dentro del objeto Response
if (apiResponse.Response.Mape.HasValue)
    Console.WriteLine($"MAPE: {apiResponse.Response.Mape:P1}");
else
    Console.WriteLine("MAPE: No calculado (usa validate_periods para obtener MAPE real)");
Console.WriteLine($"Request ID: {apiResponse.Metadata.RequestId}");
Console.WriteLine("\nPredicciones:");
foreach (var pred in apiResponse.Response.Predictions)
{
    Console.WriteLine($"  {pred.Date}: {pred.Value:N2} [{pred.Lower:N2} - {pred.Upper:N2}]");
}

---

📊 Casos de Uso Prácticos

1. Sistema de Pronóstico de Ventas

def pronosticar_ventas(datos_historicos, dias_adelante=30):
    """
    Genera pronóstico de ventas con análisis de tendencia.
    """
    api_result = predecir(
        datos_historicos['fechas'],
        datos_historicos['valores'],
        dias_adelante
    )
    
    # Acceder al objeto 'response' anidado
    datos = api_result['response']
    
    # Calcular métricas
    valores_historicos = datos_historicos['valores']
    valores_predichos = [p['value'] for p in datos['predictions']]
    
    promedio_historico = sum(valores_historicos) / len(valores_historicos)
    promedio_predicho = sum(valores_predichos) / len(valores_predichos)
    
    cambio_porcentaje = ((promedio_predicho - promedio_historico) / promedio_historico) * 100
    
    # Detectar tendencia
    if cambio_porcentaje > 10:
        tendencia = "📈 CRECIMIENTO FUERTE"
    elif cambio_porcentaje > 3:
        tendencia = "📈 Crecimiento moderado"
    elif cambio_porcentaje > -3:
        tendencia = "➡️ Estable"
    elif cambio_porcentaje > -10:
        tendencia = "📉 Declive moderado"
    else:
        tendencia = "📉 DECLIVE FUERTE"
    
    return {
        'predicciones': datos['predictions'],
        'mape': datos['mape'],
        'analisis': {
            'tendencia': tendencia,
            'cambio_porcentaje': f"{cambio_porcentaje:+.1f}%",
            'total_proyectado': sum(valores_predichos)
        }
    }

2. Predicción de Inventario con Alertas

async function predecirInventario(productId, stockActual, historialVentas) {
  /**
   * Predice cuándo se agotará el inventario y recomienda reposición.
   */
  const apiResult = await predecir(
    historialVentas.fechas,
    historialVentas.valores,
    30  // Predecir 30 días
  );
  
  // Acceder al objeto 'response' anidado
  const datos = apiResult.response;
  
  // Simular consumo de inventario
  let stockRestante = stockActual;
  let diasHastaAgotarse = null;
  
  for (let i = 0; i < datos.predictions.length; i++) {
    const pred = datos.predictions[i];
    stockRestante -= pred.value;
    
    if (stockRestante <= 0 && diasHastaAgotarse === null) {
      diasHastaAgotarse = i + 1;
    }
  }
  
  // Calcular nivel de alerta
  let alerta;
  if (diasHastaAgotarse !== null && diasHastaAgotarse <= 7) {
    alerta = { nivel: 'CRITICO', emoji: '🔴', mensaje: '¡Reponer inmediatamente!' };
  } else if (diasHastaAgotarse !== null && diasHastaAgotarse <= 14) {
    alerta = { nivel: 'ALTO', emoji: '🟠', mensaje: 'Planificar reposición esta semana' };
  } else if (diasHastaAgotarse !== null && diasHastaAgotarse <= 21) {
    alerta = { nivel: 'MEDIO', emoji: '🟡', mensaje: 'Considerar reposición pronto' };
  } else {
    alerta = { nivel: 'BAJO', emoji: '🟢', mensaje: 'Nivel de stock saludable' };
  }
  
  return { productId, stockActual, diasHastaAgotarse, alerta };
}

3. Dashboard Multi-Métrica

def crear_dashboard_metricas(metricas_historicas, nombres_metricas):
    """
    Crea un dashboard con múltiples métricas y sus proyecciones.
    """
    resultados = []
    
    for nombre, datos in zip(nombres_metricas, metricas_historicas.values()):
        try:
            api_result = predecir(datos['fechas'], datos['valores'], 7)
            pred_data = api_result['response']  # Acceder al response anidado
            
            historico = datos['valores']
            proyectado = [p['value'] for p in pred_data['predictions']]
            
            resultados.append({
                'Métrica': nombre,
                'Promedio Histórico': f"{sum(historico)/len(historico):,.1f}",
                'Proyección 7 días': f"{sum(proyectado)/7:,.1f}",
                'MAPE': f"{pred_data['mape']:.3f}" if pred_data['mape'] is not None else "N/A",
                'Estado': '⚠️' if pred_data.get('quality_warning') else '✅'
            })
        except Exception as e:
            resultados.append({'Métrica': nombre, 'Error': str(e)})
    
    return resultados

---

⚠️ Códigos de Error

Código	Significado	Solución
422	Datos invalidos	Verifica: minimo 10 puntos, fechas=valores longitud, periodos 1-365, formato fecha YYYY-MM-DD, is_open misma longitud que dates
401	API Key inválida	Verifica tu API Key en el dashboard
402	Sin créditos disponibles	Consulta planes en apisdom.com/pricing
429	Límite de peticiones excedido	Espera antes de reintentar (ver header Retry-After)
500	Error interno del servidor	Reintenta en unos segundos. Si persiste, contacta soporte

---

🔬 Transparencia Técnica

Política de ApisDom: Creemos que los desarrolladores merecen saber exactamente cómo funcionan las APIs que usan. Esta sección documenta los detalles técnicos verificados directamente del código fuente.

Cómo Funciona Internamente

Tus datos → is_open? → DataFrame + covariables → Inferencia Chronos-2 → Prediccion → MAPE
          ↓            ↓                          ↓                       ↓             ↓
          Si is_open   pandas DataFrame           modelo pre-entrenado    predict_df    backtesting
          false→NaN    + day_of_week              (no entrena)            con           validacion
                       + is_weekend                                       covariables

Detalles Verificados del Código

Aspecto	Valor Real	Archivo Fuente
Motor	Chronos-2 (Amazon Science)	prediction_service.py
Tipo	Zero-shot (pre-entrenado, no entrena por petición)	prediction_service.py
Modelo	amazon/chronos-2 (120M params)	prediction_service.py
Librería	chronos-forecasting==2.2.2	requirements.txt
Método de inferencia	predict_df (con covariables nativas)	prediction_service.py
Covariables	day_of_week (0-6), is_weekend (0/1) — known future covariates	prediction_service.py
Intervalos de confianza	quantile_levels=[0.05, 0.5, 0.95] (90% confianza)	prediction_service.py
Postprocesamiento	Valores negativos clamped a 0 (revenue no puede ser negativo)	prediction_service.py
Dispositivo	CPU (CUDA si disponible)	prediction_service.py
Cálculo MAPE	Backtesting real (via validate_periods)	prediction_service.py

Cálculo del MAPE

# Código real (prediction_service.py) - Verificado 27 marzo 2026
def _calculate_mape(self, actual: list[float], predicted: list[float]) -> float | None:
    """
    MAPE = (1/n) × Σ |actual - predicted| / |actual|
    """
    if len(actual) != len(predicted):
        return None

    # Filtrar valores donde actual != 0 (evitar división por cero)
    valid_pairs = [(a, p) for a, p in zip(actual, predicted, strict=True) if a != 0]

    if not valid_pairs:
        return None

    errors = [abs(a - p) / abs(a) for a, p in valid_pairs]
    return round(sum(errors) / len(errors), 4)

Importante: El MAPE se calcula via backtesting cuando se proporciona validate_periods. La API reserva los últimos N valores como ground truth, predice usando el resto, y compara.

Implicacion: Los valores 0 en el periodo de validacion se excluyen del calculo MAPE (para evitar division por cero). Si TODOS los valores de validacion son 0, el MAPE sera null. Si solo algunos son 0, el MAPE se calcula con los restantes. Si usas is_open: false para dias cerrados, esos dias tambien se excluyen del MAPE.

Por Qué lower y upper Pueden Ser Diferentes a value

Los intervalos de confianza están implementados mediante regresión cuantílica:

# Código real (prediction_service.py) - Verificado 27 marzo 2026
pred_df = pipeline.predict_df(
    context_df,                              # DataFrame histórico con covariables
    future_df=future_df,                     # DataFrame futuro con covariables
    prediction_length=periods,
    quantile_levels=[0.05, 0.5, 0.95],      # Genera percentiles 5%, 50% y 95%
    id_column="item_id",
    timestamp_column="timestamp",
    target="target",
)

# Extrae valores del DataFrame de salida:
value = max(0.0, row["predictions"])  # Mediana (clamped >= 0)
lower = max(0.0, row["0.05"])        # Percentil 5% (clamped >= 0)
upper = max(0.0, row["0.95"])        # Percentil 95% (clamped >= 0)

Interpretación de tu resultado:

{
  "date": "2026-01-18",
  "value": 322.15,  // Valor más probable (mediana)
  "lower": 275.44,  // 5% prob. de estar por debajo
  "upper": 450.71   // 5% prob. de estar por encima
}

Esto significa: Hay 90% de confianza de que el valor real estará entre 275.44 y 450.71.

Nota: Los valores negativos se clampean a 0 automáticamente (revenue no puede ser negativo).

---

📝 Notas Importantes

Sobre el MAPE

El MAPE (Mean Absolute Percentage Error) se devuelve como decimal (0.0 a 1.0):

• mape: 0.05 = 5% de error (excelente)
• mape: 0.15 = 15% de error (aceptable)
• mape: 0.40 = 40% de error (considera usar más datos)
• mape: null = No se solicitó validación (usa validate_periods para obtener MAPE real)

Para obtener MAPE REAL: Incluye validate_periods en tu petición (1-30). Esto realiza backtesting reservando los últimos N valores como ground truth.

Para convertir a porcentaje: mape * 100

Sobre la Calidad de las Predicciones

Factor	Impacto	Recomendación
Cantidad de datos	Alto	Mínimo 30 puntos para predicciones confiables
Regularidad temporal	Alto	Usa frecuencia consistente (diaria, semanal)
Valores atípicos	Medio	Limpia outliers antes de enviar
Estacionalidad	Medio	Incluye al menos 1 ciclo completo
Tendencia clara	Alto	Series con tendencia tienen mejor MAPE

Cuando el quality_warning Aparece

Recibirás quality_warning cuando:

• validate_periods está especificado pero hay datos insuficientes para backtesting
• Datos mínimos requeridos: validate_periods + 10 puntos (10 para training, resto para validación)
• Ejemplo: Si validate_periods: 7, necesitas al menos 17 puntos de datos

Importante: Sin validate_periods, no se genera ningún quality_warning (y mape es null).

Tiempo de Respuesta

Puntos de Datos	Tiempo Estimado
10-100	< 2 segundos
100-1000	2-5 segundos
1000-5000	5-15 segundos

Nota: La primera petición del día puede tener ~20-30s de latencia adicional (cold start).

---

💬 ¿Necesitas Ayuda?

📧 soporte@apisdom.com

---

⚖️ Aviso Legal

Nota de Transparencia: Esta API utiliza el modelo de código abierto Chronos-2 de Amazon Science para pronósticos de series temporales. Los resultados reflejan las capacidades y limitaciones inherentes del modelo. ApisDom proporciona una interfaz optimizada para consumo vía API.

Las predicciones son estimaciones estadísticas basadas en patrones históricos. No deben usarse como única base para decisiones de negocio críticas. Para aplicaciones de alto riesgo, se recomienda validación adicional.

Los intervalos de confianza (lower/upper) representan límites de probabilidad del 90%, no garantías. Los valores reales pueden caer fuera de estos rangos el 10% de las veces.

Ultima actualizacion de documentacion: 10 de abril de 2026