API de datos

Empezando

1. En Metricaas, agrega una fuente de tipo Datos personalizados y responde las tres preguntas (si vas a informar pagos, si cada suscripción tiene plan, si vas a registrar clientes).
2. En Configuración > API, genera una clave. Aparece una sola vez.
3. Envía tus suscripciones. El panel se mueve en menos de un minuto.

Autenticación

Cada llamada lleva tu clave en el encabezado. La clave pertenece a tu empresa y dice en qué fuente escribe.

Authorization: Bearer mtc_live_...

Dirección base: https://api.metricaas.ai/v1

Solo guardamos un resumen criptográfico de la clave, así que ni nosotros podemos volver a mostrarla. Si la pierdes, genera otra y revoca la anterior.

Tu primera llamada

Crear y actualizar son la misma llamada: el id es tuyo, y enviar el mismo id de nuevo actualiza en vez de duplicar.

curl -X POST https://api.metricaas.ai/v1/subscriptions \
  -H "Authorization: Bearer mtc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"id":"sub_001","customer":"cli_001","plan":"Pro","currency":"BRL","cycle":"monthly","started_at":"2024-01-10","amounts":[{"from":"2024-01-10","cents":9990},{"from":"2025-03-01","cents":12990}]}'

Envía en LOTE (un array en el cuerpo, hasta 1000 objetos). O entra todo, o no entra nada: un lote a medias te dejaría sin saber qué entró.

El importe es un HISTORIAL, no un número

En una pasarela, el historial del precio vive en las facturas: cada una es un periodo cobrado, con el precio de ese día. Aquí no hay facturas, así que el historial vive dentro de la suscripción, en el campo `amounts`.

Cada tramo dice cuánto pasó a valer, y desde cuándo. El primero empieza cuando empezó la suscripción. Eso es lo que hace que el MRR de marzo siga siendo el de marzo después de que subes el precio en abril.

{
  "amounts": [
    {
      "from": "2024-01-10",
      "cents": 9990
    },
    {
      "from": "2025-03-01",
      "cents": 12990
    }
  ]
}

Por eso, un envío que ACORTE o ALTERE un tramo ya declarado se rechaza con 409: reescribiría el MRR de meses que ya cerraron. Si fue un ajuste de precio, agrega un tramo nuevo. Si fue un error de tipeo, confirma que de verdad quieres reescribir:

POST https://api.metricaas.ai/v1/subscriptions?correct_history=true

Cancelar no es borrar

Cancelar es un hecho de tu negocio: el cliente se fue, la suscripción queda en el historial y se vuelve churn en la fecha declarada. Borrar es una errata: nunca existió, y el MRR pasado se rehace sin ella. Confundir las dos corrompe tu churn en ambas direcciones.

# el cliente se fue (se vuelve churn)
PUT https://api.metricaas.ai/v1/subscriptions/sub_001   { "canceled_at": "2026-03-01", ... }

# lo escribi mal (desaparece del historial)
DELETE https://api.metricaas.ai/v1/subscriptions/sub_001

/v1/customers

Opcional. Solo hace falta si un mismo cliente tiene más de una suscripción. El único campo obligatorio es el id, así que puedes agrupar sin contarnos quiénes son.

{
  "id": "cli_001",
  "name": "Empresa Exemplo",
  "email": "contato@exemplo.com"
}

/v1/subscriptions

El corazón de la fuente. De aquí sale tu MRR.

{
  "id": "sub_001",
  "customer": "cli_001",
  "plan": "Pro",
  "currency": "BRL",
  "cycle": "monthly",
  "started_at": "2024-01-10",
  "amounts": [
    {
      "from": "2024-01-10",
      "cents": 9990
    },
    {
      "from": "2025-03-01",
      "cents": 12990
    }
  ]
}

/v1/payments

Opcional. Si declaras los pagos, ganas morosidad, ingresos cobrados, comisiones y reembolsos. Si no, el MRR sigue completo y la morosidad simplemente no existe en tu cuenta.

{
  "id": "pay_001",
  "customer": "cli_001",
  "subscription": "sub_001",
  "amount_cents": 9990,
  "paid_at": "2024-02-10",
  "fee_cents": 349
}

Errores

El rechazo lista TODOS los problemas de una vez, con el campo (y, en la planilla, la fila). No vas a corregir uno por petición.

{
  "error": {
    "code": "invalid_request",
    "message": "a declaracao tem 2 problema(s)",
    "details": [
      {
        "field": "subscription.cycle (sub_002)",
        "line": 4,
        "reason": "invalid option"
      },
      {
        "field": "subscription.amounts (sub_007)",
        "line": 9,
        "reason": "..."
      }
    ]
  }
}

• 202 — aceptado. Tu panel se mueve en menos de un minuto.
• 400 — la declaración tiene problemas. No se guardó nada.
• 401 — clave inválida, revocada, o sin permiso para esta operación.
• 409 — esto reescribiría el historial de importes ya declarado. Mira la sección de arriba.
• 429 — demasiadas peticiones. Envía en lote.

Revisando lo que declaraste

El GET devuelve lo que está en tu bóveda, paginado por cursor. Esta misma clave leerá tus métricas cuando exista la API de lectura.

GET https://api.metricaas.ai/v1/subscriptions?limit=100&cursor=sub_050