Dokumentace Web API
Úvod
Web API pro nopCommerce poskytuje přístup ke všem funkcím platformy i plnou kontrolu nad databázovými entitami. Jde o RESTful API vytvořené podle specifikace OpenAPI 3.0 (OAS). Pomocí nástroje, jako je Swagger UI, nebo v rámci platformy SwaggerHub můžete svůj OAS kontrakt převést na interaktivní konzoli API, kterou mohou vývojáři používat k interakci s API a rychle se naučit, jak se má API chovat. nopCommerce nabízí sadu API, která vývojářům umožňují používat a rozšiřovat vestavěné funkce platformy. Tato API umožňují vývojářům číst a zapisovat data obchodníka, spolupracovat s jinými systémy a platformami a přidávat do nopCommerce nové funkce.
Dostupná API (pokrytí metod)
Framework Web API poskytuje integrátorům a vývojářům prostředky k používání webových služeb, které komunikují se systémem nopCommerce.
Metody frontendu
Web API Frontend vám nabízí způsob, jak implementovat nákupní možnosti nopCommerce v jakékoli aplikaci, ať už jde o web nebo mobilní aplikaci. Použití API je nezbytné, když chtějí prodejci oslovit širší publikum a jejich požadavky přesahují standardní funkčnost nopCommerce. Web API Frontend poskytuje metody, které umožňují používat vestavěné funkce veřejné části obchodu mimo obchod nopCommerce. I když máte v obchodě nopCommerce vlastní úpravy, budete moci tento plugin používat, protože je dodáván se zdrojovým kódem.
Po instalaci pluginu si budete moci zobrazit seznam existujících metod API pomocí následujícího endpointu Swagger UI:
{store location}/api/index.html
Tip
Prostřednictvím Frontend API nelze používat vícefaktorové ověřování (MFA).
Metody backendu
Web API Backend poskytuje přístup ke všem funkcím administrace nopCommerce. To znamená, že pomocí metod Web API Backend můžete získat plnou kontrolu nad funkcemi, jako je správa zákazníků, vytváření a aktualizace produktů, sledování prodejů a vlastně čímkoli, co chcete v administraci obchodu nopCommerce ovládat. Toto API použijte k vytváření aplikací, jako jsou systémy CRM a ERP, integrace se sociálními sítěmi a další aplikace, které vyžadují přístup k obchodním procesům obchodu.
Po instalaci pluginu si budete moci zobrazit seznam existujících metod API pomocí následujícího endpointu Swagger UI:
{store location}/api/index.html
Důležité
Po instalaci backendového a frontendového API se přepínání mezi nimi provádí přímo na stránce Swagger UI v rozbalovacím seznamu dostupných definic.

