Cómo integrar la API de Mercado Libre con Contabilium, Tango o tu ERP en PHP 8.4 y Cloud VPS: Webhooks HTTPS, OAuth2 y sincronización de stock

/www/  (o /meli/ si creaste el subdominio meli.tudominio.com.ar desde panel.com.ar)
├── private/                          <-- BLOQUEADO AL NAVEGADOR VÍA .htaccess (HTTP 403)
│   ├── .htaccess                     <-- Require all denied (impide todo acceso HTTP externo)
│   ├── config/
│   │   ├── env.php                   <-- Client ID, Client Secret de MeLi y API Key de Contabilium
│   │   └── db.php                    <-- Conexión PDO a MySQL (localhost)
│   ├── tokens/
│   │   ├── .ht_meli_oauth.json       <-- access_token + refresh_token rotados automáticamente
│   │   ├── .ht_meli_oauth.lock       <-- Archivo de semáforo para flock(LOCK_EX)
│   │   └── .ht_contabilium.json      <-- Bearer token de Contabilium
│   ├── src/
│   │   └── MeliErpTokenManager.php   <-- Clase de rotación atómica OAuth2
│   └── cli/
│       └── worker-meli-erp.php       <-- Script ejecutado por Cron o demonio systemd
└── webhooks/                         <-- PÚBLICO HTTPS
    └── meli-callback.php             <-- Único endpoint público para recibir POST de Mercado Libre

# Bloquear absolutamente cualquier petición HTTP/HTTPS a /private/ y sus subcarpetas
<IfModule mod_authz_core.c>
    Require all denied
</IfModule>
<IfModule !mod_authz_core.c>
    Order deny,allow
    Deny from all
</IfModule>

<?php
declare(strict_types=1);

final class MeliErpTokenManager
{
    public function __construct(
        private readonly string $storageDir,
        private readonly string $meliAppId,
        private readonly string $meliClientSecret,
        private readonly string $contabiliumClientId,
        private readonly string $contabiliumClientSecret,
    ) {}

    /**
     * Devuelve un access_token válido de Mercado Libre.
     * Si faltan menos de 5 minutos para vencer, lo renueva con bloqueo exclusivo (flock).
     */
    public function getMeliAccessToken(): string
    {
        $tokenFile = $this->storageDir . '/.ht_meli_oauth.json';
        $lockFile  = $this->storageDir . '/.ht_meli_oauth.lock';

        $current = $this->readJson($tokenFile);
        if ($current && ($current['expires_at'] ?? 0) > (time() + 300)) {
            return (string)$current['access_token'];
        }

        $lockFp = fopen($lockFile, 'c+');
        if ($lockFp === false || !flock($lockFp, LOCK_EX)) {
            throw new RuntimeException('No se pudo adquirir el lock para rotar el token de Mercado Libre.');
        }

        try {
            // Double-check: verificar si otro proceso ya lo renovó mientras esperábamos el lock
            clearstatcache(true, $tokenFile);
            $current = $this->readJson($tokenFile);
            if ($current && ($current['expires_at'] ?? 0) > (time() + 300)) {
                return (string)$current['access_token'];
            }

            $refreshToken = (string)($current['refresh_token'] ?? '');
            if ($refreshToken === '') {
                throw new RuntimeException('Falta el refresh_token inicial en .ht_meli_oauth.json');
            }

            $ch = curl_init('https://api.mercadolibre.com/oauth/token');
            curl_setopt_array($ch, [
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_POST           => true,
                CURLOPT_TIMEOUT        => 10,
                CURLOPT_HTTPHEADER     => [
                    'Accept: application/json',
                    'Content-Type: application/x-www-form-urlencoded',
                ],
                CURLOPT_POSTFIELDS     => http_build_query([
                    'grant_type'    => 'refresh_token',
                    'client_id'     => $this->meliAppId,
                    'client_secret' => $this->meliClientSecret,
                    'refresh_token' => $refreshToken,
                ]),
            ]);

            $raw  = (string)curl_exec($ch);
            $code = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
            curl_close($ch);

            $data = json_decode($raw, true);
            if ($code !== 200 || empty($data['access_token']) || empty($data['refresh_token'])) {
                throw new RuntimeException("Error OAuth2 Mercado Libre (HTTP {$code}): {$raw}");
            }

            $newPayload = [
                'access_token'  => (string)$data['access_token'],
                'refresh_token' => (string)$data['refresh_token'],
                'user_id'       => (int)($data['user_id'] ?? ($current['user_id'] ?? 0)),
                'expires_at'    => time() + (int)($data['expires_in'] ?? 21600),
                'updated_at'    => date('c'),
            ];

            $this->writeJsonAtomic($tokenFile, $newPayload);
            return $newPayload['access_token'];
        } finally {
            flock($lockFp, LOCK_UN);
            fclose($lockFp);
        }
    }

