Saltar al contenido

    Centro de ayuda · Integraciones

    Integra tu inventario con Mercazul

    Tres formas de mantener tu catálogo y stock sincronizados: API REST, carga manual de CSV y entrega por SFTP. Todas usan el mismo contrato de datos.

    Canales de integración

    Disponible

    API REST

    Sincronización programática de catálogo y stock. Upsert masivo idempotente por SKU, actualizaciones de precio/stock y consulta de resultados de importación.
    Disponible

    CSV manual

    Sube un CSV desde tu panel de vendedor, valida las filas en pantalla y confirma la importación. Ideal para catálogos pequeños o cargas puntuales.

    Ir a Productos → Importación
    Disponible

    CSV por SFTP

    Deposita el mismo CSV en una carpeta SFTP y la plataforma lo importará automáticamente. Usa el mismo contrato de columnas de esta página.

    El canal SFTP ya está disponible: host sftp.izzatissa.site, puerto 2022, autenticación con clave SSH (Ed25519). Escríbenos a [email protected] con tu clave pública para activar tu cuenta. Deposita tus CSV en la carpeta inbox/ y recoge el reporte de resultados de cada archivo en reports/; los trabajos también aparecen en tu historial de importaciones del panel.

    1 · Autenticación

    Cada petición necesita dos encabezados: la clave publicable de la plataforma (apikey) y un token de tu cuenta de vendedor (Authorization: Bearer). Obtén el token con tu email y contraseña:

    URL base

    https://zonalibre-api.izzatissa.site

    Clave publicable (apikey)

    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzgxMjMxMTA2LCJleHAiOjIwOTY1OTExMDZ9.dJ5raIZYJuIhurPUU_W6wxfvR-W7WeyxKb3YzDIkJr4
    curl -s 'https://zonalibre-api.izzatissa.site/auth/v1/token?grant_type=password' \
      -H 'apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzgxMjMxMTA2LCJleHAiOjIwOTY1OTExMDZ9.dJ5raIZYJuIhurPUU_W6wxfvR-W7WeyxKb3YzDIkJr4' \
      -H 'Content-Type: application/json' \
      -d '{"email":"[email protected]","password":"<your-password>"}'

    La clave publicable es pública por diseño; la seguridad real la aplican las políticas de acceso por fila (RLS) con tu token de usuario.

    2 · Sincroniza tu inventario por API

    El endpoint principal acepta lotes de filas con el mismo contrato del CSV. Las filas se upsertean por SKU: un SKU nuevo crea el producto (queda en borrador hasta pasar moderación) y un SKU existente actualiza producto y stock.

    curl -s 'https://zonalibre-api.izzatissa.site/rest/v1/rpc/seller_import_products' \
      -H 'apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzgxMjMxMTA2LCJleHAiOjIwOTY1OTExMDZ9.dJ5raIZYJuIhurPUU_W6wxfvR-W7WeyxKb3YzDIkJr4' \
      -H 'Authorization: Bearer <access_token>' \
      -H 'Content-Type: application/json' \
      -d '{
        "p_filename": "api-sync-example",
        "p_rows": [{
          "sku": "WIDGET-001",
          "name_es": "Widget industrial 10cm",
          "name_en": "Industrial widget 10cm",
          "description_es": "Widget de acero inoxidable.",
          "description_en": "Stainless-steel widget.",
          "category": "hardware",
          "price": 12.50, "moq": 100, "stock": 5400, "currency": "USD"
        }, {
          "sku": "SHOE-CURVE-01",
          "name_es": "Zapatilla running",
          "name_en": "Running sneaker",
          "description_es": "Caja surtida de zapatillas.",
          "description_en": "Assorted sneaker box.",
          "category": "footwear",
          "price": 42.00, "moq": 1, "stock": 30, "currency": "USD",
          "sell_unit": "both", "units_per_box": 12,
          "size_breakdown": "38:1,39:2,40:3,41:3,42:2,43:1", "size_system": "EU"
        }]
      }'

    Consulta el historial y los errores por fila de tus importaciones:

    curl -s 'https://zonalibre-api.izzatissa.site/rest/v1/product_import_jobs?order=created_at.desc&limit=5' \
      -H 'apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlzcyI6InN1cGFiYXNlIiwiaWF0IjoxNzgxMjMxMTA2LCJleHAiOjIwOTY1OTExMDZ9.dJ5raIZYJuIhurPUU_W6wxfvR-W7WeyxKb3YzDIkJr4' \
      -H 'Authorization: Bearer <access_token>'

    3 · Contrato CSV (manual y SFTP)

    Las primeras 10 columnas son obligatorias y van en este orden exacto; las 4 columnas de composición de caja son opcionales (puedes omitirlas). La primera fila es el encabezado; codificación UTF-8; separador coma; comillas dobles para valores con comas (p. ej. el listado de size_breakdown).

    ColumnaObligatorioRegla
    skuCódigo único de producto. Clave de upsert dentro de tu catálogo.
    name_esNombre del producto en español.
    name_enNombre del producto en inglés.
    description_esDescripción en español.
    description_enDescripción en inglés.
    categoryNombre o slug de una categoría existente (sin distinguir mayúsculas). Categorías desconocidas rechazan la fila.
    pricePrecio unitario, número ≥ 0.
    moqCantidad mínima de pedido, entero ≥ 1.
    stockStock disponible, entero ≥ 0. Reemplaza la cantidad almacenada.
    currencyCódigo ISO 4217 de 3 letras (ej: USD).
    sell_unitOpcionalUnidad de venta: individual (suelto), box (por caja) o both (ambos). Vacío = individual.
    units_per_boxOpcionalUnidades por caja, entero ≥ 1. Obligatorio cuando sell_unit es box o both; debe ser igual a la suma de size_breakdown.
    size_breakdownOpcionalComposición de la caja como lista "talla:cantidad" separada por comas. Curva: "38:1,39:2,40:3"; talla única: "40:24". Debe ir vacío para productos individuales.
    size_systemOpcionalSistema de tallas, texto libre (ej: EU, US). Opcional.

    Ejemplo mínimo

    sku,name_es,name_en,description_es,description_en,category,price,moq,stock,currency,sell_unit,units_per_box,size_breakdown,size_system
    WIDGET-001,Widget industrial 10cm,Industrial widget 10cm,Widget de acero inoxidable.,Stainless-steel widget.,hardware,12.50,100,5400,USD,individual,,,
    SHOE-CURVE-01,Zapatilla running,Running sneaker,Caja surtida de zapatillas.,Assorted sneaker box.,footwear,42.00,1,30,USD,both,12,"38:1,39:2,40:3,41:3,42:2,43:1",EU

    Carga manual: panel de vendedor → Productos → Importación masiva. Ahí también puedes descargar la plantilla y ver el historial de importaciones.

    4 · Prompts de ayuda (copia y pega en tu asistente de IA)

    Estos prompts incluyen el contrato completo para que un asistente de IA (Claude, ChatGPT…) haga el trabajo pesado: mapear tu archivo de inventario al formato correcto o escribir el script de sincronización por ti.

    Prompt: convierte mi archivo de inventario al CSV de Mercazul

    You are helping me prepare a product CSV for the Mercazul B2B marketplace bulk import.
    
    The CSV header row must start with these 10 required columns, in this exact order:
    sku,name_es,name_en,description_es,description_en,category,price,moq,stock,currency
    You may then append any of these 4 optional box-composition columns (by name, any order; omit them entirely for simple products):
    sell_unit,units_per_box,size_breakdown,size_system
    
    Field rules:
    - sku (required): Unique product code. Upsert key within your catalog.
    - name_es (required): Product name in Spanish.
    - name_en (required): Product name in English.
    - description_es (required): Description in Spanish.
    - description_en (required): Description in English.
    - category (required): Existing category name or slug (case-insensitive). Unknown categories reject the row.
    - price (required): Unit price, number ≥ 0.
    - moq (required): Minimum order quantity, integer ≥ 1.
    - stock (required): Available stock, integer ≥ 0. Replaces the stored quantity.
    - currency (required): 3-letter ISO 4217 code (e.g. USD).
    - sell_unit (optional): Selling unit: individual (loose), box (by the box), or both. Blank = individual.
    - units_per_box (optional): Units per box, integer ≥ 1. Required when sell_unit is box or both; must equal the sum of size_breakdown.
    - size_breakdown (optional): Box composition as a comma-separated "size:qty" list. Curve: "38:1,39:2,40:3"; single size: "40:24". Must be empty for individual products.
    - size_system (optional): Size system, free text (e.g. EU, US). Optional.
    
    Additional rules:
    - Rows are upserted by "sku": an unknown sku inserts a new product (it starts as a draft pending marketplace moderation); a known sku updates the existing product and replaces its stock.
    - Both Spanish and English names/descriptions are required. If my source data only has one language, translate the missing one faithfully (no embellishment).
    - "category" must match one of my marketplace categories; ask me for my category list if you need it.
    - Box products: set sell_unit to box or both, units_per_box to the total pieces per box, and size_breakdown to a "size:qty" list (e.g. "38:1,39:2,40:3") whose quantities sum to units_per_box. Leave all 4 box columns blank for loose/individual products.
    
    Here is a sample of my current inventory export (I will paste it below). Map it to the contract above, flag any rows that would fail validation and why, and output the final CSV in a code block.
    
    MY DATA:
    <paste your inventory export here>

    Prompt: genera mi script de sincronización por API

    You are helping me build an automated inventory sync against the Mercazul B2B marketplace API (Supabase/PostgREST).
    
    Base URL: https://zonalibre-api.izzatissa.site
    Auth: every request needs an "apikey" header (publishable key) plus "Authorization: Bearer <access_token>". The token comes from POST /auth/v1/token?grant_type=password with my seller email/password (JSON body: {"email":..., "password":...}); it expires in ~1 hour, so refresh or re-login as needed. Read credentials from environment variables — never hard-code them.
    
    Main sync endpoint: POST /rest/v1/rpc/seller_import_products
    Body: {"p_filename": "<label>", "p_rows": [ ...rows ]}
    Each row has these fields (the first 10 required; the last 4 optional box-composition fields):
    - sku (required): Unique product code. Upsert key within your catalog.
    - name_es (required): Product name in Spanish.
    - name_en (required): Product name in English.
    - description_es (required): Description in Spanish.
    - description_en (required): Description in English.
    - category (required): Existing category name or slug (case-insensitive). Unknown categories reject the row.
    - price (required): Unit price, number ≥ 0.
    - moq (required): Minimum order quantity, integer ≥ 1.
    - stock (required): Available stock, integer ≥ 0. Replaces the stored quantity.
    - currency (required): 3-letter ISO 4217 code (e.g. USD).
    - sell_unit (optional): Selling unit: individual (loose), box (by the box), or both. Blank = individual.
    - units_per_box (optional): Units per box, integer ≥ 1. Required when sell_unit is box or both; must equal the sum of size_breakdown.
    - size_breakdown (optional): Box composition as a comma-separated "size:qty" list. Curve: "38:1,39:2,40:3"; single size: "40:24". Must be empty for individual products.
    - size_system (optional): Size system, free text (e.g. EU, US). Optional.
    Rows are upserted by "sku". For products sold by the box, set sell_unit (box|both), units_per_box, and a "size:qty" size_breakdown whose quantities sum to units_per_box; leave those blank for individual products. The response includes job_id, inserted_count, updated_count and per-row error_rows — treat any error_rows as a partial failure and log them.
    
    Job history: GET /rest/v1/product_import_jobs?order=created_at.desc&limit=10 (same auth headers).
    Quick stock-only update: PATCH /rest/v1/products?sku=eq.<SKU> with a JSON body of changed fields, header "Prefer: return=representation".
    
    My stack and source of truth for inventory: <describe yours — e.g. "a PostgreSQL ERP", "a Shopify store", "a nightly CSV export">
    
    Write a production-quality sync script in <language of your choice> that reads my inventory, maps it to the row contract, pushes it in batches of ≤500 rows, verifies the job result, and exits non-zero on errors. Include a dry-run mode.
    
    Full OpenAPI spec if you need it: the /openapi.yaml file on the marketplace domain.

    5 · Prueba la API en vivo

    La referencia interactiva (Swagger UI) permite ejecutar cada endpoint desde el navegador: pulsa “Authorize”, pega la apikey y tu token Bearer, y usa “Try it out”. Las peticiones se ejecutan contra el entorno real con tus permisos de vendedor.

    Referencia API interactiva (Swagger)

    Buenas prácticas: nunca publiques tu contraseña ni tokens en repositorios; usa variables de entorno. Los tokens expiran en ~1 hora. Los productos nuevos pasan por moderación antes de ser visibles públicamente.