Integración paso a paso: configurar cobros automáticos con nuestra API

La implementación de un sistema robusto de cobros automáticos es fundamental para cualquier negocio basado en suscripciones o pagos recurrentes. En esta guía técnica, te mostraremos cómo integrar Mekebook en tu plataforma existente para automatizar completamente el ciclo de facturación recurrente, desde la creación de clientes y planes hasta la gestión de eventos de pago a través de webhooks.

Esta guía está dirigida a desarrolladores y equipos técnicos, y asume conocimientos básicos de APIs RESTful, JSON y desarrollo web. Todos los ejemplos de código están disponibles en múltiples lenguajes de programación, aunque en esta guía utilizaremos principalmente JavaScript/Node.js para las ilustraciones.

Requisitos previos

Antes de comenzar la integración, asegúrate de tener lo siguiente:

Una cuenta de Mekebook (puedes contactarnos para crear una cuenta de prueba)
Claves de API para el entorno de sandbox (pruebas)
Acceso al panel de control de Mekebook
Conocimientos básicos de HTTP y APIs REST
Un servidor capaz de recibir webhooks (para la implementación completa)

Paso 1: Configuración inicial y autenticación

El primer paso es configurar tu entorno de desarrollo para comunicarte con la API de Mekebook.

Obtención de claves API

Accede al panel de control de Mekebook y navega a Configuración > API Keys. Aquí encontrarás dos conjuntos de claves:

Claves de Sandbox: Para desarrollo y pruebas. No realizan transacciones reales.
Claves de Producción: Para el entorno real. Utilizan estas solo cuando tu integración esté completamente probada.

Cada conjunto incluye:

API Key: Se incluye en el encabezado de cada solicitud para identificar tu cuenta.
API Secret: Se utiliza para firmar solicitudes. Nunca debe exponerse públicamente.

Configuración básica del cliente API

A continuación, configura un cliente HTTP para comunicarte con la API. Aquí hay un ejemplo utilizando Node.js con Axios:


const axios = require('axios');