    /**
     * Obtiene y cachea el Bearer Token de la API REST de Contabilium.
     */
    public function getContabiliumToken(): string
    {
        $tokenFile = $this->storageDir . '/.ht_contabilium.json';
        $current   = $this->readJson($tokenFile);

        if ($current && ($current['expires_at'] ?? 0) > (time() + 300)) {
            return (string)$current['access_token'];
        }

        $ch = curl_init('https://rest.contabilium.com/token');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST           => true,
            CURLOPT_TIMEOUT        => 10,
            CURLOPT_HTTPHEADER     => ['Content-Type: application/x-www-form-urlencoded'],
            CURLOPT_POSTFIELDS     => http_build_query([
                'grant_type'    => 'client_credentials',
                'client_id'     => $this->contabiliumClientId,
                'client_secret' => $this->contabiliumClientSecret,
            ]),
        ]);

        $raw  = (string)curl_exec($ch);
        $code = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $data = json_decode($raw, true);
        if ($code !== 200 || empty($data['access_token'])) {
            throw new RuntimeException("Error Token Contabilium (HTTP {$code}): {$raw}");
        }

        $payload = [
            'access_token' => (string)$data['access_token'],
            'expires_at'   => time() + (int)($data['expires_in'] ?? 86400),
            'updated_at'   => date('c'),
        ];
        $this->writeJsonAtomic($tokenFile, $payload);

        return $payload['access_token'];
    }

    private function readJson(string $path): ?array
    {
        if (!is_file($path)) {
            return null;
        }
        $decoded = json_decode((string)file_get_contents($path), true);
        return is_array($decoded) ? $decoded : null;
    }

    private function writeJsonAtomic(string $path, array $data): void
    {
        $tmp = $path . '.tmp.' . getmypid();
        file_put_contents($tmp, json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), LOCK_EX);
        chmod($tmp, 0600);
        rename($tmp, $path);
    }
}

