Resumen de API de Facturación

Guía completa para administrar suscripciones, uso y facturación con la API de CallCov.

Niveles de Facturación

CallCov ofrece tres niveles:

Nivel	Precio	Minutos	Análisis	Ideal Para
Gratuito	$0/mes	500	Solo transcripción	Pruebas
Starter	$49/mes	1,000	Análisis de 16 puntos	Equipos pequeños
Growth	$199/mes	5,000	Análisis avanzado con IA	Negocios en crecimiento

Enlaces Rápidos

Obtener Suscripción - Ver suscripción actual
Resumen de Facturación - Uso y costos
Niveles Disponibles - Información de precios
Crear Checkout - Suscribirse a nivel pago
Portal del Cliente - Administrar facturación
Cancelar Suscripción - Cancelar plan
Reactivar - Deshacer cancelación
Actualizar - Moverse a nivel superior
Degradar - Moverse a nivel inferior
Historial de Facturas - Ver facturas pasadas

Obtener Suscripción

Obtener detalles de la suscripción actual incluyendo uso y límites.

Endpoint

GET /api/v1/billing/subscription

Autenticación

Token JWT o clave de API

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "660f9511-f3ac-52e5-b827-557766551111",
  "tier": "starter",
  "status": "active",
  "minutes_included": 1000,
  "minutes_used": 245.5,
  "minutes_remaining": 754.5,
  "overage_minutes": 0,
  "current_period_start": "2024-01-01T00:00:00Z",
  "current_period_end": "2024-02-01T00:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "tier_info": {
    "name": "Starter",
    "price_monthly": 49,
    "minutes_included": 1000,
    "overage_rate": 0.05,
    "features": ["Análisis de Cumplimiento de 16 Puntos", "Soporte por Email"]
  }
}

Resumen de Facturación

Obtener resumen comprensivo de facturación con estadísticas de uso.

Endpoint

GET /api/v1/billing/subscription/summary

Autenticación

Token JWT o clave de API

Response

{
  "subscription": { /* Igual que Obtener Suscripción */ },
  "usage": {
    "total_minutes_used": 245.5,
    "analysis_count": 82,
    "minutes_remaining": 754.5,
    "usage_percentage": 24.55
  },
  "estimated_overage_cost": 0.00
}

Obtener Niveles

Obtener información sobre todos los niveles de facturación disponibles.

Endpoint

GET /api/v1/billing/tiers

Autenticación

No requerida (endpoint público)

Response

{
  "tiers": [
    {
      "tier": "free",
      "name": "Gratuito",
      "price_monthly": 0,
      "minutes_included": 500,
      "overage_allowed": false,
      "features": ["Solo Transcripción", "500 minutos/mes"]
    },
    {
      "tier": "starter",
      "name": "Starter",
      "price_monthly": 49,
      "minutes_included": 1000,
      "overage_rate": 0.05,
      "overage_allowed": true,
      "features": ["Análisis de Cumplimiento de 16 Puntos", "1,000 minutos/mes", "Soporte por Email"]
    },
    {
      "tier": "growth",
      "name": "Growth",
      "price_monthly": 199,
      "minutes_included": 5000,
      "overage_rate": 0.04,
      "overage_allowed": true,
      "features": ["Análisis Avanzado con IA", "5,000 minutos/mes", "Soporte Prioritario"]
    }
  ]
}

Crear Checkout

Crear sesión de Stripe Checkout para suscribirse a un nivel pago.

Endpoint

POST /api/v1/billing/checkout

Autenticación

Solo token JWT

Request Body

{
  "tier": "starter",
  "success_url": "https://tu-app.com/success",
  "cancel_url": "https://tu-app.com/cancel"
}

Response

{
  "checkout_url": "https://checkout.stripe.com/c/pay/...",
  "session_id": "cs_test_..."
}

Ejemplo

response = requests.post(
    "https://api.callcov.com/api/v1/billing/checkout",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "tier": "starter",
        "success_url": "https://miapp.com/success",
        "cancel_url": "https://miapp.com/cancel"
    }
)

# Redirigir usuario a checkout_url
checkout_url = response.json()['checkout_url']

Portal del Cliente

Crear sesión del Portal del Cliente de Stripe para administrar facturación.

Endpoint

POST /api/v1/billing/portal

Autenticación

Solo token JWT

Request Body

{
  "return_url": "https://tu-app.com/settings"
}

Response

{
  "portal_url": "https://billing.stripe.com/p/session/..."
}

