Facturación de APIs: medí y cobrá cada llamada

Resumen

• La facturación de APIs es el pipeline que convierte llamadas en ingresos: medí cada request, agregá el uso por cliente y facturá automáticamente. Una API de billing se encarga de eso para que tu código solo reporte eventos.
• Cuatro modelos de pricing cubren casi cualquier API: por llamada (pagás por request), planes con tiers (cantidad incluida + excedente), créditos (bloques prepagos) y balance prepago (billetera en dólares). La tabla de abajo te dice cuándo usar cada uno.
• La integración son tres llamadas con el SDK @commet/node: creá un cliente, creá una suscripción y registrá un evento de uso por request con clave de idempotencia.
• Construir vs comprar es una pregunta de alcance: la medición sola es un proyecto de fin de semana, pero agregación, facturación, pagos, impuestos y casos borde son un equipo permanente. La mayoría de las empresas de APIs deberían comprar la capa de billing y dejar la ingeniería en el producto.

¿Qué es la facturación de APIs?

La facturación de APIs es el sistema que mide lo que cada cliente consume a través de tu API y se lo cobra. Tiene tres trabajos: medición (contar cada llamada o unidad de trabajo), valorización (aplicar un precio a ese uso) y facturación (convertir el uso valorizado en una factura y cobrarla).

La razón por la que las APIs necesitan infraestructura de billing dedicada es que el uso es el producto. Un dashboard SaaS puede cobrar $49/mes fijos porque servir un login más no cuesta nada. Una API que sirve 10 millones de requests cuesta mucho más que una que sirve 10 mil — cómputo, ancho de banda y muchas veces costos upstream por unidad (tokens de LLM, SMS, lookups de datos) escalan con cada llamada. El precio fijo o le cobra de más a los clientes chicos o deja que los grandes destruyan tu margen.

Una plataforma de facturación de APIs se ubica entre tus handlers y tus ingresos: tu código reporta eventos de uso, la plataforma los agrega por cliente y por período, aplica tu modelo de pricing, genera las facturas y cobra la tarjeta registrada. La alternativa — contar requests en tu propia base de datos y reconciliarlos a mano en facturas — funciona hasta que el primer reintento cuenta un evento dos veces o el primer cambio de precios exige una migración.

¿Cómo funciona la medición y facturación de una API?

El pipeline es el mismo sin importar el proveedor: eventos → agregación → factura.

1. Eventos. Cada request facturable emite un evento de uso: un event code (api_calls), el cliente que consumió, un valor (cuántas unidades) y una clave de idempotencia para que los reintentos nunca cobren dos veces. Los eventos tienen timestamp, así que una entrega tardía no corrompe el período al que pertenecen.
2. Agregación. El motor de billing suma los eventos por cliente, por feature y por período. Acá se descuentan las cantidades incluidas, se decrementan los créditos y se calcula el excedente.
3. Factura. Al cierre del período (o en tiempo real, para los modelos prepagos), el uso agregado se convierte en líneas de factura: precio base, uso incluido, excedente a la tarifa configurada. La factura se finaliza, se cobra al cliente y el ciclo se reinicia.

En Commet esto se mapea a un modelo plan-first: definís una feature con un event code, la empaquetás en un plan con un modelo de pricing y asignás el plan a un cliente. Desde ahí tu única responsabilidad en runtime es reportar eventos — la agregación, la facturación y el cobro corren automáticamente. El mismo pipeline alimenta la medición de tokens para productos de IA; la guía de cobro por uso en productos de IA cubre esa variante en profundidad.

Dos propiedades importan más que cualquier otra cosa en este pipeline:

• Idempotencia. Las redes fallan y las colas reentregan. Si tu pipeline de medición cuenta el mismo request dos veces, le estás cobrando de más a tus clientes en silencio. Cada evento necesita una clave de idempotencia, y la API de ingesta debe rechazar duplicados.
• Auditabilidad. Cuando un cliente pregunta "¿por qué me cobraron $312 este mes?", necesitás el log crudo de eventos, no solo el agregado. Las disputas se ganan o se pierden según puedas mostrar cada llamada contada.

¿Qué modelo de pricing conviene para tu API?

