API - GraphQL

Umožňuje rozšiřovat funkce eshopu, napojovat aplikace třetích stran a obecně pracovat s daty bez ohledu na naše programátory. Obsahuje řadu funkcí pro čtení a manipulaci s daty eshopu, nejčastěji používané funkce a příklady jejich použití jsou popsány na této stránce nápovědy, ucelený seznam a popis všech funkcí je pak k nalezení v kompletní dokumentaci API.

Pro aktivaci modulu nebo více informací kontaktujte naše zákaznické oddělení.

Technologie

Naše API využívá otevřený standard GraphQL, který umožňuje klientům definovat strukturu datových požadavků a odpovědí. Na rozdíl od pevně stanovených formátů, jako je SOAP nebo REST může klient specifikovat, jaká data požaduje, což usnadňuje agregaci odpovědí z různých zdrojů a zmenšuje celkový objem přenášených dat. Naše implementace podporuje čtení (dotazy) a změnu (mutace). Více informací na stránkách tvůrců https://graphql.org/.

Pro testování všech funkcionalit lze používat libovolný GrahpQL editor, doporučujeme například

Altair GraphQL Client https://altairgraphql.dev.

Dokumentace

Kompletní dokumentace se nachází na adrese https://graphql-docs.wpjshop.cz/

Autentifikace

Do pole X-Access-Token v hlavičce každého API requestu je třeba vložit přihlašovací token administrátorského účtu, který bude k přístupu na API používán. Ten se nachází na detailu účtu administrátora v záložce Přihlašování, je možné ho zde vygenerovat nebo přegenerovat. Zároveň je třeba administrátorovi udělit oprávnění API používat. To lze nastavit na záložce Oprávnění: Ostatní zaškrtnutím pole Používat u API.

➡️ Nastavení > Administrátoři

Omezení

U seznamů je omezen maximální počet položek na stránce na 1000. Pokud je zadána hodnota vyšší, vždy se použije nejvyšší možná hodnota.

#limit bude nastaven na 1000
query {
  orders(limit: 2000){...}}

Sledování změn

Slouží pro sledování změn, které vznikají na straně e-shopu. Umožňuje efektivně zachytit a zpracovat události, jako jsou například úpravy produktů, změny ve skladových zásobách a další relevantní aktualizace dat.

Při používání je nezbytné, aby každý klient (např. integrace, systém nebo aplikace) používal vlastní access token.

Pokud by více klientů sdílelo jeden společný API access token, docházelo by k tzv. kolizi odběru – jednotliví klienti by si změny navzájem „kradli“, protože každé změně je přiřazen stav zpracování na úrovni access tokenu.

Aby bylo možné změny spolehlivě sledovat a zpracovávat, je tedy nutné:

• vytvořit samostatný access token pro každý samostatný systém/klienta,
• zajistit, že nedochází ke sdílení tokenu mezi více aplikacemi nebo procesy.

Endpointy pro práci se změnami

• query changes - Slouží k načtení změn v e-shopu. Po načtení je nutné tyto změny potvrdit pomocí mutace changesConfirm, jinak nebudou doručovány další nové změny.
• mutation changesConfirm - Slouží k potvrzení zpracovaných změn. Přijímá jedno ID změny, přičemž všechny změny s tímto ID a nižším budou považovány za potvrzené.
  • Například volání changesConfirm(changeId: 1000) potvrdí všechny změny s ID ≤ 1000 (včetně ID 1000).
• mutation changesReset - Slouží k resetování stavu zpracovaných změn – umožňuje znovu načítat změny od určitého data a času (např. v případě chyby při zpracování nebo potřeby opětovného importu).

Aktuálně podporované změny

• ProductChange - změna informací u produktu (název, popis, viditelnost atd...)
  • Obsahuje ID změněného produktu a názvy změněných polí. Následně je možné pomocí query products načíst změněné produkty a aktualizovat si je.
• ProductVariationChange - změna informací u varianty (název, viditelnost atd...)
  • Obsahuje ID změněné varianty a názvy změněných polí.
• ProductQuantityChange - změna skladové dostupnosti
  • Obsahuje ID produktu, ID varianty, ID skladu a zároveň novou a starou hodnotu skladu.
• ProductPriceChange - změna ceny
  • Obsahuje ID produktu, ID varianty, ID ceníku a zároveň novou a starou cenu i slevu.