Rozsahy a oprávnění
Aby mohla klientská aplikace API používat, musí mít odpovídající oprávnění (ACL) v obchodě nopCommerce, kde je plugin API nainstalován. Například pro přístup k metodám backendu (administrace) prostřednictvím API je vyžadováno speciální oprávnění „Access Web API Backend“. Ve výchozím stavu je toto oprávnění přiděleno pouze roli administrátora. Tato nastavení můžete změnit prostřednictvím standardního ACL používaného v nopCommerce.
Ověřování
Aby byly transakce na platformě nopCommerce bezpečné, musí se všechny aplikace připojující se k našim API při volání API ověřit.
Aby mohl klient API, například mobilní aplikace, provést volání webového API, musí prokázat svou identitu. K tomu API s každým požadavkem poskytuje přístupový token v hlavičce Authorization pomocí autorizačního schématu HTTP Bearer. Tento token funguje jako elektronický klíč, který vám umožňuje přístup k API.
Po instalaci pluginu Web API je třeba na konfigurační stránce pluginu vygenerovat tajný klíč. Tento klíč bude sloužit k podepisování a ověřování každého JWT tokenu.
Vyžádání tokenu
Endpoint
Pro každé API existuje nezabezpečený endpoint, který slouží k získání přístupového tokenu:
/api-backend/Authenticate/GetToken/api-frontend/Authenticate/GetToken
Typ obsahu
Typ obsahu těla požadavku. Nastavte tuto hodnotu na
Content-Type:application/json-patch+jsonPřihlašovací údaje
Uživatelské jméno a heslo k účtu nopCommerce. Chcete-li tyto přihlašovací údaje zadat v těle požadavku JSON, zahrňte do volání kód podobný následujícímu:
{ "username":"<user name>", "email":"<Email>", "password":"<password>" }
Příklady
Následující příklad používá příkaz curl k vyžádání tokenu pro zákaznický účet:
curl -X 'POST' \
'http://localhost:15536/api-backend/Authenticate/GetToken' \
-H 'accept: application/json' \
-H 'Content-Type: application/json-patch+json' \
-d '{
"username": "admin@yourstore.com",
"email": "admin@yourstore.com",
"password": "123456"
}'
Odpověď s ověřovacím tokenem
Úspěšný požadavek vrátí tělo odpovědi s tokenem takto:
{
"username": "admin@yourStore.com",
"customer_id": 1,
"token": <authentication token>
}
Použití tokenu v požadavku Web API
Každé volání webového API, které přistupuje k prostředku vyžadujícímu vyšší úroveň oprávnění než anonymní, by mělo v hlavičce obsahovat ověřovací token. K tomu se HTTP hlavička odesílá v následujícím formátu:
curl -X 'GET' \
'http://localhost:15536/api-backend/BlogPost/GetById/1' \
-H 'accept: application/json' \
-H 'Authorization: <authentication token>'
Testování
Pro pohodlné testování endpointů API je k dispozici Vývojářský režim (Developer mode). Aktivací tohoto režimu na konfigurační stránce pluginu se ověřování tokenu v podstatě vypne. API můžete testovat pomocí následujících nástrojů:
- Swagger UI. Nabízí webové rozhraní, které poskytuje informace o službě pomocí vygenerované specifikace OpenAPI.
- Postman. Jde o nástroj pro testování API.
Níže najdete návod, jak pomocí nástroje Postman ověřit uživatele a získat z API JWT token a poté provést ověřený požadavek s JWT tokenem k načtení seznamu stránek (topics) z API.
Jak ověřit uživatele pomocí nástroje Postman
Chcete-li ověřit uživatele a získat JWT token, postupujte takto:
- Otevřete kartu nového požadavku kliknutím na tlačítko plus (+) na konci karet.
- Pomocí rozbalovacího výběru vlevo od vstupního pole URL změňte metodu HTTP požadavku na „POST“.
- Do pole URL zadejte ověřovací URL svého API:
{storeURL}/api-backend/Authenticate/GetToken. - Pod polem URL vyberte kartu „Body“, přepněte přepínač typu těla na „raw“ a pomocí rozbalovacího výběru změňte formát na „JSON (application/json)“.
- Do textového pole „Body“ zadejte objekt JSON obsahující testovací uživatelské jméno a heslo.
- Klikněte na tlačítko „Send“. Měli byste obdržet odpověď „200 OK“ s údaji o uživateli včetně JWT tokenu v těle odpovědi. Hodnotu tokenu zkopírujte, protože ji v dalším kroku použijeme k provedení ověřeného požadavku.
Zde je snímek obrazovky nástroje Postman po odeslání požadavku a ověření uživatele:

Jak provést ověřený požadavek k načtení stránky (topic) podle ID
Chcete-li provést ověřený požadavek pomocí JWT tokenu z předchozího kroku, postupujte takto:
- Otevřete kartu nového požadavku kliknutím na tlačítko plus (+) na konci karet.
- Pomocí rozbalovacího výběru vlevo od vstupního pole URL změňte metodu HTTP požadavku na „GET“.
- Do pole URL zadejte URL „Get topic“ svého API:
{storeURL}/api-backend/Topic/GetById/:id. - Pod polem URL vyberte kartu „Authorization“, v rozbalovacím výběru typu změňte typ na „Bearer Token“ a do pole „Token“ vložte JWT token z předchozího kroku ověření.

- Klikněte na tlačítko „Send“. Měli byste obdržet odpověď „200 OK“ obsahující pole JSON se všemi záznamy uživatelů v systému (v příkladu jen jeden testovací uživatel).
Zde je snímek obrazovky nástroje Postman po provedení ověřeného požadavku na získání stránky (topic) podle ID:

Licence
Plugin Web API je licencován za následujících podmínek.