Integrar por API

This content is not available in your language yet.

Esta guía es para el equipo técnico del cliente. Vas a conectar MateGuard a tu stack para que cada promoción pase por un análisis automático —como un gate de CI— y para recibir los resultados en tus propios sistemas sin entrar al dashboard. Al terminar vas a tener una API key, un webhook registrado y un pipeline que dispara análisis y consume las respuestas.

Antes de empezar

Necesitás rol owner o admin: son los únicos que pueden generar credenciales.
Las credenciales se administran en Configuración → API & Webhooks (/settings/api).
Los análisis siguen consumiendo la cuota de tu plan. La API comparte las mismas reglas de acceso que el dashboard, así que vas a chocar los mismos límites (ver “Problemas comunes”).

1. Generá una API key

En API & Webhooks, generá una key. El secreto se muestra una sola vez: copialo y guardalo en tu gestor de secretos en ese momento. Si lo perdés, revocá la key y generá una nueva.

Autenticás cada request con el header X-API-Key:

curl https://api.mateguard.com.ar/v1/analyses/{id} \
  -H "X-API-Key: tu_api_key"

Las keys creadas desde el dashboard tienen acceso completo. Si querés keys con permisos acotados (por ejemplo, solo lectura de análisis), eso se crea por la propia API.

2. Dispará un análisis

Encolá un análisis con POST /v1/analyses. Responde 202 con un id estable. La operación soporta Idempotency-Key, así que podés reintentar sin duplicar:

curl -X POST https://api.mateguard.com.ar/v1/analyses \
  -H "X-API-Key: tu_api_key" \
  -H "Idempotency-Key: promo-black-friday-2026" \
  -H "Content-Type: application/json" \
  -d '{"text": "Regla de la promo a analizar..."}'

Después consultás el resultado con GET /v1/analyses/{id}, o esperás el webhook (paso 3).

3. Registrá un webhook y verificá su firma

Desde API & Webhooks registrás un webhook indicando la URL de destino; el secreto se muestra una vez. La UI suscribe a todos los eventos; si necesitás un subconjunto, registrá el webhook por la API (POST /v1/webhooks).

Cada entrega viene firmada con HMAC-SHA256. Verificá la firma con tu secreto antes de confiar en el payload —es la única forma de asegurar que el evento vino de MateGuard.

Podés forzar una entrega de prueba con POST /v1/webhooks/{id}/test y revisar el historial de entregas con GET /v1/webhooks/{id}/deliveries.

4. (Opcional) Traé el SQL de monitoreo

Si empujás el esquema de tus tablas (/v1/schema*), podés obtener el SQL de monitoreo renderizado a tu warehouse con GET /v1/analyses/{id}/monitoring-sql.

Qué esperar

Errores en formato RFC 7807 (application/problem+json): cuerpo estructurado con type, title y status, fácil de rutear en tu cliente.
Rate limit por plan (30/30/120/300 rpm) con headers en la respuesta.
Una key revocada se rechaza de inmediato.

Problemas comunes

Recibo 403 email-not-verified. En plan Free, la cuenta debe tener el email verificado antes de encolar. Verificá el email desde el dashboard.

Recibo 402 antes de llegar al rate limit. Los gates de acceso corren antes que el límite por minuto: subscription-paused (suscripción pausada por falta de pago), quota-exceeded (agotaste los análisis del mes) y free-tier-cap-exceeded (tope global del tier Free). Revisá el title del cuerpo para saber cuál es y regularizá plan o pago.

Mi webhook dejó de recibir eventos. Tras 10 fallos consecutivos, el endpoint se deshabilita automáticamente y se envía un aviso por email. No hay re-habilitación: borrá el webhook y volvé a crearlo (vas a obtener un secreto nuevo).

Una entrega puntual falló. Reintentá esa entrega específica con POST /v1/webhooks/{id}/deliveries/{delivery_id}/redeliver.

Qué sigue

Vigilar un vector para llevar un finding a monitoreo continuo.
Gobernar tu organización para administrar quién genera credenciales.
Pagos y planes para entender los límites de cuota que ves desde la API.
Conceptos para el vocabulario del producto.