Qué Pueden Hacer los Usuarios en el Portal

Actualizar método de pago
Ver historial de facturación
Descargar facturas
Cancelar suscripción
Actualizar suscripción

Cancelar Suscripción

Cancelar la suscripción paga actual.

Endpoint

POST /api/v1/billing/subscription/cancel

Autenticación

Solo token JWT

Parámetros de Query

Parámetro	Tipo	Default	Descripción
`at_period_end`	boolean	true	Cancelar al final del período (true) o inmediatamente (false)

Response

{
  "message": "La suscripción será cancelada al final del período de facturación actual",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
}

Ejemplo

# Cancelar al final del período (default)
response = requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/cancel",
    headers={"Authorization": f"Bearer {access_token}"}
)

# Cancelar inmediatamente
response = requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/cancel?at_period_end=false",
    headers={"Authorization": f"Bearer {access_token}"}
)

Reactivar Suscripción

Reactivar una suscripción programada para cancelación.

Endpoint

POST /api/v1/billing/subscription/reactivate

Autenticación

Solo token JWT

Response

{
  "message": "Suscripción reactivada exitosamente",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
}

Solo Funciona para Cancelaciones Programadas

Esto solo funciona si la suscripción está programada para cancelarse al final del período. No se puede reactivar una suscripción ya cancelada.

Actualizar Suscripción

Actualizar a un nivel superior.

Endpoint

POST /api/v1/billing/subscription/upgrade

Autenticación

Solo token JWT

Request Body

{
  "tier": "growth"
}

Response

Devuelve suscripción actualizada (mismo formato que Obtener Suscripción).

Rutas de Actualización

Gratuito → Starter ✅
Gratuito → Growth ✅
Starter → Growth ✅

Cómo Funcionan las Actualizaciones

Efecto inmediato: Límites de uso actualizados inmediatamente
Facturación prorrateada: Se cobra monto prorrateado por el resto del período
Rollover de minutos: Los minutos no usados del nivel anterior se pierden
Nuevo ciclo de facturación: El próximo cargo será por el precio completo del nuevo nivel

Ejemplo

response = requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/upgrade",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"tier": "growth"}
)

subscription = response.json()
print(f"Actualizado a {subscription['tier']}")
print(f"Nuevo límite: {subscription['minutes_included']} minutos")

Degradar Suscripción

Degradar a un nivel inferior (programado para el final del período).

Endpoint

POST /api/v1/billing/subscription/downgrade

Autenticación

Solo token JWT

Request Body

{
  "tier": "starter"
}

Response

{
  "message": "La suscripción será degradada al nivel starter al final del período de facturación actual",
  "current_period_end": "2024-02-01T00:00:00Z",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
}

Rutas de Degradación

Growth → Starter ✅
Growth → Gratuito ✅
Starter → Gratuito ✅

Cómo Funcionan las Degradaciones

Final del período: Toma efecto al final del ciclo de facturación actual
Sin reembolsos: Continuar usando el nivel actual hasta el final del período
Aplican nuevos límites: Los límites más bajos comienzan en el próximo ciclo de facturación
Degradar a Gratuito: Cancela la suscripción de Stripe

Obtener Facturas

Obtener historial de facturas de facturación desde Stripe.

Endpoint

GET /api/v1/billing/invoices

Autenticación

Solo token JWT

Parámetros de Query

Parámetro	Tipo	Default	Descripción
`limit`	integer	12	Número de facturas a devolver

Response

{
  "invoices": [
    {
      "id": "in_1234567890",
      "invoice_number": "ABC-1234",
      "status": "paid",
      "amount_due": 49.00,
      "amount_paid": 49.00,
      "total": 49.00,
      "currency": "USD",
      "created": 1704067200,
      "period_start": 1704067200,
      "period_end": 1706745600,
      "invoice_pdf": "https://pay.stripe.com/invoice/.../pdf",
      "hosted_invoice_url": "https://invoice.stripe.com/i/...",
      "description": "Suscripción mensual",
      "lines": [
        {
          "description": "Plan Starter × 1",
          "amount": 49.00,
          "quantity": 1,
          "period_start": 1704067200,
          "period_end": 1706745600
        }
      ]
    }
  ],
  "has_more": false
}

Flujos de Trabajo Comunes

Primera Suscripción

# 1. Obtener niveles disponibles
tiers = requests.get("https://api.callcov.com/api/v1/billing/tiers").json()

