Recetas: integraciones típicas con la API y los webhooks

​

1. Sincronizar las suscripciones a tu warehouse

query Sync($after: String, $since: DateTime) {
  subscriptions(
    first: 100
    after: $after
    filter: { updatedAfter: $since }
    sortKey: UPDATED_AT
    reverse: true
  ) {
    nodes {
      id status customerEmail shopifyCustomerId
      amount currency frequency frequencyType nextPaymentDate
      plan { id name } planGroup { id title }
      items { shopifyVariantId quantity unitAmount role }
      shippingAddress { city province countryCode }
      createdAt updatedAt
    }
    pageInfo { hasNextPage endCursor }
  }
}

import requests, datetime

API = "https://api.appreval.com/api/graphql"
HEADERS = {"Authorization": "Bearer reval_XXXXXXXX", "Content-Type": "application/json"}

def fetch_changed(since: str):
    after = None
    while True:
        r = requests.post(API, headers=HEADERS, json={"query": QUERY, "variables": {"after": after, "since": since}})
        r.raise_for_status()
        page = r.json()["data"]["subscriptions"]
        yield from page["nodes"]
        if not page["pageInfo"]["hasNextPage"]:
            return
        after = page["pageInfo"]["endCursor"]

started = datetime.datetime.now(datetime.timezone.utc).isoformat()
for sub in fetch_changed(last_run):   # last_run: lo que guardaste la vez anterior
    upsert(sub)                       # tu warehouse, clave primaria = sub["id"]
save_last_run(started)

• Pedí first: 100 (el máximo) y no anides orders adentro de subscriptions: 100 × 100 supera el tope de nodos por request. Traé los pedidos en una segunda consulta (receta 2).
• updatedAt cambia con cualquier edición, cobro, pausa o cancelación, así que una suscripción cancelada entra en la próxima corrida sola.
• Con 2000 requests por minuto por clave, una tienda con 50.000 suscripciones se sincroniza entera en menos de un minuto; el ritmo lo marca tu warehouse, no la API.

​

2. Conciliar los pedidos del mes con contabilidad

{
  orders(first: 100, filter: { createdAfter: "2026-10-01T00:00:00Z", createdBefore: "2026-11-01T00:00:00Z" }) {
    totalCount
    nodes {
      id type cycleNumber amount currency createdAt
      shopifyOrderId shopifyOrderName mercadoPagoPaymentId
      subscription { id customerEmail }
    }
    pageInfo { hasNextPage endCursor }
  }
}

• type distingue el primer cobro (FIRST) de las renovaciones (RENEWAL); el descuento de primer pedido solo aplica al primero.
• Un pedido combinado (auto-merge) aparece una vez por suscripción con el mismo shopifyOrderId: cada fila es un cobro de Mercado Pago, así que la suma de amount coincide con lo cobrado aunque el pedido de Shopify sea uno solo.
• Si tu contabilidad necesita el IVA, cada suscripción trae tax { amount rate title included }.

​

3. Un bot de soporte que pausa, saltea y cancela

query Find($email: String!) {
  customer(email: $email) {
    subscriptions(first: 10, filter: { status: [ACTIVE, PAUSED] }) {
      nodes { id status nextPaymentDate plan { name } }
    }
  }
}

curl https://api.appreval.com/api/graphql \
  -H "Authorization: Bearer reval_XXXXXXXX" \
  -H "Idempotency-Key: ticket-48213-pause" \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation($id: ID!) { subscriptionPause(id: $id) { subscription { id status } userErrors { code message } } }","variables":{"id":"cmg…"}}'

• Usá como Idempotency-Key algo que identifique la intención (el ID del ticket más la acción): si tu herramienta reintenta, la API devuelve la misma respuesta sin pausar dos veces.
• MIN_CYCLES significa que el plan tiene un compromiso mínimo que el cliente no cumplió. Es la misma regla que ve en el portal: decidí en tu bot si el agente puede saltearla con overrideMinCycles: true (actúa como el merchant).
• Para cancelar, pedile al agente un motivo de la lista (TOO_EXPENSIVE, DELIVERY_PROBLEMS…) y pasá el texto libre en note: aparece en el análisis de bajas del dashboard.
• El historial de la suscripción muestra «API (nombre de la clave)», así que nombrá la clave con el nombre de la herramienta («Zendesk bot»).

​

3b. Un bot que arma el checkout listo para el cliente

