Conciliación Automática de Pagos en Turismo y Hotelería: Sincronización Contable en VikBooking con Mercado Pago y Pasarelas Locales

En la industria de la hospitalidad y el turismo, la gestión financiera no concluye cuando el huésped completa el pago de su reserva con tarjeta de crédito o transferencia bancaria. Para el departamento contable de un hotel, hostal o cadena de cabañas vacacionales, ese momento marca apenas el inicio de un laberinto operativo: la conciliación de pagos.

Cuando un hotel utiliza VikBooking sobre WordPress junto a procesadores como Mercado Pago, existe una brecha notable entre el valor bruto de la reserva (Gross Booking Value) y el dinero real que ingresa a la cuenta bancaria del hotel semanas después. Comisiones de la pasarela (entre el 2.99% y el 3.49% + IVA), retenciones impositivas obligatorias en origen (ReteFuente, ReteIVA y ReteICA en Colombia, percepciones de IIBB en Argentina, retenciones de ISR en México) y tarifas de liberación inmediata crean desajustes continuos en los libros contables.

Muchos hoteles intentan conciliar estos valores descargando archivos CSV de Mercado Pago y cruzando celdas manualmente en hojas de cálculo de Excel. Este método manual no solo consume decenas de horas al mes, sino que provoca errores humanos, fugas de capital y retrasos en el cierre contable fiscal.

En este artículo técnico para desarrolladores, directores financieros (CFOs) y administradores hoteleros, analizaremos la arquitectura de conciliación bancaria automatizada, cómo consumir la API de Balance y Reportes de Liquidación (Settlement Reports) de Mercado Pago y cómo sincronizar automáticamente los estados financieros dentro de la base de datos de VikBooking.

---

1. La Ecuación Contable del Pago Hotelero en América Latina

Para diseñar un sistema automatizado de conciliación, primero debemos modelar matemáticamente el flujo de fondos de cada transacción:

┌────────────────────────────────────────────────────────────────────────┐
│                   Desglose Financiero de una Reserva                   │
└────────────────────────────────────────────────────────────────────────┘

  [Tarifa Neta de la Habitación]          $ 1,000,000 COP
+ [Impuestos Locales / IVA 19%]           $   190,000 COP
---------------------------------------------------------
= [Monto Cobrado al Huésped (Bruto)]      $ 1,190,000 COP (Registrado en VikBooking)

- [Comisión Mercado Pago (3.19% + IVA)]  -$    45,208 COP
- [Retención en la Fuente (ReteFuente)]  -$    17,850 COP
- [Retención de IVA (ReteIVA 15%)]       -$     5,415 COP
- [Retención de ICA (ReteICA)]           -$     4,926 COP
---------------------------------------------------------
= [Monto Neto Liquidado en Banco]         $ 1,116,601 COP (Fondos Disponibles)

Si el software de reservas solo registra que se cobraron $1,190,000 COP, pero el banco recibe $1,116,601 COP, existe una discrepancia contable de $73,399 COP. Sin un software que registre de forma transparente el desglose de cada deducción fiscal y comisión financiera asociado al booking_id, los balances de fin de mes jamás cuadrarán ante las autoridades tributarias (DIAN, SAT o AFIP).

---

2. Arquitectura de Conciliación: Dos Capas de Sincronización

La conciliación profesional no depende únicamente del webhook instantáneo. Requiere una arquitectura desacoplada en dos etapas:

[Etapa 1: En Tiempo Real (Webhooks IPN)]
  Mercado Pago ──► Webhook Listener ──► Marca Reserva como PAGADA en VikBooking
                                        (Garantiza el Check-in del Huésped)

[Etapa 2: Nocturna / Diferida (Settlement Reports API)]
  Cron Job / CLI ──► Consulta /v1/balance/history en Mercado Pago
                     │
                     ▼ (Cruza External Reference: "VB-4589")
                     Calcula Comisiones Netas y Retenciones Impositivas
                     │
                     ▼
                     Actualiza Libro Diario y Tabla Contable en WordPress

1. Capa Transaccional Operativa (Tiempo Real): Verifica que la tarjeta fue aprobada y confirma la habitación en VikBooking para evitar sobreventas (overbooking).
2. Capa de Conciliación Financiera (Cierre Diario): Se ejecuta de manera programada (típicamente a las 02:00 AM) cuando Mercado Pago consolida los reportes de liquidación. Esta capa descarga los identificadores de liquidación (settlement IDs), clasifica las deducciones impositivas y marca la transacción como CONCILIADA.

---

3. Consumo de la API de Balance y Movimientos de Mercado Pago

Mercado Pago ofrece el endpoint /v1/balance/history para auditar todos los movimientos financieros asociados a una cuenta de recaudación. A diferencia del endpoint de pagos común /v1/payments/{id}, este recurso expone el detalle exacto de las retenciones impositivas y el costo financiero de cada operación:

