Mercado Libre + Odoo
Integration Architecture Explained

def upsert_product(item: dict, odoo_company_id: int) -> int:
    models, uid = odoo_connect()
    meli_id  = item["id"]
    site_id  = item.get("site_id", "")    # MLM, MCO, MLA, MLB, MLC
    is_catalog = item.get("catalog_listing", False)

    # Lookup by MELI item ID — not title, not SKU
    existing = models.execute_kw(ODOO_DB, uid, ODOO_KEY,
        "product.template", "search_read",
        [[("x_meli_item_id", "=", meli_id), ("x_meli_site_id", "=", site_id)]],
        {"fields": ["id", "x_meli_catalog_listing"], "limit": 1}
    )

    # Base vals — always safe to update
    vals = {
        "list_price":             float(item.get("price", 0)),
        "x_meli_item_id":         meli_id,
        "x_meli_site_id":         site_id,
        "x_meli_catalog_listing":  is_catalog,
    }

    # Only update content fields if NOT catalog mode (MLA/MLB protection)
    if not is_catalog:
        seller_sku = next(
            (a["value_name"] for a in item.get("attributes", [])
             if a["id"] == "SELLER_SKU"), meli_id
        )
        vals.update({
            "name":         item["title"],
            "default_code": seller_sku,
            "description":  item.get("plain_text", ""),
        })

    if existing:
        tmpl_id = existing[0]["id"]
        models.execute_kw(ODOO_DB, uid, ODOO_KEY,
            "product.template", "write", [[tmpl_id], vals])
    else:
        vals["type"]    = "product"
        vals["sale_ok"]  = True
        tmpl_id = models.execute_kw(ODOO_DB, uid, ODOO_KEY,
            "product.template", "create", [vals])

    return tmpl_id

# MELI payment_type → (Odoo journal name, clears_immediately)
# Expand per your Odoo account.journal configuration
LATAM_PAYMENT_MAP = {
    # ── Universal (all LATAM sites) ─────────────────────────────────────
    "account_money":   ("Mercado Pago",   True),
    "visa":             ("Mercado Pago",   True),
    "master":           ("Mercado Pago",   True),
    "amex":             ("Mercado Pago",   True),

    # ── Mexico (MLM) ────────────────────────────────────────────────────
    "oxxo":             ("OXXO Pay",       False),  # up to 24h clearing
    "kueski":           ("Kueski Pay",     True),
    "spei":             ("Transferencia SPEI", False),  # 15min–4h
    "banamex_3months":  ("Mercado Pago",   True),   # MSI — cleared by MP

    # ── Colombia (MCO) ──────────────────────────────────────────────────
    "pse":              ("PSE Colombia",   False),  # 5min–24h
    "efecty":           ("Efecty",         False),  # next business day
    "baloto":           ("Baloto",         False),  # next business day
    "bancolombia":      ("Bancolombia",    False),

    # ── Argentina (MLA) ─────────────────────────────────────────────────
    "rapipago":         ("Rapipago",       False),
    "pagofacil":        ("Pago Fácil",     False),

    # ── Brazil (MLB) ────────────────────────────────────────────────────
    "bolbradesco":      ("Boleto Bancário", False), # 1–3 business days
    "pix":              ("Pix",            True),   # instant
    "account_money_br": ("Mercado Pago",   True),

    # ── Chile (MLC) ─────────────────────────────────────────────────────
    "webpay":           ("WebPay",         True),
    "khipu":            ("Khipu",          False),
}

def get_order_state(payment_type: str) -> str:
    """Returns Odoo sale.order state based on payment clearing speed."""
    _, clears_now = LATAM_PAYMENT_MAP.get(payment_type, ("Mercado Pago", True))
    return "sale" if clears_now else "draft"  # draft = hold fulfillment

SAFETY_BUFFER          = 5      # units held back — absorbs sync lag and multi-channel
MELI_FULL_LOCATION_ID  = int(os.environ["ODOO_MELI_FULL_LOC_ID"])

def sync_inventory(meli_item_id: str, site_id: str, odoo_wh_id: int):
    models, uid = odoo_connect()

    products = models.execute_kw(ODOO_DB, uid, ODOO_KEY,
        "product.product", "search_read",
        [[("product_tmpl_id.x_meli_item_id", "=", meli_item_id),
          ("product_tmpl_id.x_meli_site_id", "=", site_id)]],
        {"fields": ["id", "x_meli_is_full", "x_meli_variation_id"]}
    )

    for prod in products:
        product_id   = prod["id"]
        is_full      = prod.get("x_meli_is_full", False)
        variation_id = prod.get("x_meli_variation_id")

        if is_full:
            # MELI FULL: MELI is master → read stock from MELI → write Odoo FULL location
            item   = meli_get(f"/items/{meli_item_id}")
            fulfil = item.get("available_quantity", 0)
            set_odoo_quant(models, uid, product_id, MELI_FULL_LOCATION_ID, fulfil)
        else:
            # Standard: Odoo is master → read Odoo → push to MELI
            quants = models.execute_kw(ODOO_DB, uid, ODOO_KEY,
                "stock.quant", "search_read",
                [[("product_id", "=", product_id),
                  ("location_id.usage", "=", "internal"),
                  ("location_id.warehouse_id", "=", odoo_wh_id)]],
                {"fields": ["quantity", "reserved_quantity"]}
            )
            available = sum(q["quantity"] - q["reserved_quantity"] for q in quants)
            push_qty  = max(0, int(available) - SAFETY_BUFFER)

            body = ({"variations": [{"id": variation_id, "available_quantity": push_qty}]}
                    if variation_id else {"available_quantity": push_qty})
            meli_put(f"/items/{meli_item_id}", body)

REPUTATION_THRESHOLDS = {
    # metric_key: (alert_at, penalized_at) — fractions, not percentages
    "late_shipment_rate":  (0.02, 0.04),   # alert at 2%, suspended at 4%
    "cancellation_rate":   (0.008, 0.015),
    "claims_rate":         (0.015, 0.030),
}

SITES = ["MLM", "MCO", "MLA", "MLB", "MLC"]

def check_reputation_all_sites(seller_ids: dict) -> list[dict]:
    """
    seller_ids: {"MLM": "seller_id_mx", "MCO": "seller_id_co", ...}
    Returns list of alerts for any metric near threshold.
    """
    alerts = []
    for site, seller_id in seller_ids.items():
        metrics = meli_get(f"/users/{seller_id}/seller_reputation",
                            token_manager=get_token_manager(site))

        transactions = metrics.get("transactions", {})
        tier         = metrics.get("level_id", "unknown")  # 1_red → 5_green

        for metric_key, (alert_at, penalty_at) in REPUTATION_THRESHOLDS.items():
            value = transactions.get(metric_key, 0)
            if value >= alert_at:
                alerts.append({
                    "site":     site,
                    "metric":   metric_key,
                    "value":    round(value * 100, 2),
                    "limit":    round(penalty_at * 100, 2),
                    "tier":     tier,
                    "critical": value >= penalty_at * 0.85,
                })
    return sorted(alerts, key=lambda x: x["value"], reverse=True)