Plugin e1_ws_searchupcdata

ERPIO One plugin (.NET Framework 4.8) pre vyhľadávanie produktov podľa čiarových kódov cez SearchUPCData.com.

Stiahnuť plugin

Plugin poskytuje 5 modelov:

  • products – vyhľadanie 1 produktu podľa UPC
    • Parametre: @upc, @apiKey
  • products_search – fulltext vyhľadávanie (UPC, názov, značka)
    • Parametre: @query, @apiKey
  • products_search_advanced – rozšírené vyhľadávanie s filtrami
    • Parametre: @query, @brand, @category, @apiKey
  • products_brands – zoznam značiek
    • Parametre: @apiKey
  • products_categories – zoznam kategórií
    • Parametre: @apiKey

Dokumentácia API: https://searchupcdata.com/api-docs

Vlastnosti

REST GET volania na SearchUPCData s Bearer autentifikáciou.
5 samostatných providerov (bez akcií), každý vracia DataTable pripravený na zobrazenie.
CustomSearch: voliteľné filtrovanie výsledkov parametrom __whereany (case-insensitive) priamo v plugine.
Schema-only režim pre návrh datasource (param __schemaonly).

Požiadavky

Aktívny API key pre SearchUPCData (Free/Starter/Pro/Enterprise).

Pre jeho získanie je potrebné sa zaregistrovať na stránke https://searchupcdata.com, kde môžete na začiatok využívať Free program s limitom 100 požiadaviek mesačne (stav k 02/2026), ale si vybrať niektorý z platených programov podľa toho koľko požiadaviek na API mesačne potrebujete robiť.

Inštalácia

Skopíruj DLL do adresára plugins. Reštartuj Gateway, aby sa načítal nový plugin.

Konfigurácia a spustenie

Plugin sa inicializuje po reštarte brána a následne je dostupný v zozname pluginov pri vytváraní datasource.
V datasource si zvoľ príslušný model (provider) a nastav parametre (viď nižšie). Všetky API volania používajú hlavičku:
Authorization: Bearer {@apiKey}

Base URL: https://searchupcdata.com/api

Modely (providers)

products

Vyhľadá jeden produkt podľa UPC.
Endpoint: GET /api/products/:upc
Parametre:

@upc (string, povinné)
@apiKey (string, povinné)

Príklad použitia (parametre):
@upc = 7865578655204
@apiKey =

Pozn.: V oficiálnych docs je ukážka odpovede s poľami id, upc, name, description, imageUrl, brand, category, tie plugin mapuje 1:1.

products_search

Fulltext vyhľadávanie produktov podľa query (môže byť UPC, názov, značka).
Endpoint: GET /api/products/search?query=…
Parametre:

@query (string, povinné)
@apiKey (string, povinné)

Príklad:
@query = rice
@apiKey =

products_search_advanced

Pokročilé vyhľadávanie s voliteľnými filtrami brand a category.
Endpoint: GET /api/products/search/advanced?query=&brand=&category=
Parametre:

@query (string, voliteľné)
@brand (string, voliteľné)
@category (string, voliteľné)
@apiKey (string, povinné)

Príklad:
@query = basmati
@brand = Taqwa
@category = Rice
@apiKey =

products_brands
Zoznam všetkých unikátnych značiek v databáze.
Endpoint: GET /api/products/brands
Parametre:

@apiKey (string, povinné)

products_categories

Zoznam všetkých kategórií produktov.
Endpoint: GET /api/products/categories
Parametre:

@apiKey (string, povinné)

Schéma a stĺpce

Produkty (products, products_search, products_search_advanced)

Plugin vracia tabuľku so stĺpcami:

  • Textid (string)
  • upc (string)
  • name (string)
  • description (string)
  • imageUrl (string)
  • brand (string)
  • category (string)

Založené na príklade odpovede /api/products/:upc v dokumentácii API (ostatné endpointy môžu vracať pole položiek — plugin má tolerantné rozbalenie zo štruktúr [], items, results, data).

Značky (products_brands)

brand (string)
API vracia zoznam značiek (pole stringov alebo pole pod kľúčom brands; plugin zvláda oba tvary).

Kategórie (products_categories)

API vracia zoznam kategórií (pole stringov alebo pole pod kľúčom categories).

Error handling & limity

HTTP 401 – chýbajúci/neplatný @apiKey (Authorization: Bearer).
HTTP 404 – produkt nenájdený (pri products/:upc).
HTTP 429 – prekročená mesačná kvóta podľa tarify (Free: 100, Starter: 10 000, Pro: 100 000, Enterprise: unlimited).
HTTP 5xx – dočasný problém na strane API.
Konkrétne kódy a kvóty sú uvedené v dokumentácii API. [barcodelookup.com]

Plugin loguje chybové stavy a text odpovede pre rýchlu diagnostiku (viď sekcia Logovanie) – postup analogický k vzorovému projektu. [github.com]

Logovanie

Plugin vytvorí internú SQLite tabuľku p_e1_ws_searchupcdata_log a zapisuje dátum, metódu, lokalitu a správu. To uľahčuje debugging nasadenia.

Schema-only mód
Pri návrhu datasource vieš získať iba hlavičku stĺpcov (bez dát). Stačí zaškrtnúť Get schema only.

Fulltext filtrácia (__whereany)
Každý provider podporuje post‑filtering priamo v plugine:
__whereany =

Filter je case‑insensitive a prehľadáva všetky stĺpce vrátenej tabuľky.

Poznámky k implementácii

Autentifikácia: vždy posielame Authorization: Bearer {@apiKey}. Base URL: https://searchupcdata.com/api.

Tolerantný parser: pri search/advanced/brands/categories plugin podporuje odpovede typu čisté pole ([]) aj objekt s poľom (items, results, data). Je to praktické, keďže nie všetky stránky dokumentácie uvádzajú presný tvar každého endpointu.

Licencia

Interné použitie v rámci ERPIO One nasadení. Upozornenie: použitie dát podlieha podmienkam služby SearchUPCData (API key, kvóty, rate limits).