# Consulta de movimientos financieros liquidados en las últimas 24 horas
curl -X GET "https://api.mercadopago.com/v1/balance/history?begin_date=2026-09-06T00:00:00Z&end_date=2026-09-06T23:59:59Z" \
  -H "Authorization: Bearer TEST-789456123-APP-TOKEN" \
  -H "Content-Type: application/json"

El payload devuelto contiene un desglose estructurado dentro de la matriz charges_details:

{
  "id": 987654321,
  "date_created": "2026-09-06T14:32:10.000-04:00",
  "date_approved": "2026-09-06T14:33:05.000-04:00",
  "date_released": "2026-09-08T00:00:00.000-04:00",
  "external_reference": "VB-4589",
  "transaction_amount": 1190000.00,
  "net_amount": 1116601.00,
  "fee_details": [
    {
      "type": "mercadopago_fee",
      "amount": 45208.00,
      "fee_payer": "collector"
    }
  ],
  "charges_details": [
    {
      "type": "tax_withholding",
      "name": "rete_fuente",
      "amount": 17850.00
    },
    {
      "type": "tax_withholding",
      "name": "rete_iva",
      "amount": 5415.00
    },
    {
      "type": "tax_withholding",
      "name": "rete_ica",
      "amount": 4926.00
    }
  ]
}

---

4. Implementación en WordPress: Comando de Conciliación Automática (WP-CLI)

Para procesar grandes volúmenes de transacciones sin sufrir limitaciones de tiempo de ejecución de PHP en el navegador (max_execution_time), la mejor práctica en WordPress es implementar un comando WP-CLI o un worker que se invoque desde un cron del sistema operativo Linux (crontab).

A continuación presentamos la implementación del motor de conciliación para VikBooking:

<?php
/**
 * Plugin Name: DoneAPI - Conciliador Automático VikBooking & Mercado Pago
 * Description: Motor de conciliación financiera automatizada para reservas hoteleras en VikBooking.
 * Version: 2.0.0
 * Author: DoneAPI Engineering Team
 */

if (!defined('ABSPATH')) {
    exit;
}

if (defined('WP_CLI') && WP_CLI) {
    WP_CLI::add_command('doneapi reconcile-payments', 'DoneAPI_Reconcile_Command');
}

class DoneAPI_Reconcile_Command {
    /**
     * Ejecuta la conciliación nocturna de pagos entre Mercado Pago y VikBooking
     * 
     * ## OPCIONES
     * [--days=<days>]
     * : Número de días hacia atrás a conciliar (por defecto 1).
     * 
     * ## EJEMPLO
     *     wp doneapi reconcile-payments --days=2
     */
    public function __invoke($args, $assoc_args) {
        $days = isset($assoc_args['days']) ? intval($assoc_args['days']) : 1;
        WP_CLI::line("Iniciando conciliación financiera para los últimos {$days} días...");

        $access_token = defined('MERCADOPAGO_ACCESS_TOKEN') ? MERCADOPAGO_ACCESS_TOKEN : get_option('doneapi_mp_access_token');
        if (!$access_token) {
            WP_CLI::error("Access Token de Mercado Pago no configurado.");
            return;
        }

        $begin_date = gmdate('Y-m-d\TH:i:s\Z', strtotime("-{$days} days"));
        $end_date   = gmdate('Y-m-d\TH:i:s\Z');

        $url = add_query_arg([
            'begin_date' => $begin_date,
            'end_date'   => $end_date,
            'status'     => 'approved',
        ], 'https://api.mercadopago.com/v1/payments/search');

        $response = wp_remote_get($url, [
            'headers' => [
                'Authorization' => "Bearer {$access_token}",
                'Content-Type'  => 'application/json',
            ],
            'timeout' => 30,
        ]);

        if (is_wp_error($response)) {
            WP_CLI::error("Fallo al conectar con la API de Mercado Pago: " . $response->get_error_message());
            return;
        }

        $body = json_decode(wp_remote_retrieve_body($response), true);
        $results = $body['results'] ?? [];

        WP_CLI::line("Se encontraron " . count($results) . " transacciones aprobadas en el periodo.");

        global $wpdb;
        $reconciled_count = 0;

        foreach ($results as $payment) {
            $external_ref = $payment['external_reference'] ?? null;
            if (!$external_ref || strpos($external_ref, 'VB-') !== 0) {
                continue; // No pertenece a VikBooking
            }

            $booking_id = intval(str_replace('VB-', '', $external_ref));
            $gross_amount = floatval($payment['transaction_amount']);
            $net_amount   = floatval($payment['net_received_amount'] ?? 0);
            $mp_fee       = 0.0;
            $taxes        = 0.0;

            if (isset($payment['fee_details'])) {
                foreach ($payment['fee_details'] as $fee) {
                    $mp_fee += floatval($fee['amount']);
                }
            }

            if (isset($payment['charges_details'])) {
                foreach ($payment['charges_details'] as $charge) {
                    if ($charge['type'] === 'tax_withholding') {
                        $taxes += floatval($charge['amount']);
                    }
                }
            }

            // Actualizar tabla contable de auditoría
            $table_reconcile = $wpdb->prefix . 'doneapi_hotel_reconciled_ledger';
            $wpdb->replace($table_reconcile, [
                'booking_id'     => $booking_id,
                'payment_id'     => $payment['id'],
                'gross_amount'   => $gross_amount,
                'gateway_fee'    => $mp_fee,
                'tax_withheld'   => $taxes,
                'net_amount'     => $net_amount,
                'reconciled_at'  => current_time('mysql'),
                'payment_method' => $payment['payment_method_id'] ?? 'unknown',
                'status'         => 'RECONCILED'
            ], ['%d', '%s', '%f', '%f', '%f', '%f', '%s', '%s', '%s']);

            // Añadir nota de auditoría interna en VikBooking
            if (class_exists('VikBooking')) {
                $audit_note = sprintf(
                    "Conciliado con éxito. Bruto: $%.2f | Comisión MP: -$%.2f | Retenciones: -$%.2f | Neto Banco: $%.2f",
                    $gross_amount, $mp_fee, $taxes, $net_amount
                );
                VikBooking::addPaymentLog($booking_id, [
                    'gateway'        => 'DoneAPI Reconciler',
                    'transaction_id' => $payment['id'],
                    'amount'         => $net_amount,
                    'status'         => 'RECONCILED',
                    'notes'          => $audit_note
                ]);
            }

            $reconciled_count++;
        }

        WP_CLI::success("Conciliación finalizada. {$reconciled_count} reservas sincronizadas en los libros contables.");
    }
}