const Mekebook = axios.create({
  baseURL: 'https://api.Mekebook.com/v1',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.Mekebook_API_KEY}`,
    'X-Api-Version': '2025-11-01'
  }
});


const handleApiError = (error) => {
  if (error.response) {
   
   
    console.error('Error de API:', error.response.data);
    console.error('Código de estado:', error.response.status);
  } else if (error.request) {
   
    console.error('No se recibió respuesta:', error.request);
  } else {
   
    console.error('Error:', error.message);
  }
  throw error;
};

Recomendamos utilizar variables de entorno para almacenar tus claves API, nunca las incluyas directamente en el código fuente.

Paso 2: Creación y gestión de clientes

El primer objeto que necesitas crear en Mekebook es el cliente, que representa a la persona o empresa que pagará por tus servicios.

Crear un nuevo cliente


async function createCustomer(customerData) {
  try {
    const response = await Mekebook.post('/customers', customerData);
    console.log('Cliente creado:', response.data);
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}


const newCustomer = {
  email: 'cliente@ejemplo.com',
  name: 'Empresa Ejemplo S.L.',
  tax_id: 'B12345678',
  billing_address: {
    line1: 'Calle Principal 123',
    postal_code: '28001',
    city: 'Madrid',
    country: 'ES'
  },
  metadata: {
    internal_id: 'CL-12345',
    source: 'website_signup'
  }
};


createCustomer(newCustomer)
  .then(customer => {
    console.log(`Cliente creado con ID: ${customer.id}`);
  })
  .catch(err => {
    console.error('Error al crear cliente:', err);
  });

El objeto cliente creado contendrá un ID único (cus_12345abcde) que utilizarás para todas las operaciones relacionadas con este cliente.

Añadir un método de pago al cliente

Para procesar pagos recurrentes, necesitas asociar al menos un método de pago al cliente. Mekebook ofrece dos enfoques:

1. Enfoque seguro con tokenización frontend (recomendado)

Este método utiliza nuestro SDK de JavaScript para tokenizar los datos de pago en el navegador del cliente, sin que los datos sensibles pasen por tu servidor.


<form id="payment-form">
  <div id="card-element"></div>
  <button type="submit">Guardar método de pago</button>
</form>

<script src="https://js.Mekebook.com/v1"></script>
<script>
  const Mekebook = Mekebook('pk_test_51H...');
  
  const cardElement = Mekebook.elements.create('card');
  cardElement.mount('#card-element');
  
  const form = document.getElementById('payment-form');
  
  form.addEventListener('submit', async (event) => {
    event.preventDefault();
    
    const { token, error } = await Mekebook.createToken(cardElement);
    
    if (error) {
      console.error('Error al crear token:', error);
    } else {
     
      fetch('/api/save-payment-method', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          customerId: 'cus_12345abcde',
          paymentToken: token.id
        })
      })
      .then(response => response.json())
      .then(data => {
        console.log('Método de pago guardado:', data);
      })
      .catch(err => {
        console.error('Error al guardar método de pago:', err);
      });
    }
  });
</script>

Luego, en tu backend:


async function savePaymentMethod(customerId, paymentToken) {
  try {
    const response = await Mekebook.post(`/customers/${customerId}/payment_methods`, {
      token: paymentToken
    });
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}

2. Enfoque directo desde backend (solo para casos específicos)

Este método requiere que tu servidor maneje datos sensibles de pago, por lo que solo debe usarse en escenarios específicos donde la tokenización frontend no es posible.



async function createPaymentMethodDirect(customerId, paymentData) {
  try {
    const response = await Mekebook.post(`/customers/${customerId}/payment_methods`, {
      type: 'card',
      card: {
        number: '4242424242424242',
        exp_month: 12,
        exp_year: 2028,
        cvc: '123'
      }
    });
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}

El método de pago creado tendrá un ID único (pm_67890fghij) que utilizarás para crear suscripciones.

Paso 3: Configuración de planes y productos

Antes de crear suscripciones, debes definir los planes disponibles en tu plataforma.

Crear un producto

Los productos representan los servicios o niveles de acceso que ofreces:

async function createProduct(productData) {
  try {
    const response = await Mekebook.post('/products', productData);
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}


const newProduct = {
  name: 'Software Premium',
  description: 'Acceso completo a todas las funcionalidades',
  metadata: {
    features: 'unlimited_projects,team_access,priority_support'
  }
};

createProduct(newProduct)
  .then(product => {
    console.log(`Producto creado con ID: ${product.id}`);
  });

Crear planes de precios

Los planes definen cuánto y con qué frecuencia se cobra a los clientes por cada producto:

async function createPlan(planData) {
  try {
    const response = await Mekebook.post('/plans', planData);
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}


const monthlyPlan = {
  product_id: 'prod_12345abcde',
  name: 'Plan Premium Mensual',
  amount: 2990,
  currency: 'eur',
  interval: 'month',
  interval_count: 1,
  metadata: {
    plan_code: 'premium_monthly'
  }
};


const yearlyPlan = {
  product_id: 'prod_12345abcde',
  name: 'Plan Premium Anual',
  amount: 29900,
  currency: 'eur',
  interval: 'year',
  interval_count: 1,
  metadata: {
    plan_code: 'premium_yearly',
    discount: '15%'
  }
};


Promise.all([
  createPlan(monthlyPlan),
  createPlan(yearlyPlan)
])
.then(([monthly, yearly]) => {
  console.log(`Plan mensual creado con ID: ${monthly.id}`);
  console.log(`Plan anual creado con ID: ${yearly.id}`);
});

Paso 4: Creación y gestión de suscripciones

Una vez que tienes clientes con métodos de pago y planes definidos, puedes crear suscripciones para iniciar los cobros recurrentes.

Crear una suscripción

async function createSubscription(subscriptionData) {
  try {
    const response = await Mekebook.post('/subscriptions', subscriptionData);
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}


const newSubscription = {
  customer_id: 'cus_12345abcde',
  plan_id: 'plan_67890fghij',
  payment_method_id: 'pm_54321zyxwv',
  metadata: {
    source: 'website_checkout',
    promotion: 'summer_deal'
  }
};


const subscriptionWithTrial = {
  customer_id: 'cus_12345abcde',
  plan_id: 'plan_67890fghij',
  payment_method_id: 'pm_54321zyxwv',
  trial_period_days: 14,
  metadata: {
    source: 'free_trial_signup'
  }
};


createSubscription(newSubscription)
  .then(subscription => {
    console.log(`Suscripción creada con ID: ${subscription.id}`);
    console.log(`Estado: ${subscription.status}`);
    console.log(`Próximo cobro: ${subscription.current_period_end}`);
  });

La suscripción creada tendrá un estado inicial (normalmente "active" o "trialing" si hay período de prueba) y fechas que indican cuándo comenzó y cuándo se realizará el próximo cobro.

Gestionar cambios en la suscripción

Durante el ciclo de vida de una suscripción, es común necesitar realizar cambios como upgrades, downgrades o cancelaciones.

Actualizar una suscripción (cambio de plan)

async function updateSubscription(subscriptionId, updateData) {
  try {
    const response = await Mekebook.patch(`/subscriptions/${subscriptionId}`, updateData);
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}


updateSubscription('sub_12345abcde', {
  plan_id: 'plan_premium_plus',
  prorate: true
})
.then(updatedSubscription => {
  console.log(`Suscripción actualizada: ${updatedSubscription.id}`);
  if (updatedSubscription.pending_update) {
    console.log('Cambio programado para el próximo período de facturación');
  } else {
    console.log('Cambio aplicado inmediatamente');
  }
});

Cancelar una suscripción

async function cancelSubscription(subscriptionId, cancelData) {
  try {
    const response = await Mekebook.post(`/subscriptions/${subscriptionId}/cancel`, cancelData);
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}


cancelSubscription('sub_12345abcde', {
  immediate: true,
  reason: 'customer_request',
  feedback: 'Encontró un servicio más económico'
})
.then(result => {
  console.log(`Suscripción cancelada: ${result.status}`);
});


cancelSubscription('sub_12345abcde', {
  immediate: false,
  reason: 'customer_request',
  feedback: 'Volverá en unos meses'
})
.then(result => {
  console.log(`Suscripción programada para cancelación: ${result.cancel_at}`);
});

Paso 5: Configuración de webhooks

Los webhooks son fundamentales para mantener tu sistema sincronizado con los eventos que ocurren en Mekebook, como pagos exitosos, fallos, cancelaciones, etc.

Registrar un endpoint de webhook

Primero, configura la URL donde recibirás las notificaciones:

async function createWebhookEndpoint(endpointData) {
  try {
    const response = await Mekebook.post('/webhook_endpoints', endpointData);
    return response.data;
  } catch (error) {
    return handleApiError(error);
  }
}


createWebhookEndpoint({
  url: 'https://tu-aplicacion.com/webhooks/Mekebook',
  enabled_events: [
    'subscription.created',
    'subscription.updated',
    'subscription.cancelled',
    'payment.succeeded',
    'payment.failed',
    'invoice.created',
    'invoice.paid',
    'customer.updated'
  ],
  description: 'Webhook principal para producción'
})
.then(endpoint => {
  console.log(`Endpoint creado con ID: ${endpoint.id}`);
  console.log(`Secret para verificación: ${endpoint.secret}`);
});

Implementar el controlador de webhooks

A continuación, necesitas crear un endpoint en tu servidor para recibir y procesar estos eventos. Aquí hay un ejemplo utilizando Express.js:

const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');

const app = express();


function verifyWebhookSignature(req, res, next) {
  const payload = req.body;
  const signature = req.headers['x-Mekebook-signature'];
  const webhookSecret = process.env.Mekebook_WEBHOOK_SECRET;
  
  if (!signature) {
    return res.status(400).send('No se proporcionó firma');
  }
  
  try {
   
    const hmac = crypto.createHmac('sha256', webhookSecret);
    const expectedSignature = hmac.update(JSON.stringify(payload)).digest('hex');
    
   
    const valid = crypto.timingSafeEqual(
      Buffer.from(expectedSignature, 'hex'),
      Buffer.from(signature, 'hex')
    );
    
    if (!valid) {
      return res.status(403).send('Firma inválida');
    }
    
    next();
  } catch (err) {
    console.error('Error al verificar firma:', err);
    return res.status(400).send('Error de verificación');
  }
}


app.post('/webhooks/Mekebook',
  bodyParser.json(),
  verifyWebhookSignature,
  async (req, res) => {
   
    res.status(200).send('OK');
    
   
    const event = req.body;
    
    try {
      switch (event.type) {
        case 'subscription.created':
          await handleSubscriptionCreated(event.data.object);
          break;
          
        case 'payment.succeeded':
          await handlePaymentSucceeded(event.data.object);
          break;
          
        case 'payment.failed':
          await handlePaymentFailed(event.data.object);
          break;
          
        case 'subscription.cancelled':
          await handleSubscriptionCancelled(event.data.object);
          break;
          
       
        
        default:
          console.log(`Evento no manejado: ${event.type}`);
      }
    } catch (err) {
      console.error(`Error al procesar evento ${event.type}:`, err);
    }
  }
);


async function handleSubscriptionCreated(subscription) {
 
  console.log(`Activando servicio para cliente ${subscription.customer_id}`);
  await activateService(subscription.customer_id, subscription.plan_id);
}

async function handlePaymentSucceeded(payment) {
 
  console.log(`Pago exitoso: ${payment.id}, monto: ${payment.amount}`);
  await recordPayment(payment);
}

async function handlePaymentFailed(payment) {
 
  console.log(`Pago fallido: ${payment.id}, motivo: ${payment.failure_code}`);
  await recordFailedPayment(payment);
  await notifySupport(payment);
}

async function handleSubscriptionCancelled(subscription) {
 
  console.log(`Desactivando servicio para cliente ${subscription.customer_id}`);
  await deactivateService(subscription.customer_id);
}


app.listen(3000, () => {
  console.log('Servidor escuchando en puerto 3000');
});

Es importante responder rápidamente a los webhooks (código 200) y procesar la lógica de negocio de forma asíncrona para evitar tiempos de espera.

Flujo completo de eventos con webhooks

Para ilustrar cómo funciona todo el sistema en conjunto, aquí tienes un ejemplo de la secuencia típica de eventos para una suscripción:

Creación de suscripción: Recibes subscription.created
Generación de primera factura: Recibes invoice.created
Intento de pago inicial: Recibes payment.succeeded o payment.failed
Factura pagada: Recibes invoice.paid (si el pago fue exitoso)
Período de facturación termina: El ciclo se repite desde el paso 2

Para fallos de pago, recibirás eventos adicionales relacionados con el proceso de dunning (reintentos):

Inicio de dunning: Recibes dunning.started
Reintento de pago: Recibes payment.succeeded o payment.failed por cada intento
Fin de dunning: Recibes dunning.succeeded o dunning.failed
Cambio de estado de suscripción: Recibes subscription.updated o subscription.cancelled según el resultado

Paso 6: Pruebas y validación

Antes de pasar a producción, es crucial probar exhaustivamente la integración utilizando el entorno de sandbox.

Tarjetas de prueba

Mekebook proporciona tarjetas de prueba para simular diferentes escenarios:

4242 4242 4242 4242 - Pago exitoso
4000 0000 0000 0002 - Tarjeta rechazada (genérico)
4000 0000 0000 9995 - Fondos insuficientes
4000 0000 0000 0069 - Tarjeta caducada
4000 0000 0000 9987 - Tarjeta perdida
4000 0000 0000 3220 - Procesamiento 3D Secure requerido

Simulación de eventos de ciclo de vida

El panel de control de sandbox te permite simular eventos como:

Fallos de pago
Cancelaciones
Disputas (chargebacks)
Actualizaciones automáticas de tarjetas

Utiliza estas herramientas para verificar que tu sistema maneja correctamente todos los escenarios posibles.

Checklist de validación

Antes de pasar a producción, verifica que:

Los clientes se crean correctamente con toda la información necesaria
Los métodos de pago se tokenizán y almacenan de forma segura
Las suscripciones se crean y activan según lo esperado
Los webhooks se reciben y procesan correctamente
El sistema maneja adecuadamente los fallos de pago y reintentos
Las cancelaciones y cambios de plan funcionan como se espera
La experiencia de usuario es fluida en todos los escenarios

Paso 7: Migración a producción

Una vez que has validado completamente tu integración en el entorno de sandbox, puedes proceder a la migración a producción.

Cambio de claves API

Sustituye las claves de sandbox por las de producción en tu configuración:


const Mekebook = axios.create({
  baseURL: 'https://api.Mekebook.com/v1',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.Mekebook_LIVE_API_KEY}`,
    'X-Api-Version': '2025-11-01'
  }
});

