Quickstart — primeiros passos com a API do vario

Este guia leva você do zero à sua primeira análise de texto em menos de 5 minutos. Ao concluí-lo, você terá registrado uma conta, consultado os playbooks disponíveis, enviado uma requisição de análise e interpretado a resposta.

Base URL: https://api.vario.lat/v1 Autenticação: Authorization: Bearer vario_SUA_API_KEY

Passo 1 — Registrar conta de API

Crie uma conta API-only com créditos de boas-vindas. Não é necessário cartão de crédito.

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Seu Nome",
    "organization": "Sua Organização"
  }'

Resposta 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."
}

O saldo inicial é de 250 créditos gratuitos, suficientes para explorar todos os modos e playbooks.

Erros frequentes neste passo:

Passo 2 — Consultar playbooks disponíveis

Liste os tipos de conduta que você pode detectar e os idiomas suportados por cada um.

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

Resposta 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"
    }
  ]
}

Use o valor de conduct_type no campo playbook do próximo passo. O campo language aceita os códigos ISO 639-1 listados por cada playbook.

Passo 3 — Analisar um texto

Envie um texto para análise. O vario não armazena nem retém o texto analisado — cada requisição é stateless.

curl -X POST https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer vario_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Combinamos manter os preços em $X neste trimestre",
    "language": "pt",
    "playbook": "price_fixing",
    "mode": "fast"
  }'

Parâmetros da requisição:

Resposta 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
}

Passo 4 — Interpretar o resultado

combined_score

Número em escala de 0 a 10. Quanto maior o valor, maior o risco detectado. Use-o para priorizar quando processar volumes altos de texto.

should_alert

Booleano. true indica que a análise superou o limiar de risco configurado para o playbook. Na maioria dos fluxos, esse campo é o gatilho principal da sua lógica de escalonamento.

severity

Categórico com quatro níveis:

reasoning

Texto explicativo que descreve os fatores de risco identificados na mensagem. Útil para que um revisor humano entenda por que o sistema gerou o alerta sem precisar voltar ao texto original.

recommended_action

Sugestão de ação para a equipe de compliance. Os valores disponíveis dependem do modo de análise:

bedrock_available

Se esse campo retornar false, a análise foi parcial: a camada de análise assistida não estava disponível naquele momento. Você pode reenviar a requisição ou adicionar o header Prefer: deep-analysis-required para receber um erro 503 explícito em vez de uma resposta parcial.

Dica — playground gratuito

Antes de integrar a API ao seu sistema, você pode testar requisições diretamente pelo portal. O playground inclui 5 análises gratuitas por dia que não consomem créditos de produção, com visualização imediata da resposta completa.

Próximos passos

• POST /analyze — referência completa do endpoint de análise.
• GET /playbooks — lista de condutas disponíveis.
• Créditos e modos — funil de três etapas (screening → fast → full) para otimizar custos.
• Modo screening — para varredura massiva de corpus, use "mode": "screening" (1 crédito, schema L1 diferente).
• Modo full — para análises mais profundas, use "mode": "full" (3 créditos, raciocínio completo).
• thread_context — se você tiver acesso ao thread de e-mails, passe as mensagens anteriores no array thread_context para melhorar a precisão da análise (apenas efetivo nos modos fast e full).