Cuatro modelos cubren casi cualquier negocio de APIs. En Commet, el lado de consumo se mapea a tres modelos de plan — medido, créditos o balance — y son mutuamente excluyentes por plan: cada plan usa exactamente uno. El pricing por tiers es una capa de empaquetado sobre planes medidos, no un cuarto modelo de consumo.

Algo de guía práctica para elegir:

• Por llamada es la forma más pura de pricing por uso: definís un precio por unidad (por ejemplo $0.001 por llamada en un plan de balance con precio fijo, o una tarifa pura de excedente en un plan medido) y cada request se factura a esa tarifa. Convierte bien en self-serve para developers porque no hay nada que dimensionar de entrada.
• Planes con tiers son a lo que converge la mayoría de las empresas de APIs. Un plan medido incluye 10,000 llamadas/mes por un precio base; el excedente se cobra a $0.01 por llamada al cierre del período. Apilá tres o cuatro planes con cantidades crecientes y tenés ingresos predecibles más expansión por uso. Más sobre la mecánica en el glosario de cobro medido.
• Créditos brillan cuando una llamada no equivale a una unidad de costo — una página de OCR cuesta más que un chequeo de estado. Ponerle precio a las operaciones en créditos (1 crédito por lookup, 20 por documento) mantiene tu margen estable mientras los clientes razonan en una sola moneda. En Commet, los créditos del plan se reinician cada período, y los créditos comprados como packs nunca expiran. Mirá cobro por créditos.
• Balance prepago es el modelo de los proveedores de nube: el precio base del plan se convierte en un saldo para gastar y cada evento deduce su costo real en dólares. Los planes de balance soportan precio fijo por unidad o pricing por modelo de IA, donde el costo se calcula desde los precios actuales de tokens más tu margen. Mirá cobro por balance.

Una restricción que conviene diseñar desde temprano: los planes gratuitos no pueden correr excedente — el uso se bloquea al llegar al límite incluido. Eso es una feature, no una limitación; un tier gratuito que factura excedente en silencio es un desastre de soporte.

¿Cómo integro la facturación en mi API?

Con Commet la integración son tres llamadas al SDK. Instalá el SDK:

npm install @commet/node

Primero, creá un cliente y una suscripción. La creación de clientes es idempotente sobre tu propio ID de usuario, así que podés llamarla desde tu flujo de signup sin verificar existencia antes. Crear la suscripción devuelve una URL de checkout donde el cliente carga sus datos de pago:

import { Commet } from "@commet/node";

const commet = new Commet({ apiKey: process.env.COMMET_API_KEY! });

await commet.customers.create({
  email: "billing@acme.com",
  id: "user_123",
});

const subscription = await commet.subscriptions.create({
  customerId: "user_123",
  planCode: "pro",
});

redirect(subscription.data.checkoutUrl);

Desde ahí, facturar una llamada es un solo track() en tu handler. Podés pasar tu propio ID de usuario como customerId — no hace falta guardar ni buscar el ID de Commet:

app.post("/v1/convert", async (request, response) => {
  const conversion = await convertDocument(request.body);

  await commet.usage.track({
    customerId: request.userId,
    feature: "api_calls",
    value: 1,
    idempotencyKey: request.id,
  });

  response.json(conversion);
});

Los parámetros que importan:

• feature es el event code de una feature medida que definiste en el dashboard (api_calls, documents_processed, compute_minutes — snake_case, descriptivo).
• value es la cantidad consumida y por defecto es 1. Usá valores fraccionarios para unidades como gigabytes o minutos.
• idempotencyKey hace seguros los reintentos: Commet rechaza un evento cuya clave ya fue registrada para ese cliente. Usá tu request ID, job ID o cualquier identificador único de la unidad de trabajo. Es opcional en la API y no negociable en la práctica.

Esa es toda la integración en runtime. La agregación, las cantidades incluidas, el excedente, la facturación y el cobro pasan del lado de la plataforma. Si tu API expone LLMs, podés saltarte el conteo manual por completo y pasar el modelo más los conteos de tokens — Commet los valoriza desde un catálogo de 180+ modelos de IA, como cubre la guía de cobro por uso en productos de IA. Para un recorrido completo en tu framework, arrancá por el quickstart de Next.js o la documentación de tracking de uso.