Configuración de webhooks de producción

Crea nuevos endpoints de webhook específicos para el entorno de producción:


createWebhookEndpoint({
  url: 'https://tu-aplicacion.com/webhooks/Mekebook/production',
  enabled_events: [
    'subscription.created',
    'subscription.updated',
    'subscription.cancelled',
    'payment.succeeded',
    'payment.failed',
    'invoice.created',
    'invoice.paid',
    'customer.updated'
  ],
  description: 'Webhook principal para producción'
})
.then(endpoint => {
  console.log(`Endpoint de producción creado con ID: ${endpoint.id}`);
  console.log(`Secret para verificación: ${endpoint.secret}`);
});

Migración de datos (si es necesario)

Si ya tienes clientes con suscripciones activas en otro sistema, deberás migrarlos a Mekebook. Esto generalmente implica:

Crear clientes en Mekebook para cada cliente existente
Migrar información de pago (requiere autorización del cliente)
Crear suscripciones con las fechas de facturación correctas
Sincronizar historiales de facturación (opcional)

Mekebook ofrece herramientas y API específicas para migraciones que facilitan este proceso. Contacta con nuestro equipo de soporte para obtener asistencia personalizada en migraciones complejas.

Mejores prácticas y consideraciones adicionales

Para finalizar, aquí tienes algunas recomendaciones adicionales para una integración óptima:

