API de Avalio

Integrá el análisis de riesgo de cheques a tu sistema. La API es determinística (el mismo motor que usa la app, con datos oficiales del BCRA) y responde en segundos. Sumá webhooks firmados para que tu sistema se entere solo cuando un emisor que monitoreás se deteriora, sin consultar en loop.

Todo es self-service: generás la clave, probás gratis en el sandbox y empezás a integrar hoy, sin llamar a ventas ni firmar nada. A diferencia de los burós tradicionales —que te atienden por teléfono y no publican ni precios ni documentación—, acá tenés OpenAPI, Postman, precios públicos y una decisión explicable desde la primera llamada.

Cómo funciona, en 3 pasos

En criollo: tu sistema se identifica con su clave, hace una pregunta a un endpoint y recibe la respuesta lista para usar en JSON. Nada de pantallas ni teléfono: todo máquina a máquina.

Autenticación

Todas las llamadas usan una clave de API de tu empresa. La generás desde la app, en Integraciones → API (solo el administrador). Se muestra una sola vez: guardala en un lugar seguro. Enviala en el header Authorization: Bearer o en x-api-key.

Authorization: Bearer avk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Claves de prueba y de producción

Hay dos tipos de clave, y las dos son self-service (alta inmediata, sin hablar con ventas y sin contrato):

Riesgo de cliente por CUIT

POST /api/v1/riesgo. Evaluá a un cliente o proveedor al que le vendés a crédito sin un cheque de por medio. Enviás el CUIT y, opcionalmente, un monto y plazo para simular el límite. Recibís la identidad (nombre, DNI derivado del CUIT, estado en ARCA), una decisión explícita y el porqué.

curl -X POST https://avalio.com.ar/api/v1/riesgo \
  -H "Authorization: Bearer avk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "cuit": "30700000040" }'

{
  "ok": true,
  "version": "v1",
  "modo": "sandbox",
  "cuit": "30700000040",
  "identidad": {
    "cuit": "30700000040",
    "tipo_persona": "juridica",
    "dni": null,
    "nombre": "SANDBOX APOC SA",
    "estado_arca": "activo"
  },
  "decision": "rechazar",
  "score": 5,
  "nivel": "Alto",
  "probabilidad_cobro": 5,
  "reasons": [
    { "code": "EN_APOC", "severidad": "critica",
      "mensaje": "El CUIT figura en la base APOC de ARCA (facturas apócrifas)." }
  ],
  "fuentes": [
    { "clave": "bcra", "etiqueta": "BCRA · Central de Deudores...", "estado": "ok",
      "as_of": "2026-01-02T12:00:00.000Z" },
    { "clave": "apoc", "etiqueta": "ARCA · Base APOC...", "estado": "alerta",
      "as_of": "2026-01-02T12:00:00.000Z" }
  ],
  "datos_desactualizados": false,
  "generado": "2026-01-02T12:00:00.000Z"
}

La respuesta es explicable: decision es una de aprobar/revisar/rechazar; cada item de reasons trae un code estable (ruteá tu lógica por el código, no por el texto); y cada fuentes[] incluye as_of (la fecha del dato). Si el BCRA está caído, datos_desactualizados es true y no se cobra.

Buscar empresa por nombre → CUIT

¿Tenés el nombre pero no el CUIT? Resolvelo con los avisos del Boletín Oficial. Es un paso previo al análisis: no consume crédito. Devuelve las coincidencias con su CUIT, listas para pasar a /riesgo. Alcance: sociedades (S.A., S.R.L., S.A.S.) con avisos recientes; no resuelve monotributistas ni personas físicas. Ningún buró self-service argentino expone esto por API.

curl "https://avalio.com.ar/api/v1/empresas/buscar?nombre=Molinos%20Rio%20de%20la%20Plata" \
  -H "Authorization: Bearer avk_live_..."

{
  "resultados": [
    { "cuit": "30500010912", "denominacion": "MOLINOS RIO DE LA PLATA S.A." }
  ],
  "request_id": "req_2f8c..."
}

Sandbox

Con una clave avk_test_ estos CUIT ficticios devuelven cada caso canónico, siempre igual, sin consumir crédito. Ideal para tus tests automatizados.

Precios

Pagás por consulta, no por plan: comprás un pack de créditos que no vence y cada consulta a producción descuenta uno. Sin contrato, sin mínimos. El pago es con Mercado Pago (tarjeta, débito o dinero en cuenta); también hay tarjeta internacional. El sandbox y las consultas servidas con datos de respaldo por caída del BCRA no cobran.