curl https://api.appreval.com/api/graphql \
  -H "Authorization: Bearer reval_XXXXXXXX" \
  -H "Idempotency-Key: conv-9154-link" \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { checkoutLinkCreate(lines: [{ planId: \"cmg…\", quantity: 2 }, { planId: \"cmh…\", quantity: 1 }], customer: { email: \"ana@ejemplo.com\", firstName: \"Ana\", phone: \"+5491144445555\", address: { address1: \"Calle 123\", city: \"CABA\", province: \"Buenos Aires\", zip: \"1414\", countryCode: \"AR\" } }, externalRef: \"conv-9154\") { url expiresAt userErrors { code message field } } }"}'

• La respuesta trae la URL lista para mandar y expiresAt. La URL no lleva ningún dato personal — solo un código opaco; los datos viven en Reval, vencen a los 30 días y se borran al usarse.
• Los planes pueden tener frecuencias distintas: el cliente paga una vez y cada frecuencia queda como su propia suscripción.
• Cuando el cliente completa la compra, tu externalRef aparece en Subscription.externalRef y como external_ref en el webhook subscription.created — ahí tu bot cierra el circuito con su conversación.
• El link es de un solo uso: para una compra nueva, generá otro. Un link sin customer ni externalRef también funciona y es permanente.
• Los errores vuelven por userErrors indicando la línea (lines[1]: …): plan inactivo (PLAN_UNAVAILABLE), bundle o producto-caja (REJECTED), input inválido (INVALID_INPUT). Nunca se genera un link muerto.

​

4. Alertas de cobros fallidos en Slack (o donde quieras)

from flask import Flask, request, abort
import hmac, hashlib, time, requests

app = Flask(__name__)
SECRET = "whsec_XXXXXXXX"
SEEN = set()  # en producción, una tabla o Redis

@app.post("/reval")
def reval():
    raw = request.get_data()
    parts = dict(kv.split("=", 1) for kv in request.headers["X-Reval-Signature"].split(","))
    expected = hmac.new(SECRET.encode(), f"{parts['t']}.".encode() + raw, hashlib.sha256).hexdigest()
    if abs(time.time() - int(parts["t"])) > 300 or not hmac.compare_digest(expected, parts["v1"]):
        abort(401)
    delivery_id = request.headers["X-Reval-Delivery"]
    if delivery_id in SEEN:
        return "", 200          # reintento de algo ya procesado
    SEEN.add(delivery_id)
    event = request.get_json()
    if event["topic"] == "subscription.payment_failed":
        d = event["data"]
        requests.post(SLACK_WEBHOOK, json={"text": f":warning: Cobro fallido de {d['customer_email']} ({d['amount_formatted']}): {d['reason_text']}"})
    return "", 200

• Respondé 200 antes de hacer cosas lentas; si Slack tarda más de 10 segundos, Reval cuenta el intento como fallido y reintenta.
• Mercado Pago reintenta el cobro por su cuenta; si después aprueba, recibís subscription.charged para la misma suscripción.
• Si querés ver el estado actual sin esperar el próximo evento, consultá subscription(id) { lastPaymentFailedAt lastPaymentFailReason status }.

​

5. Webhooks en Zapier, Make o n8n, sin escribir código

1. En tu herramienta, creá un trigger de tipo Webhook / Catch hook y copiá la URL que te da (es https, así que Reval la acepta).
2. En Reval → Integraciones → Webhooks, agregá un endpoint con esa URL y marcá solo los eventos que necesitás (por ejemplo subscription.cancelled).
3. Tocá Enviar prueba: tu herramienta recibe un evento test con la misma forma que uno real, y con eso mapeás los campos (data.customer_email, data.product_names, data.reason…).
4. Guardá el flujo. A partir de ahí, cada evento real lo dispara.

• Estas herramientas responden 2xx al instante, que es lo que Reval espera. No hace falta verificar la firma para empezar; si querés hacerlo, Make y n8n tienen pasos de HMAC con los que podés replicar la verificación.
• Usá data.subscription_id como clave en tu planilla o CRM para no duplicar filas cuando Reval reintenta una entrega.

​

6. Email de retención con link directo al portal

mutation { subscriptionPortalLink(id: "cmg…") { url expiresAt userErrors { code message } } }

• El link está firmado y vence: generalo al momento de mandar el email, no lo guardes.
• Trátalo como una credencial: quien lo tenga entra al portal de ese cliente. No lo mandes por canales donde pueda quedar expuesto.
• Si usás Klaviyo, los eventos que Reval le manda ya incluyen portal_subscription_url, que abre la suscripción en el portal con el login normal del cliente; subscriptionPortalLink es para cuando necesitás el acceso directo desde otra herramienta.

​

Qué elegir: API, webhooks o Klaviyo