• OrderChange - změna objednávky
• OrderItemChange - změna položky objednávky
• UserChange - změna uživatele
• UserBonusPointChange - změna bodů ve věrnostním programu u uživatele

Každá změna obsahuje metadata s obecnými údaji o změně

• id - unikátní ID změny
• action - typ změny (INSERT, UPDATE, DELETE)
• date - datum vzniku změny

Pro zjištění typu změny používejte pole __typename v GraphQL, které vrací typ objektu odpovídající konkrétnímu typu změny.

Do budoucna plánujeme postupné rozšiřování typů změn. Doporučujeme proto, aby vaše implementace zahrnovala logování neznámých nebo nezpracovaných typů změn – díky tomu budete mít přehled o tom, kdy začnou přicházet nové typy, které vaše aplikace zatím nezohledňuje.

Naopak v případě, že vás zajímá pouze určitý typ změn (např. změny ve skladu), doporučujeme všechny ostatní změny ignorovat a zpracovávat jen ty relevantní.

Jednotlivé typy změn jsou případně popsány v dokumentaci zde.

Příklad načítání změn je k vidění například v naší PHP knihovně pro komunikaci s API zde.

Queries

Seznam nejčastěji používaných queries k nimž jsou níže zpracovány příklady jejich využití.

Mutations

Seznam nejčastěji používaných mutations, k nimž jsou níže zpracovány příklady jejich využití.

Příklady

Načtení změn

query {
  changes(limit: 100) {
    __typename
    metadata {
      id
      action
      date
    }
    ... on ProductChange {
      productId
      changedFields
    }
    ... on ProductQuantityChange {
      productId
      variationId
      storeId
      quantity
      quantityPrevious
    }
    ... on ProductPriceChange {
      productId
      variationId
      priceListId
      price
      pricePrevious
      discount
      discountPrevious
    }
  }
}

Potvrzení změn

mutation {
  changesConfirm (id: 15) {
    result
  }
}

Vrácení změn zpět k datu

mutation {
  changesReset (date: "2024-04-01 00:00:00") {
    result
  }
}

Načtení objednávky

query {
  order(id: 1) {
    id
    code
    dateCreated
    status {
      id
      name
    }
    deliveryAddress {
      name
      surname
      street
      city
      zip
      country {
        code
        name
      }
    }
    items {
      name
      pieces
      totalPrice {
        withVat
        vat
        currency {
          code
        }
      }
    }
  }
}

Načtení seznamu objednávek

query {
  orders(limit: 50, sort: {dateCreated: ASC}, 
  filter: {dateCreated:{ge:"2024-02-01 00:00:00"}}) {
    hasNextPage
    hasPreviousPage
    items {
      id
      code
      dateCreated
      totalPrice {
        withVat
        withoutVat
      }
      currency {
        code
        name
      }
    }
  }
}

Načtení produktu

query {
  product(id:6185) {
    id
    url
    code
    ean
    inStore
    stores {
      store {
        id
        name
      }
      inStore
    }
    title
    price {
      withVat
      currency {
        code
      }
    }
    visible
    parameters {
      parameter{
        name
      }
      values {
        value
      }
    }
    variations {
      values {
        label {
          name
        }
        value
      }
    }
  }
}

Načtení seznamu produktů

query {
  products(limit: 10, sort: {title: ASC}, 
  filter: {dateUpdated: {ge: "2024-02-19 00:00:00"}}) {
    hasNextPage
    hasPreviousPage
    items {
      id
      code
      ean
      title
      visible
      inStore
      price {
        withVat
        currency {
          code
        }
      }
    }
  }
}

Načtení uživatele

query {
  user (email:"wpj@wpj.cz") {
    id
    name
    surname
    isActive
    dateLastOrder
    invoiceAddress {
      name
      surname
      firm
      phone
      street
      city
      zip
      country {
        code
      }
      ico
      dic
    }
  }
}

Načtení seznamu uživatelů

query {
  users (userSort:{id:ASC}, 
  userFilter: {dateRegistered: {ge:"2024-01-01" le:"2024-02-01"}}) {
    hasNextPage
    hasPreviousPage
    items{
      id
      email
      name
      surname
      newsletterInfo {
        isSubscribed
      }
    }
  }
}

Vytvoření nebo úprava produktu

mutation productCreateOrUpdate($product: ProductModifyInput!) {
  productCreateOrUpdate(product: $product) {
    result
    product {
      id        
      code
      title
      description
      price {
        withVat
      }
    }
  }
}

