Guía: facturación

English version: Guide: billing.

Qué puede gastar una cuenta, cómo verlo antes de que deje de marcar y cómo subir de nivel. Toda lectura de abajo es una vista de datos que ya existen —nunca una segunda fuente— y las formas están en la Referencia de la API.

Las claves de prueba no cuestan nada

Las llamadas y SMS simulados de una clave dd_test_ no se miden ni se cobran. Las rutas que gastan de verdad responden 403 test_environment a una clave de prueba. Ver el inicio rápido alojado.

Una cuenta nueva empieza inactiva

Una cuenta creada por el registro público tiene un plan draft: todo lo que gasta o hace una llamada real responde 402 plan_inactive hasta que el plan está activo. Además empieza en el nivel de confianza más bajo, cuyos límites son pequeños a propósito.

Sabe dónde estás

Pregunta	Endpoint
Saldo, el tope vigente, el gasto contra él y el modo de aplicación	GET /v1/billing/account
Qué umbrales de alerta de gasto han saltado	GET /v1/billing/alerts
Líneas facturables en una ventana (no es la factura)	GET /v1/billing/summary
Costo bruto por campaña, operador o agente	GET /v1/billing/cost
El libro de la cartera, apunte por apunte	GET /v1/billing/ledger (from, to, entry_type, limit, cursor)
La factura de un mes natural (el periodo lo fija el servidor)	GET /v1/billing/invoice

curl -s $API/v1/billing/account -H "Authorization: Bearer $TOKEN"

Una cuenta que se queda sin saldo deja de marcar; GET /v1/billing/account es la superficie que puede decirlo antes. Las retenciones abiertas cuentan como gastadas, así que available_usd peca de pronto. enforcement_mode y los umbrales de alerta son de sólo lectura aquí: ajustas cuándo te avisan, nunca si te bloquean. Con la facturación apagada la respuesta es 200 con billing_enabled: false y dinero nulo.

Sube de nivel

curl -s $API/v1/billing/tiers -H "Authorization: Bearer $TOKEN"        # what is on sale, with price and an upgrade flag
curl -s -X POST $API/v1/billing/tier/upgrade \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tier": "<a tier flagged upgrade: true>"}'

• Los derechos cambian al instante; el precio espera al cierre del siguiente periodo. La factura de este mes no cambia ni un centavo y no hay línea de prorrateo.
• Sólo subidas. Una bajada, o repetir la llamada, responde 422 not_an_upgrade; los demás 422 son unknown_tier, tier_not_sellable y tier_not_in_catalog.
• El precio es por asiento y mes. GET /v1/billing/tier muestra el nivel vigente y el cambio pendiente.
• Exige una clave dd_ o una sesión account_admin; una sesión member es 403 role_forbidden.

Webhooks de facturación

Hoy no hay ningún evento de facturación en el catálogo de webhooks. El catálogo es cerrado: call.ended, call.answered, promise.recorded, sms.received, sms.optout, recording.available, disposition.event, carrier.health_changed, anomaly.detected, ai.drift.detected y port_request.ported; un nombre desconocido es 400. Para enterarte de un saldo bajo o de un umbral cruzado, consulta GET /v1/billing/account y GET /v1/billing/alerts. Cómo registrar, firmar y verificar cualquiera de esos eventos está en Webhooks de salida.

Más detalle sobre asientos, planes y medición: guía de la API REST y Límites de uso y topes.