Integrare feed: XML, JSON si CSV

Ce face aceasta integrare

Integrarea Feed (XML, JSON, CSV) permite IVO sa citeasca catalogul tau de produse dintr-un URL public. Tu publici un fisier feed pe site-ul sau serverul tau, iar IVO il descarca, afiseaza o previzualizare, mapeaza campurile tale la campurile IVO si sincronizeaza catalogul prin sistemul normal de import al comerciantului.

Alege aceasta metoda cand poti genera un export de catalog, dar nu vrei sa instalezi un plugin de platforma sau sa implementezi direct Merchant API.

Unde se configureaza

1. Deschide Dashboard Merchant.
2. Mergi la Produse si apoi Istoric importuri, sau la Setari si apoi Integrari.
3. Apasa Integreaza un feed sau Integrare noua.
4. Alege Feed (XML, JSON, CSV).
5. Introdu URL-ul feedului, ruleaza previzualizarea, verifica produsele mapate si salveaza.

Cerinte

• Feedul trebuie sa fie disponibil la un URL public http sau https.
• URL-ul trebuie sa returneze direct continutul feedului, nu o pagina HTML, pagina de login sau pagina intermediara de descarcare.
• IVO trebuie sa poata accesa feedul cu User-Agent-ul IVO.md (+https://ivo.md/help/merchant-integration/ivo-md-crawler).
• Feedul ar trebui sa fie UTF-8. Pentru CSV, primul rand trebuie sa contina anteturile coloanelor.
• Fiecare produs trebuie sa aiba cel putin nume si un pret pozitiv valid.
• Foloseste un SKU sau ID intern stabil. Acesta ajuta IVO sa actualizeze aceeasi oferta la sincronizarile viitoare.

Cum proceseaza IVO feedul

1. IVO descarca feedul si detecteaza formatul.
2. Pentru JSON si XML, IVO cauta o lista de produse precum products, product, offers, offer, RSS channel.item sau cea mai mare lista de produse gasita intr-o structura imbricata.
3. Pentru CSV, IVO detecteaza delimitatorul: virgula, punct si virgula, tab sau bara verticala.
4. Previzualizarea citeste pana la 10 produse si arata cheile sursa gasite.
5. IVO propune automat maparea campurilor dupa denumiri comune si dupa valorile din exemple.
6. Poti corecta manual maparea inainte de salvare.
7. La sincronizare, produsele sunt trimise in loturi de 100 si procesate de sistemul de import merchant.
8. Ofertele existente sunt actualizate dupa ID-ul intern al comerciantului; produsele noi intra in fluxul de import si verificare.

Formate acceptate

JSON

JSON-ul poate fi o lista directa sau un obiect care contine lista de produse. Radacini uzuale acceptate: products, product, offers, offer.

{
  "products": [
    {
      "sku": "SKU-1001",
      "name": "Laptop 14 Ultra",
      "price": "15999 MDL",
      "currency": "MDL",
      "availability": 7,
      "brand": "ExampleBrand",
      "ean": "5940000000011",
      "category": "Laptopuri",
      "description": "Laptop compact cu 16 GB RAM si SSD 512 GB.",
      "images": [
        "https://example.com/images/sku-1001-1.jpg",
        "https://example.com/images/sku-1001-2.jpg"
      ],
      "color": "Silver",
      "memory": "16 GB"
    }
  ]
}

XML

XML-ul poate fi un catalog simplu sau un feed RSS / Google Shopping. Namespace-uri precum g:title sunt acceptate si normalizate la parsare.

<products>
  <product>
    <id>SKU-1001</id>
    <name>Laptop 14 Ultra</name>
    <price>15999</price>
    <currency>MDL</currency>
    <availability>7</availability>
    <brand>ExampleBrand</brand>
    <ean>5940000000011</ean>
    <category>Laptopuri</category>
    <description>Laptop compact cu 16 GB RAM si SSD 512 GB.</description>
    <image>https://example.com/images/sku-1001-1.jpg</image>
    <image_2>https://example.com/images/sku-1001-2.jpg</image_2>
    <color>Silver</color>
  </product>
</products>

CSV

CSV-ul trebuie sa aiba antet pe primul rand. IVO detecteaza ,, ;, tab si |. Imaginile pot fi in coloane separate precum image_1, image_2 sau intr-o singura coloana, separate prin spatii ori virgule.

sku,name,price,currency,availability,brand,ean,category,image_1,image_2,color
SKU-1001,Laptop 14 Ultra,15999,MDL,7,ExampleBrand,5940000000011,Laptopuri,https://example.com/1.jpg,https://example.com/2.jpg,Silver

Campuri recomandate

Maparea campurilor

In previzualizare, IVO afiseaza cheile brute din feed si campurile IVO. Daca folosesti denumiri standard, maparea este de obicei automata. Daca ai denumiri custom, selecteaza manual campul tinta.

Mai multe chei sursa pot fi mapate la acelasi camp IVO. De exemplu, image_1, image_2 si gallery pot merge toate la image; color si size pot merge la variant_option.

Puncte merchant si strategie de stoc

Fiecare oferta sincronizata are nevoie de o strategie de stoc. Ai trei variante:

• Un punct merchant implicit: toate produsele din feed sunt atasate unei singure locatii.
• Campuri de stoc detectate: mapezi coloane diferite la puncte merchant diferite, de exemplu stock_chisinau la punctul Chisinau si stock_balti la punctul Balti.
• Toate produsele disponibile in toate punctele: IVO creeaza disponibilitate pentru fiecare punct merchant si foloseste disponibilitatea implicita.

Daca activezi Out of stock on missing, produsele importate anterior prin acelasi feed, dar lipsa din ultima sincronizare, vor fi setate cu stoc 0. Activeaza optiunea doar daca feedul este complet la fiecare rulare.

Valori implicite si modificator de pret

Valorile implicite completeaza informatii care lipsesc din feed: moneda, disponibilitate, brand, categorie, descriere sau imagine. Modificatorul de pret schimba preturile la import. De exemplu, 10 creste preturile cu 10%, iar -5 le reduce cu 5%.

Reguli de validare

• name este obligatoriu.
• price este obligatoriu si trebuie sa fie mai mare decat zero.
• Daca nu exista SKU, IVO genereaza un ID stabil din nume, pret, brand si EAN, dar un SKU real este mai sigur.
• LEI, LEU si MDL sunt normalizate la MDL. Alte monede trebuie sa fie coduri din trei litere.
• Sincronizarea are limita de siguranta de 5000 produse mapate per rulare.
• Imaginile trebuie sa fie URL-uri absolute accesibile de IVO.

Exemplu PHP: feed JSON

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

$products = [
    [
        'sku' => 'SKU-1001',
        'name' => 'Laptop 14 Ultra',
        'price' => 15999,
        'currency' => 'MDL',
        'availability' => 7,
        'brand' => 'ExampleBrand',
        'ean' => '5940000000011',
        'category' => 'Laptopuri',
        'description' => 'Laptop compact cu 16 GB RAM si SSD 512 GB.',
        'images' => [
            'https://example.com/images/sku-1001-1.jpg',
            'https://example.com/images/sku-1001-2.jpg',
        ],
        'color' => 'Silver',
        'memory' => '16 GB',
    ],
];

echo json_encode(['products' => $products], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

Exemplu Node.js: feed JSON

import express from 'express';

const app = express();

app.get('/ivo-feed.json', (req, res) => {
  res.type('application/json');
  res.json({
    products: [
      {
        sku: 'SKU-1001',
        name: 'Laptop 14 Ultra',
        price: 15999,
        currency: 'MDL',
        availability: 7,
        brand: 'ExampleBrand',
        ean: '5940000000011',
        category: 'Laptopuri',
        description: 'Laptop compact cu 16 GB RAM si SSD 512 GB.',
        images: ['https://example.com/images/sku-1001-1.jpg'],
        color: 'Silver',
        memory: '16 GB'
      }
    ]
  });
});

app.listen(3000);

Exemplu Python: feed CSV

from flask import Flask, Response
import csv
import io

app = Flask(__name__)

@app.get('/ivo-feed.csv')
def ivo_feed():
    rows = [{
        'sku': 'SKU-1001',
        'name': 'Laptop 14 Ultra',
        'price': '15999',
        'currency': 'MDL',
        'availability': '7',
        'brand': 'ExampleBrand',
        'ean': '5940000000011',
        'category': 'Laptopuri',
        'image_1': 'https://example.com/images/sku-1001-1.jpg',
        'image_2': 'https://example.com/images/sku-1001-2.jpg',
        'color': 'Silver'
    }]
    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=rows[0].keys())
    writer.writeheader()
    writer.writerows(rows)
    return Response(output.getvalue(), mimetype='text/csv; charset=utf-8')

Greseli frecvente

• Nume de produse prea generale, precum Husa sau Cablu. Adauga brand, model si varianta.
• Schimbarea SKU-urilor intre sincronizari. Pastreaza-le stabile.
• Imagini relative precum /image.jpg. Foloseste URL complet.
• Feed protejat cu login sau blocarea crawlerului IVO.
• Activarea optiunii Out of stock on missing cand trimiti doar feed partial.
• Gruparea produselor diferite ca variante. Grupeaza doar variante reale ale aceluiasi produs.

Dupa salvare

Prima sincronizare porneste dupa salvarea integrarii active. Ulterior poti merge la Setari > Integrari si poti folosi actiunea de sincronizare manuala. Progresul si erorile apar in Produse > Istoric importuri.