#vytvoření produktu
{
  "product": {
    "code": "abc1234",
    "title": "Nový produkt",
    "description": "Popis nového produktu",
    "price": {
      "priceWithVat": 121
    }
  }
}

#úprava produktu
{
  "product": {
    "id": 6273,
    "title": "Aktualizovaný název produktu",
    "description": "Aktualizovaná anotace produktu"
  }
}

Vytvoření nebo úprava varianty produktu

mutation variationCreateOrUpdate($variation: VariationModifyInput!) {
  variationCreateOrUpdate(variation: $variation) {
    result
    product {
      id
    }
    variation {
      id
      title
      values{
        label{
          name
        }
        value
      }
    }
  }
}

{
  "variation": {
     "productId": 6160,
     "visible": false,
     "title": "Velikost Apple Watch: 46mm",
     "labels": [{
        "label": "Velikost Apple Watch",
        "value": "46mm"
    }]
  }
}

Vytvoření objednávky

mutation orderCreate($order: OrderCreateInput!) {
  orderCreate(orderCreateInput: $order) {
    order {
      id
      code
      items{
        code
      }
      dateCreated
    }
  }
}

{
  "order":{
    "invoiceAddress": {
      "name": "Abc",
      "surname": "Cba",
      "street": "Abc 1403",
      "city": "test",
      "zip": "54301",
      "country": "CZ",
      "phone": "+420 123 456 789",
      "email": "test@wpj.cz"
    },
    "items": [
      {"productId": 1, "pieces":  1}
    ],
    "coupons": ["ABC123"],
    "deliveryTypeId": 1,
    "language": "cs",
    "dateDue": "2025-01-01 01:00:00",
    "currency": "EUR",
    "userId": 1
  }
}

Aktualizace objednávky

mutation orderUpdate($input: OrderUpdateInput!) {
  orderUpdate(input: $input) {
    result
    order {
      id,
      code
      dateCreated
      dateUpdated
      status {
        id
        name
      }
      deliveryInfo {
        packageId
      }
    }
  }
}

{
  "input": {
    "id": 105184,
    "status": {
      "id": 2,
      "comment": "Přiděleno číslo balíku 'abc123'"
    },
  	"packageId": "abc123"
  }
}

Storno objednávky

mutation orderStorno($input: OrderStornoInput!) {
  orderStorno(input: $input) {
    result
    order {
      id,
      code
      cancelled
      dateCreated
      dateHandle 
      status{
        name
      }
    }
  }
}

{
  "input": {
    "id": 105186,
    "message": "Storno z API",
    "sendMail": false
  }
}

Vytvoření nebo úprava uživatele

mutation userCreateOrUpdate($input: UserInput!) {
  userCreateOrUpdate(input: $input) {
    result
    user {
      id
      email
      userName
      dateRegistered
    }
  }
}

#vytvoření uživatele
{
  "input": {
    "email": "test@api.cz",
  	"isActive": true,
    "invoiceAddress": {
      "name": "Test",
      "surname": "Api",
      "street": "Lanovska 123",
      "city": "Vrchlabi",
      "zip": "54301",
      "country": "CZ",
      "phone": "123456789"
    }
  }
}

#úprava uživatele
{
  "input": {
    "id": 100393,
    "ico": "28860608",
    "dic": "CZ28860608",
    "invoiceAddress": {
	"firm": "wpj s.r.o."
    }
  }
}

Aktualizace ceny produktu v ceníku

mutation productPriceListUpdate($input: ProductPriceListInput!) {
  productPriceListUpdate(input: $input) {
    result
    product {
      id
      title
      price{
        withVat
      }
      priceLists{
        priceList{
          id
          name
        }
        price{
          withVat
        }
      }
    }
  }
}

{
  "input": {
    "productId": 6160,
    "priceListId": 9,
    "price": {
      "priceWithVat": 7800
    }
  }
}

Aktualizace stavu skladu u produktu

mutation productStoreUpdate($input: ProductStoreInput!) {
  productStoreUpdate(input: $input) {
    result
    product {
      id
      variations{
        id
        inStore
      }
      title
      inStore
      stores{
        store{
          id
        }
        inStore
      }
    }
  }
}

{
  "input": {
    "productId": 6160,
    "variationId":13380,  
    "storeId": 2,
    "quantity": 100
  }
}