---

5. Tabla de Auditoría Contable para WordPress

Para mantener la integridad contable sin tocar las tablas centrales del core de WordPress, implementamos una tabla con motor InnoDB y precisión decimal para cálculos financieros:

CREATE TABLE `wp_doneapi_hotel_reconciled_ledger` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  `booking_id` int(11) unsigned NOT NULL,
  `payment_id` varchar(64) NOT NULL,
  `gross_amount` decimal(12,2) NOT NULL,
  `gateway_fee` decimal(12,2) NOT NULL DEFAULT '0.00',
  `tax_withheld` decimal(12,2) NOT NULL DEFAULT '0.00',
  `net_amount` decimal(12,2) NOT NULL,
  `payment_method` varchar(32) NOT NULL,
  `status` enum('PENDING','RECONCILED','DISCREPANCY','REFUNDED') NOT NULL DEFAULT 'PENDING',
  `reconciled_at` datetime NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `unique_payment` (`payment_id`),
  KEY `idx_booking_date` (`booking_id`, `reconciled_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

---

6. Manejo de Devoluciones y Reembolsos Parciales (Refunds)

En el sector hotelero, las cancelaciones por fuerza mayor o modificaciones de fechas son frecuentes. Cuando un cliente solicita un reembolso:

1. Reembolso Total: Mercado Pago devuelve la comisión porcentual cobrada, pero no reintegra el costo fijo de procesamiento en ciertas jurisdicciones. El script conciliador detecta el estado refunded, actualiza el registro en wp_doneapi_hotel_reconciled_ledger a REFUNDED y calcula el impacto neto negativo en caja.
2. Reembolsos Parciales (Cobro de Penalidad por No-Show): Si la política del hotel retiene el 50% de la primera noche por cancelación tardía, el sistema debe registrar el débito parcial manteniendo el saldo a favor en la cuenta bancaria del hotel.

---

7. Plugin DoneAPI VikBooking Mercado Pago ($7 USD) y Asesoría Contable

La integración manual de pasarelas de pago y sistemas de conciliación para hoteles suele demandar meses de pruebas de integración y miles de dólares en honorarios de desarrollo.

En DoneAPI hemos empaquetado esta tecnología para ponerla al alcance de cualquier establecimiento turístico:

• Plugin VikBooking Mercado Pago Oficial ($7 USD): Listo para instalar en WordPress, con soporte para pagos con tarjeta, PSE, Pix y OXXO, validación criptográfica HMAC y generación de identificadores external_reference preparados para conciliación automática.
• Sin Comisiones Recurrentes: Pago único de $7 USD con licencia directa de código para tu dominio.
• Módulos de Exportación ERP: Conectores personalizados para sincronizar las transacciones conciliadas de VikBooking con softwares contables líderes como Siigo, QuickBooks, SAP Business One y Alegra.

💬 ¿Quieres adquirir el plugin de VikBooking Mercado Pago por $7 USD o necesitas automatizar la conciliación contable de tu cadena hotelera?
Escríbenos directamente por WhatsApp y nuestro equipo de ingenieros te asistirá de inmediato.

---

8. Conclusión

La conciliación automática de pagos no es un lujo administrativo, sino un pilar fundamental para la salud financiera y fiscal de cualquier negocio hotelero moderno.

Al integrar VikBooking con los endpoints de liquidación de Mercado Pago, las empresas turísticas eliminan la incertidumbre contable, deducen con precisión matemática las retenciones impositivas y garantizan que cada peso recaudado quede perfectamente auditado y justificado en sus libros contables.