# 2. Crear sesión de checkout
checkout = requests.post(
    "https://api.callcov.com/api/v1/billing/checkout",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "tier": "starter",
        "success_url": "https://miapp.com/success",
        "cancel_url": "https://miapp.com/cancel"
    }
).json()

# 3. Redirigir usuario a checkout_url
redirect_to(checkout['checkout_url'])

# 4. Después del pago exitoso, el usuario es redirigido a success_url
# 5. Verificar estado de suscripción
subscription = requests.get(
    "https://api.callcov.com/api/v1/billing/subscription",
    headers={"Authorization": f"Bearer {access_token}"}
).json()

Monitorear Uso

# Obtener resumen de facturación
summary = requests.get(
    "https://api.callcov.com/api/v1/billing/subscription/summary",
    headers={"Authorization": f"Bearer {access_token}"}
).json()

usage_pct = summary['usage']['usage_percentage']
remaining = summary['usage']['minutes_remaining']

if usage_pct > 80:
    print(f"⚠️  Advertencia: {usage_pct}% de minutos usados")
    print(f"Restantes: {remaining} minutos")

Cambiar Suscripción

# Actualizar inmediatamente
requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/upgrade",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"tier": "growth"}
)

# Degradar al final del período
requests.post(
    "https://api.callcov.com/api/v1/billing/subscription/downgrade",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"tier": "starter"}
)

Códigos de Error

Estado	Error	Solución
400	No se puede crear checkout para nivel gratuito	Usar endpoint de actualización en su lugar
400	Ya tiene suscripción activa	Usar endpoints de actualización/degradación
400	No se puede actualizar al mismo nivel o inferior	Verificar nivel actual primero
400	No se encontró cliente de Stripe	Suscribirse a plan pago primero
402	Límite de uso excedido	Actualizar plan o esperar al próximo ciclo de facturación
500	Operación de Stripe falló	Reintentar o contactar soporte

Relacionado

Crear Análisis - Enviar audio para análisis (consume minutos)
Claves de API - Crear claves de API para acceso programático
Guía de Inicio Rápido - Guía de configuración completa

Niveles de Facturación​

Enlaces Rápidos​

Obtener Suscripción​

Endpoint​

Autenticación​

Response​

Resumen de Facturación​

Endpoint​

Autenticación​

Response​

Obtener Niveles​

Endpoint​

Autenticación​

Response​

Crear Checkout​

Endpoint​

Autenticación​

Request Body​

Response​

Ejemplo​

Portal del Cliente​

Endpoint​

Autenticación​

Request Body​

Response​

Qué Pueden Hacer los Usuarios en el Portal​

Cancelar Suscripción​

Endpoint​

Autenticación​

Parámetros de Query​

Response​

Ejemplo​

Reactivar Suscripción​

Endpoint​

Autenticación​

Response​

Actualizar Suscripción​

Endpoint​

Autenticación​

Request Body​

Response​

Rutas de Actualización​

Cómo Funcionan las Actualizaciones​

Ejemplo​

Degradar Suscripción​

Endpoint​

Autenticación​

Request Body​

Response​

Rutas de Degradación​

Cómo Funcionan las Degradaciones​

Obtener Facturas​

Endpoint​

Autenticación​

Parámetros de Query​

Response​

Flujos de Trabajo Comunes​

Primera Suscripción​

Monitorear Uso​

Cambiar Suscripción​

Códigos de Error​

Relacionado​

Niveles de Facturación

Enlaces Rápidos

Obtener Suscripción

Endpoint

Autenticación

Response

Resumen de Facturación

Endpoint

Autenticación

Response

Obtener Niveles

Endpoint

Autenticación

Response

Crear Checkout

Endpoint

Autenticación

Request Body

Response

Ejemplo

Portal del Cliente

Endpoint

Autenticación

Request Body

Response

Qué Pueden Hacer los Usuarios en el Portal

Cancelar Suscripción

Endpoint

Autenticación

Parámetros de Query

Response

Ejemplo

Reactivar Suscripción

Endpoint

Autenticación

Response

Actualizar Suscripción

Endpoint

Autenticación

Request Body

Response

Rutas de Actualización

Cómo Funcionan las Actualizaciones

Ejemplo

Degradar Suscripción

Endpoint

Autenticación

Request Body

Response

Rutas de Degradación

Cómo Funcionan las Degradaciones

Obtener Facturas

Endpoint

Autenticación

Parámetros de Query

Response

Flujos de Trabajo Comunes

Primera Suscripción

Monitorear Uso

Cambiar Suscripción

Códigos de Error

Relacionado