Comprá un pack desde tu cuenta (Comprar análisis) o mirá los planes y precios. Para volumen alto, escribinos.

Especificación y herramientas

La spec OpenAPI 3.1 está publicada en /api/v1/openapi: importala en Postman o Insomnia, o generá un SDK con openapi-generator. También podés bajar la colección de Postman.

O usá los clientes oficiales, sin dependencias (bajalos y listo): avalio.js para Node 18+ (usa fetch nativo) y avalio.py para Python 3.8+ (solo la librería estándar). Cubren todos los endpoints —riesgo, evaluate, análisis, lote, monitoreo, verificación— con Idempotency-Key y errores tipados por code.

const res = await fetch("https://avalio.com.ar/api/v1/riesgo", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.AVALIO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ cuit: "30700000016" }),
});
const data = await res.json();
if (data.decision === "rechazar") { /* frenar la operación */ }

import os, requests

res = requests.post(
    "https://avalio.com.ar/api/v1/riesgo",
    headers={"Authorization": f"Bearer {os.environ['AVALIO_API_KEY']}"},
    json={"cuit": "30700000016"},
    timeout=30,
)
data = res.json()
if data["decision"] == "rechazar":
    ...  # frenar la operación

Evaluar un cheque

POST /api/v1/evaluate. Enviás el CUIT del librador y, opcionalmente, el monto y el plazo (en días). Recibís el score, la recomendación y el detalle.

curl -X POST https://avalio.com.ar/api/v1/evaluate \
  -H "Authorization: Bearer avk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "cuit": "30711044567", "monto": 1500000, "plazo": 30 }'

{
  "ok": true,
  "version": "v1",
  "cuit": "30711044567",
  "denominacion": "EMPRESA EJEMPLO S.A.",
  "score": 82,
  "nivel": "Bajo",
  "recomendacion": "Aprobar",
  "probabilidad_cobro": 88,
  "cheques_rechazados": 0,
  "sin_registros": false,
  "confianza": 90,
  "datos_parciales": false,
  "datos_desactualizados": false,
  "generado": "2026-07-28T14:30:00.000Z"
}

Importante: datos_parciales o datos_desactualizados en truesignifican que una fuente estaba caída o se sirvió una copia de respaldo. En ese caso el resultado es orientativo: conviene reintentar antes de decidir. Avalio nunca asume que una fuente caída está «limpia».

¿Qué pesa en el score? Mirá la metodología del score. Y si querés ver el mismo análisis paso a paso sin código, mirá cómo analizar un cheque.

Límites de uso

60 solicitudes por minuto y 2.000 por hora, por clave. Si los superás, la API responde 429.

Manejo de errores e idempotencia

Ante un error, la API responde con un cuerpo uniforme: un code estable (no cambia aunque reescribamos el texto), el error legible y el request_id (también en el header X-Request-Id) para soporte. Ruteá tu lógica por el code, no por el texto ni por el status solo.

{
  "ok": false,
  "error": "Sin créditos disponibles. Cargá un pack para seguir consultando.",
  "code": "insufficient_credits",
  "request_id": "req_2f8c..."
}

Dos casos no se cobran: insufficient_credits (402) y source_unavailable (503, una fuente oficial caída). Ante un 429, respetá el header Retry-After (segundos). Un patrón robusto:

const res = await fetch(url, opts);
const data = await res.json();

if (!data.ok) {
  switch (data.code) {
    case "rate_limited": {               // 429: respetá Retry-After y reintentá
      const espera = Number(res.headers.get("Retry-After") || 1);
      await new Promise((r) => setTimeout(r, espera * 1000));
      return reintentar();
    }
    case "source_unavailable":           // 503: fuente caída, NO se cobró
    case "internal_error":               // 500: reintentá con backoff
      return reintentarConBackoff();
    case "insufficient_credits":         // 402: cargá un pack; NO reintentes en loop
    case "invalid_request":              // 400: corregí el pedido antes de reintentar
    default:
      // registrá data.code y data.request_id para soporte
      throw new Error(data.code + " / " + data.request_id);
  }
}

Idempotencia (reintentar sin re-cobrar)

Si tu red se corta y no sabés si el POST llegó, reintentalo con el mismo header Idempotency-Key: Avalio devuelve la misma respuesta (con X-Idempotent-Replayed: true), sin volver a consultar ni a cobrar. La clave vale 24 h. Usar la misma clave con un cuerpo distinto corta con 409 (idempotency_conflict): para un pedido diferente, usá una clave nueva. Mismo comportamiento que Stripe.

