Créditos y Facturación

Esta guía explica cómo funcionan los créditos en la API de MasLeads.

Sistema de Créditos

MasLeads utiliza un sistema de créditos prepago. Cada operación consume créditos de tu saldo.

Coste por Tipo de Datos

Tipo Créditos Descripción
email 1 Email corporativo verificado
phone 1 Teléfono directo
email + phone 2 Ambos datos

Ejemplo de Cálculo

Job con 50 leads solicitando email + phone:
50 leads × 2 créditos = 100 créditos reservados

Flujo de Créditos

1. Reserva Anticipada

Al crear un job, los créditos se reservan inmediatamente:

POST /api/v1/enrich/leads

{
  "leads": [...50 leads...],
  "enrichment_type": ["email", "phone"]
}

{
  "job_id": "job_abc123",
  "credits_reserved": 100,
  "status": "pending"
}

Tu saldo: 1000 → 900 (disponible)

2. Consumo Real

Cuando el job se completa, se calculan los créditos reales:

{
  "job_id": "job_abc123",
  "status": "completed",
  "total_leads": 50,
  "leads_found": 40,
  "leads_not_found": 10,
  "credits_used": 80,
  "credits_refunded": 20
}

3. Reembolso Automático

Los créditos de leads not_found o error se reembolsan automáticamente:

Resultado Créditos
found Consumidos
not_found Reembolsados
error Reembolsados

Tu saldo final: 900 + 20 (reembolso) = 920 disponibles

Consultar Saldo

GET /api/v1/usage

{
  "available_credits": 920,
  "reserved_credits": 0,
  "used_credits": 80,
  "total_credits": 1000,
  "plan_type": "professional",
  "billing_period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  }
}

Campos Explicados

Campo Descripción
available_credits Créditos disponibles para usar
reserved_credits Créditos reservados por jobs en progreso
used_credits Créditos consumidos este período
total_credits Créditos totales del período

Error: Créditos Insuficientes

Si no tienes suficientes créditos, recibirás 402 Payment Required:

{
  "error": "insufficient_credits",
  "message": "Not enough credits. Available: 50, Required: 200"
}

Cómo Manejar

def create_job_safely(leads, enrichment_type):
    # Calcular créditos necesarios
    credits_per_lead = len(enrichment_type)
    credits_needed = len(leads) * credits_per_lead

    # Verificar saldo
    usage = api.get_usage()
    if usage['available_credits'] < credits_needed:
        raise InsufficientCreditsError(
            f"Need {credits_needed}, have {usage['available_credits']}"
        )

    # Crear job
    return api.create_job(leads, enrichment_type)

Comprar Más Créditos

Para adquirir más créditos o información sobre paquetes disponibles, ve a la sección de facturación en tu cuenta o contacta con nuestro equipo comercial.

Créditos por Plan

Cada plan incluye créditos según lo contratado. La cantidad de créditos y las condiciones de rollover dependen del plan específico.

¿Qué es Rollover?

  • Sin rollover: Los créditos no usados expiran al final del período
  • Con rollover: Los créditos no usados se acumulan (según condiciones del plan)

Historial de Uso

En tu cuenta

En la sección Perfil → API → Uso puedes ver:

  • Uso diario/semanal/mensual
  • Desglose por job
  • Reembolsos aplicados
  • Gráficos de tendencia

Via API (próximamente)

GET /api/v1/usage/history?period=month

Alertas de Créditos Bajos

Puedes configurar alertas en Perfil → API → Alertas:

  • Email cuando créditos < 20%
  • Email cuando créditos < 10%
  • Webhook de alerta (opcional)

Facturación

Facturas

Las facturas están disponibles en la sección de facturación de tu cuenta.

Incluyen: - Créditos comprados - Créditos del plan - Impuestos aplicables - Descuentos (si aplica)

Métodos de Pago

  • Tarjeta de crédito/débito
  • Transferencia bancaria
  • Domiciliación SEPA (UE)

FAQ

¿Los créditos caducan?

  • Créditos del plan: Depende del plan (ver rollover)
  • Créditos comprados: No caducan mientras la cuenta esté activa

¿Qué pasa si un job falla completamente?

Todos los créditos se reembolsan:

{
  "job_id": "job_xyz",
  "status": "failed",
  "credits_reserved": 100,
  "credits_refunded": 100,
  "error": "Internal processing error"
}

¿Se cobran créditos por el mismo lead dos veces?

Sí, cada procesamiento consume créditos independientemente. Si envías el mismo lead en dos jobs diferentes, se cobrarán ambos.

Tip: Implementa deduplicación en tu lado antes de enviar leads.

¿Hay descuentos por volumen?

Sí. Los paquetes más grandes tienen mejor precio por crédito. Para volúmenes muy altos, contacta con nuestro equipo comercial para precios personalizados.

¿Puedo obtener un reembolso de créditos comprados?

Los créditos comprados no son reembolsables, pero nunca caducan.

Anterior: ← Rate Limiting | Siguiente: Manejo de Errores →