Seguridad

Nunca almacenes datos completos de tarjetas en tus servidores
Utiliza siempre HTTPS para todas las comunicaciones
Implementa una rotación regular de claves API
Verifica siempre las firmas de los webhooks
Limita el acceso a las claves API solo al personal necesario

Gestión de errores

Implementa reintentos con backoff exponencial para errores 5xx
Monitoriza activamente los errores de API y webhooks
Configura alertas para tasas de error anormales
Mantén logs detallados para facilitar la depuración

Experiencia de usuario

Proporciona mensajes de error claros y accionables
Implementa formularios de pago con validación en tiempo real
Ofrece un portal de autoservicio para que los clientes gestionen sus suscripciones
Personaliza las comunicaciones de facturación y dunning

Optimización

Utiliza el campo metadata para almacenar información específica de tu aplicación
Implementa idempotencia en todas las operaciones críticas
Configura webhooks solo para los eventos que realmente necesitas procesar
Considera la implementación de un sistema de colas para procesar webhooks de alto volumen

Conclusión

La integración de Mekebook en tu plataforma te permite automatizar completamente el ciclo de facturación recurrente, desde la captura inicial del método de pago hasta la gestión de todo el ciclo de vida de la suscripción. Con esta guía, deberías tener una comprensión clara de los pasos necesarios para implementar una integración robusta y escalable.

Recuerda que nuestro equipo de soporte está disponible para ayudarte en cualquier fase del proceso de integración. No dudes en contactarnos si tienes preguntas específicas o necesitas asistencia personalizada.