curl -X POST https://avalio.com.ar/api/v1/riesgo \
  -H "Authorization: Bearer avk_live_..." \
  -H "Idempotency-Key: pedido-7f3a9c" \
  -H "Content-Type: application/json" \
  -d '{ "cuit": "30711044567" }'

Webhooks

En vez de consultar la API en loop, registrá una URL y Avalio te avisa cuando pasa algo relevante sobre tus emisores monitoreados. La configurás en Integraciones → Webhooks (solo el administrador); podés probar la conexión al instante con el botón Probar.

Cada entrega es un POST con este cuerpo:

{
  "event": "emisor.deterioro",
  "created": "2026-07-28T14:30:00.000Z",
  "data": {
    "cuit": "30711044567",
    "denominacion": "EMPRESA EJEMPLO S.A.",
    "score": 58,
    "score_anterior": 74,
    "nivel": "Medio"
  }
}

Verificar la firma

Cada entrega viaja firmada en el header X-Avalio-Signature con el formato t=<timestamp>,v1=<hmac>. El HMAC es SHA-256 sobre el texto <timestamp>.<cuerpo> usando el secret del webhook. Verificalo antes de confiar en el evento, y rechazá timestamps viejos (evita reenvíos).

const crypto = require('crypto');

function verificarAvalio(secret, rawBody, header) {
  const partes = Object.fromEntries(header.split(',').map(kv => kv.split('=')));
  const t = Number(partes.t);
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // > 5 min: posible reenvío
  const esperado = crypto.createHmac('sha256', secret)
    .update(t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1));
}

Respondé 2xx para confirmar la recepción. Si tu endpoint no responde, Avalio registra el fallo y lo vas a ver en el panel.

Disponibilidad y estado

El estado en vivo de la API y de cada fuente oficial está publicado en /estado. El diseño es fail-safe: si una fuente (BCRA, ARCA) está caída, la API responde con datos_desactualizados: true y no cobra esa consulta, en vez de darte un resultado como si la fuente estuviera bien. Para integraciones de alto volumen ofrecemos un SLA formal por contrato (disponibilidad y soporte dedicado): escribinos.

Versionado y registro de cambios

La API es estable y versionada por ruta (/api/v1). Política de compatibilidad: los cambios retrocompatibles (campos y headers nuevos, endpoints nuevos, valores nuevos en un enum) se publican sin aviso y no te rompen —programá tolerando campos desconocidos—. Un cambio incompatible nunca se aplica sobre /api/v1: saldría como una versión nueva (/api/v2), con la v1 funcionando en paralelo y un preaviso de al menos 6 meses antes de cualquier baja, avisado por mail a los integradores y acá en el changelog.

• 22/10/2026100 consultas reales gratis al generar tu primera clave (free tier, sin tarjeta). Respuestas de riesgo FIRMADAS (HMAC): cada respuesta trae un bloque firma verificable por un tercero en POST /v1/verificar (sin API key) — probá que una decisión la emitió Avalio y no fue alterada. Clientes oficiales sin dependencias (Node y Python) y colección de Postman completa. El contrato uniforme (code estable, request_id, headers de rate-limit) ahora cubre TODOS los endpoints.
• 21/10/2026Nuevo GET /v1/empresas/buscar: resolvé el CUIT de una empresa por su nombre (razón social) desde el Boletín Oficial, como paso previo al análisis. No consume crédito; con clave de prueba responde en sandbox.
• 20/10/2026Headers de clase mundial en todas las respuestas: X-Request-Id, X-RateLimit-Limit/Remaining/Reset, Retry-After y X-Avalio-Credits-Charged/Remaining. Códigos de error estables (code). Soporte de Idempotency-Key (reintento sin re-cobrar). Campo opcional resumen_ia (explicá el resultado en lenguaje natural con explicar:true).
• 18/10/2026Nuevo POST /v1/riesgo (riesgo de cliente por CUIT, con identidad y decisión explicable). Análisis por lote (/v1/riesgo/lote) y monitoreo con webhooks firmados (emisor.deterioro, lote.completado).
• 24/08/2026Claves de prueba (avk_test_) y sandbox determinístico de CUIT: integrá y escribí tus tests antes de pagar.
• 21/07/2026Lanzamiento de la API v1: POST /v1/evaluate (riesgo de un cheque por CUIT) y OpenAPI 3.1 público.