¿Qué debería mostrar un dashboard de facturación de APIs?

Una vez que los eventos fluyen, el dashboard se convierte en tu consola de ingresos. Elijas la plataforma que elijas, estas son las vistas que importan para un negocio de APIs — todas vienen en el dashboard de Commet:

• Eventos de uso. El feed crudo de cada evento registrado con su cliente, feature, valor y timestamp. Es tu pista de auditoría para disputas de facturación y tu herramienta de debugging cuando una integración reporta doble.
• Clientes y suscripciones. Quién está en qué plan, el consumo del período actual contra las cantidades incluidas, y el estado de la suscripción. La pregunta "el cliente quiere saber cuánto debe" tiene que resolverse en un click.
• Facturas. Cada factura generada con líneas que separan el precio base del excedente, su estado de pago y las transacciones detrás.
• Costos de IA (si facturás tokens). Uso de modelo por request, desglose de tokens y el margen aplicado — para ver tu spread entre el costo del proveedor y el precio al cliente.

Tus clientes necesitan la imagen espejo: un portal self-service donde ven el uso actual, los créditos o el balance restante y las facturas, y pueden recargar o comprar packs de créditos sin escribirle a soporte. El Customer Portal de Commet maneja upgrades, compras de packs de créditos y recargas de balance de fábrica — cada ticket de "¿por qué me cobraron esto?" que absorbe el portal es tiempo de soporte que te quedás.

¿Conviene construir o comprar la facturación de tu API?

Respuesta honesta: la medición es fácil de empezar y brutal de terminar, y la medición es la parte más chica del problema.

Construirlo vos tiene sentido cuando la lógica de billing es genuinamente tu diferencial o tu pricing es tan inusual que ninguna plataforma lo modela. Un contador en Redis y un cron mensual funcionan para tus primeros diez clientes. Lo que te alcanza después es todo lo demás: ingesta idempotente bajo reintentos, eventos tardíos y fuera de orden, agregación que sobrevive un cambio de precios a mitad de período, prorrateo en cambios de plan, generación de facturas, pagos fallidos, reembolsos — y después la mitad no-ingenieril: registro, cobro y remisión de impuestos en cada jurisdicción donde viven tus clientes. Cada pieza es abordable; la suma es un equipo de billing permanente.

Comprar solo la capa de medición (un motor de cobro por uso) resuelve eventos, agregación y valorización, pero te deja como vendedor: igual tenés que ensamblar un procesador de pagos, una solución de impuestos y el compliance encima.

Comprar el stack completo significa que un solo proveedor es dueño del camino desde los eventos hasta la plata en el banco. Commet hace esto como Merchant of Record: es el vendedor legal, así que los impuestos se calculan, cobran y remiten por vos, los reembolsos y el compliance están resueltos, los clientes pueden pagar en su moneda local en más de 20 mercados, y los payouts llegan en moneda local en 112 países. Los límites honestos: los pagos son solo con tarjeta hoy (sin PayPal ni transferencia), y el precio es un 4.5% + $0.40 fijo por transacción exitosa, sin cargos mensuales — las cuentas están en la página de precios.

La heurística de decisión: si tus ingenieros están escribiendo pipelines de agregación en lugar de tu producto, elegiste mal. Los datos de uso salen de tu API de cualquier forma; la pregunta es si convertirlos en ingresos es trabajo de tu equipo o de tu proveedor.

Lo esencial

La facturación de APIs es un pipeline — eventos, agregación, factura — y la superficie de integración es chica: un track() por request facturable con clave de idempotencia. Elegí el modelo de pricing según cómo se comportan tus costos: por llamada para costos lineales, planes con tiers para ingresos predecibles con upside por uso, créditos para ocultar la varianza de costo por operación, balance prepago para transparencia y riesgo crediticio cero. En Commet, medido, créditos y balance son mutuamente excluyentes por plan, así que elegí con intención. Y antes de construir nada de esto in-house, ponele precio al iceberg completo — la medición es la punta visible, e impuestos, facturación y casos borde de pagos son el resto. Arrancá por el quickstart y podés facturar tu primera llamada la misma tarde.