CREATE TABLE IF NOT EXISTS meli_webhook_queue (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    notification_id VARCHAR(64) NOT NULL,
    topic VARCHAR(40) NOT NULL,
    resource VARCHAR(160) NOT NULL,
    user_id BIGINT UNSIGNED NOT NULL,
    payload_json TEXT NOT NULL,
    status ENUM('pending', 'processing', 'done', 'error') NOT NULL DEFAULT 'pending',
    attempts TINYINT UNSIGNED NOT NULL DEFAULT 0,
    last_error VARCHAR(255) DEFAULT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    processed_at DATETIME DEFAULT NULL,
    UNIQUE KEY uk_topic_resource_pending (topic, resource, status),
    KEY idx_status_created (status, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE IF NOT EXISTS erp_orders_synced (
    meli_order_id BIGINT UNSIGNED PRIMARY KEY,
    sku VARCHAR(80) NOT NULL,
    quantity INT NOT NULL,
    total_amount DECIMAL(14,2) NOT NULL,
    contabilium_synced TINYINT(1) NOT NULL DEFAULT 0,
    synced_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

<?php
declare(strict_types=1);

header('Content-Type: application/json; charset=utf-8');

if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
    http_response_code(200);
    exit(json_encode(['ok' => true, 'status' => 'ready']));
}

$rawBody = (string)file_get_contents('php://input');
$event   = json_decode($rawBody, true);

if (!is_array($event) || empty($event['resource']) || empty($event['topic'])) {
    http_response_code(400);
    exit(json_encode(['ok' => false, 'error' => 'invalid_payload']));
}

require_once __DIR__ . '/../private/config/db.php'; // Define $pdo (PDO MySQL dentro de /www/private/)

$notifId  = (string)($event['_id'] ?? bin2hex(random_bytes(8)));
$topic    = (string)$event['topic'];     // Ej: orders_v2, items, shipments, questions
$resource = (string)$event['resource'];  // Ej: /orders/2000009876543210
$userId   = (int)($event['user_id'] ?? 0);

// Encolamos en ~5 ms evitando duplicados si Mercado Libre reenvía el mismo recurso pendiente
$stmt = $pdo->prepare("
    INSERT IGNORE INTO meli_webhook_queue
        (notification_id, topic, resource, user_id, payload_json, status, created_at)
    VALUES
        (?, ?, ?, ?, ?, 'pending', NOW())
");
$stmt->execute([$notifId, $topic, $resource, $userId, $rawBody]);

// Respondemos HTTP 200 OK de inmediato (<20 ms totales)
http_response_code(200);
echo json_encode(['ok' => true, 'queued' => true]);

<?php
declare(strict_types=1);

if (PHP_SAPI !== 'cli') {
    http_response_code(403);
    exit('Acceso permitido únicamente por CLI.');
}

require_once __DIR__ . '/../config/db.php';
require_once __DIR__ . '/../src/MeliErpTokenManager.php';

$tokenManager = new MeliErpTokenManager(
    storageDir:              __DIR__ . '/../tokens',
    meliAppId:               getenv('MELI_APP_ID') ?: '',
    meliClientSecret:        getenv('MELI_CLIENT_SECRET') ?: '',
    contabiliumClientId:     getenv('CONTABILIUM_EMAIL') ?: '',
    contabiliumClientSecret: getenv('CONTABILIUM_API_KEY') ?: '',
);

$meliToken = $tokenManager->getMeliAccessToken();
$cbToken   = $tokenManager->getContabiliumToken();

// Tomamos hasta 25 notificaciones pendientes de órdenes
$stmt = $pdo->query("
    SELECT * FROM meli_webhook_queue
    WHERE status = 'pending' AND topic IN ('orders_v2', 'orders')
    ORDER BY id ASC
    LIMIT 25
");
$jobs = $stmt->fetchAll(PDO::FETCH_ASSOC);

foreach ($jobs as $job) {
    $jobId    = (int)$job['id'];
    $resource = (string)$job['resource']; // Ej: /orders/2000009876543210

    $pdo->prepare("UPDATE meli_webhook_queue SET status = 'processing', attempts = attempts + 1 WHERE id = ?")
        ->execute([$jobId]);

    try {
        // 1. Consultar la orden completa en la API de Mercado Libre
        $ch = curl_init("https://api.mercadolibre.com{$resource}");
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 10,
            CURLOPT_HTTPHEADER     => [
                "Authorization: Bearer {$meliToken}",
                'x-format-new: true',
            ],
        ]);
        $orderRaw  = (string)curl_exec($ch);
        $orderCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $order = json_decode($orderRaw, true);
        if ($orderCode !== 200 || !is_array($order)) {
            throw new RuntimeException("MeLi GET {$resource} devolvió HTTP {$orderCode}");
        }

        // Solo sincronizamos órdenes pagadas / confirmadas
        if (($order['status'] ?? '') !== 'paid') {
            $pdo->prepare("UPDATE meli_webhook_queue SET status = 'done', processed_at = NOW() WHERE id = ?")
                ->execute([$jobId]);
            continue;
        }

        $orderId = (int)$order['id'];

        // 2. Recorrer ítems vendidos y sincronizar por SKU con Contabilium / ERP
        foreach (($order['order_items'] ?? []) as $itemRow) {
            $sku = (string)($itemRow['item']['seller_sku'] ?? ($itemRow['item']['seller_custom_field'] ?? ''));
            $qty = (int)($itemRow['quantity'] ?? 1);

            if ($sku === '') {
                continue;
            }

            // Verificar idempotencia para no descontar dos veces la misma orden
            $chk = $pdo->prepare("SELECT meli_order_id FROM erp_orders_synced WHERE meli_order_id = ?");
            $chk->execute([$orderId]);
            if ($chk->fetch()) {
                continue;
            }

            // Ejemplo: consultar/actualizar stock o enviar comprobante en la API de Contabilium
            $cbUrl = 'https://rest.contabilium.com/api/inventarios/getStockBySku?codigo=' . rawurlencode($sku);
            $chCb  = curl_init($cbUrl);
            curl_setopt_array($chCb, [
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_TIMEOUT        => 10,
                CURLOPT_HTTPHEADER     => [
                    "Authorization: Bearer {$cbToken}",
                    'Accept: application/json',
                ],
            ]);
            $cbRes  = (string)curl_exec($chCb);
            $cbCode = (int)curl_getinfo($chCb, CURLINFO_HTTP_CODE);
            curl_close($chCb);

            if ($cbCode >= 400) {
                throw new RuntimeException("Error Contabilium SKU {$sku} (HTTP {$cbCode}): {$cbRes}");
            }

            $pdo->prepare("
                INSERT INTO erp_orders_synced (meli_order_id, sku, quantity, total_amount, contabilium_synced, synced_at)
                VALUES (?, ?, ?, ?, 1, NOW())
            ")->execute([$orderId, $sku, $qty, (float)($order['total_amount'] ?? 0)]);
        }

        $pdo->prepare("UPDATE meli_webhook_queue SET status = 'done', processed_at = NOW() WHERE id = ?")
            ->execute([$jobId]);

        // Pausa de 250 ms para respetar el rate-limit de la API del ERP
        usleep(250000);
    } catch (Throwable $e) {
        $nextStatus = ((int)$job['attempts'] >= 5) ? 'error' : 'pending';
        $pdo->prepare("UPDATE meli_webhook_queue SET status = ?, last_error = ? WHERE id = ?")
            ->execute([$nextStatus, substr($e->getMessage(), 0, 250), $jobId]);
    }
}

/usr/local/php84/bin/php /webcp/docs/webs/TU_ID/www/private/cli/worker-meli-erp.php >/dev/null 2>&1

[Unit]
Description=Worker de Sincronizacion Mercado Libre y Contabilium/ERP
After=network.target mysql.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/integrador/private/cli
ExecStart=/usr/bin/php8.4 /var/www/integrador/private/cli/worker-meli-erp-daemon.php
Restart=always
RestartSec=3
StandardOutput=append:/var/log/meli-erp-worker.log
StandardError=append:/var/log/meli-erp-worker.err

[Install]
WantedBy=multi-user.target