Quickstart — primeros pasos con la API de vario

Esta guía te lleva desde cero hasta tu primer análisis de texto en menos de 5 minutos. Al terminarla habrás registrado una cuenta, consultado los playbooks disponibles, enviado un request de análisis e interpretado el response.

Base URL: https://api.vario.lat/v1 Autenticación: Authorization: Bearer vario_TU_API_KEY

Paso 1 — Registrar cuenta de API

Crea una cuenta API-only con créditos de bienvenida. No requiere tarjeta de crédito.

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Tu Nombre",
    "organization": "Tu Organización"
  }'

Response 201:

{
  "key": "vario_xbGhABC123...WXYZ",
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced.",
  "free_credits": 250,
  "call_cost_screening": 1,
  "call_cost_fast": 2,
  "call_cost_full": 3,
  "docs_note": "$0.150 per credit. Pricing is subject to change."
}

El balance inicial es de 250 créditos gratuitos, suficientes para explorar todos los modos y playbooks.

Errores frecuentes en este paso:

Paso 2 — Consultar playbooks disponibles

Lista los tipos de conducta que puedes detectar y los idiomas soportados por cada uno.

curl https://api.vario.lat/v1/playbooks \
  -H "Authorization: Bearer vario_TU_API_KEY"

Response 200:

{
  "playbooks": [
    {
      "conduct_type": "price_fixing",
      "languages": ["es", "pt"],
      "version": "1.0"
    },
    {
      "conduct_type": "bid_rigging",
      "languages": ["es"],
      "version": "1.0"
    },
    {
      "conduct_type": "bribery",
      "languages": ["es", "pt"],
      "version": "1.0"
    },
    {
      "conduct_type": "market_manipulation",
      "languages": ["es"],
      "version": "1.0"
    }
  ]
}

Usa el valor de conduct_type en el campo playbook del siguiente paso. El campo language acepta los códigos ISO 639-1 que lista cada playbook.

Paso 3 — Analizar un texto

Envía un texto para analizar. vario no almacena ni retiene el texto analizado — cada request es stateless.

curl -X POST https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer vario_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Acordamos mantener los precios en $X este trimestre",
    "language": "es",
    "playbook": "price_fixing",
    "mode": "fast"
  }'

Parámetros del request:

Response 200:

{
  "combined_score": 6.8,
  "should_alert": true,
  "severity": "high",
  "reasoning": "El mensaje contiene una referencia explícita a un acuerdo de precios entre competidores. El uso de 'acordamos' en primera persona plural y la mención de un precio fijo para un período específico son señales consistentes con coordinación de precios.",
  "key_phrases": [
    "Acordamos mantener los precios",
    "$X este trimestre"
  ],
  "regulatory_frameworks": [
    "Ley de Defensa de la Competencia (Chile, DL 211)",
    "Lei 12.529/2011 (CADE, Brasil)",
    "COFECE — Ley Federal de Competencia Económica (México)"
  ],
  "recommended_action": "legal_review",
  "confidence": "high",
  "mode_used": "fast",
  "analyzed_at": "2026-06-02T14:32:00Z",
  "pipeline_version": "1.0",
  "bedrock_available": true
}

Paso 4 — Interpretar el resultado

combined_score

Número en escala de 0 a 10. A mayor valor, mayor riesgo detectado. Úsalo para priorizar cuando procesas volúmenes altos de texto.

should_alert

Booleano. true indica que el análisis superó el umbral de riesgo configurado para el playbook. En la mayoría de los flujos, este campo es el disparador principal de tu lógica de escalación.

severity

Categórico con cuatro niveles:

reasoning

Texto explicativo que describe los factores de riesgo identificados en el mensaje. Útil para que un revisor humano entienda por qué el sistema generó la alerta sin necesidad de regresar al texto original.

recommended_action

Sugerencia de acción para el equipo de compliance. Los valores disponibles dependen del modo de análisis:

bedrock_available

Si este campo retorna false, el análisis fue parcial: el sistema asistido por IA no estuvo disponible en ese momento. Puedes reintentar el request o agregar el header Prefer: deep-analysis-required para recibir un error 503 explícito en lugar de un response parcial.

Tip — playground gratuito

Antes de integrar la API en tu sistema, puedes probar requests directamente desde el portal. El playground incluye 5 análisis gratuitos por día que no consumen créditos de producción, con visualización inmediata del response completo.

Próximos pasos

• POST /analyze — referencia completa del endpoint de análisis.
• GET /playbooks — lista de conductas disponibles.
• Créditos y modos — embudo de tres etapas (screening → fast → full) para optimizar costos.
• Modo screening — para barrido masivo de corpus, usa "mode": "screening" (1 crédito, schema L1 distinto).
• Modo full — para análisis de mayor profundidad, usa "mode": "full" (3 créditos, razonamiento completo).
• thread_context — si tienes acceso al hilo de emails, pasa los mensajes previos en el array thread_context para mejorar la precisión del análisis (solo efectivo en modos fast y full).