Az árak és készletadatok automatikus frissítésére a Merchant API-n keresztül van lehetőség.

Cél, hogy mindig a lehető leginkább naprakészen tartsuk az árakat és a termékek aktuális készletét, hogy elkerülhessük az esetleges vásárlói panaszokat, illetve az extra picker és ügyfélszolgálati munkát.

Javasoljuk, hogy az új árakat azonnal küldjék el nekünk, amint egy terméket átáraztak, az aktuális készletet pedig mindig küldjék felénk, ha egy termék készlete megváltozott a saját rendszerükben, de minimum óránként küldjenek egy frissítést a megváltozott adatokkal.

Leggyakrabban használt API hívások:

• updatePurchasables: termékek frissítése, pl. árak, készletadatok.

• deletePurchasable: termék törlése, ha pl. időszakosan nem elérhető a termék vagy megszűnik a termék forgalmazása.

Utolsó frissítés: 2025-06-10

API végpont

UAT: https://api.uat.avokado.com/merchant/api

PROD: https://api.avokado.com/merchant/api

Authentication

HTTP headerben kell küldeni az API tokent:

{
  "Authorization": "Bearer [AUTH_TOKEN]"
}

Bővebben a GraphQL-ről

https://graphql.org/

Javasolt GraphQL IDE

• Desktop:

  • https://github.com/prisma-labs/graphql-playground/releases

  • https://insomnia.rest/

• Google Chrome Extension: https://chrome.google.com/webstore/detail/graphql-playground-for-ch/kjhjcgclphafojaeeickcokfbhlegecd?hl=en

Elérhető funkciók

Árak és/vagy készletadatok frissítése/létrehozása

Az updatePurchasables mutation segítségével frissíthető egy termék egy adott boltban érvényes ára vagy árai és az aktuálisan elérhető szabad készletszintje. Ha még nem létezik az adott boltban a termékre érvényes Purchasable bejegyzés, a rendszer automatikusan létrehozza.

Fontos: létrehozáskor a rendszer hibát fog dobni, ha legalább egy ár nincs megadva!

Frissítéskor az ár nem kötelező. Ha például csak a készletszintet kell frissíteni, elegendő a “stock” paramétert küldeni.

Amennyiben egy terméknek nem kell a készletetét kezelni, akkor a “​​trackStockQuantity” pareméter értékét “false”-ra kell állítani és nem szükséges “stock” paramétert küldeni.

A “​​trackStockQuantity” paraméter opcionális és az alapértelmezett értéke “true”, ha érkezik a “stock” paraméterben bármilyen érték. Ha sem “stock”, sem “​​trackStockQuantity” pareméter sem érkezik, akkor a “​​trackStockQuantity” értéke automatikusan “false” lesz.

Ha egy termék esetében maximalizálni kell az rendelésen belül kosárba rakható mennyiséget, az a “maxOrderQuantity” 0-nál nagyobb értékével tehető meg. Az érték megadása új termék esetén is opcionális, alapértelmezetten 0, azaz nincs limit beállatva.

Az árak esetében, ahol a tól-ig időszak is megadásra kerül, a rendszer promóciós (akciós) árként kezeli. Amennyiben egy adatküldésen belül több ilyen (időszaki promóciós ár) érkezik, és a dátumok átfedésben vannak, az átfedéses időszakban az alacsonyabb ár lesz érvényes.

Figyelem! Minden adatküldés felülírja az előzőt! Tehát ha pl. egy termék esetében előre beküldésre kerül egy promóciós időszak, de a következő küldésben már nincs ott, akkor az első küldésben lévő adatok nem fognak érvényesülni.

Az adatküldésekkel kapcsolatban fontos, hogy az egy időpontban történő küldések esetén ne termékenként egy-egy külön request készüljön, hanem egy requestbe az összes módosult termék adatai kerüljenek bele.

Request

mutation ($update: [PurchasableStockPriceUpdateInput!]!) {
  updatePurchasables(storeId: "a6f4d42f-d2a9-40b7-8799-06a5973f4b64", update: $update)
}

{
  "update": [
    {
    "merchantProductId": 129740,

     "gtins": ["123456789123", "2233445566"],

     "maxOrderQuantity": 20,

     "stock": 100,

     "trackStockQuantity": true,
    "prices": [
        {
          "amount": 1520,
          "currency": "HUF"
        },{
          "amount": 1420,
          "currency": "HUF"
        },{
          "amount": 1020,
          "currency": "HUF",
          "label": "most csak 1",
          "validSince": "2022-10-01",
          "validUntil": "2022-12-31"
        }
      ]
    }
  ]
}

* merchantProductId: termék egyedi azonosító (pl. SKU).

Egy mutationben akár több termék is beküldhető és lehet külön frissíteni az árakat vagy a készletadatokat, az alábbi példa ezt mutatja.

{
  "update": [
    {
    "merchantProductId": 129740,
    "stock": 100
    },{
    "merchantProductId": 26625,
    "stock": 120
    }
  ]
}

Response

{
  "data": {
    "updatePurchasables": "e5f0e477-a8dd-45c3-92f6-2b9a6a411023"
  }
}

cURL request példa

curl -g \

-X POST \

-H "Content-Type: application/json" \

-H "Authorization: Bearer [API_TOKEN]" \

-d '{"query": "mutation ($update: [PurchasableStockPriceUpdateInput!]!) { updatePurchasables(storeId: \"a6f4d42f-d2a9-40b7-8799-06a5973f4b64\", update: $update) }", "variables" : "{ \"update\": [ { \"merchantProductId\": 123456, \"stock\": 111 },{ \"merchantProductId\": 654321, \"stock\": 222 } ] }" }' \

https://api.avokado.com/merchant/api

Árak és készletadat frissítések státusza

A getUpdatePurchasablesStatusForAll query segítségével lekérdezhető az updatePurchasables mutation használatával beküldött frissítések állapota.

Request

query getUpdateStatus {

  getUpdatePurchasablesStatusForAll(listOptions: { control: { limit: 2 } }) {

count

result {

       merchantProductId

       code

       message

       startedAt

       finishedAt

}

  }

}

Response

{

  "data": {

"getUpdatePurchasablesStatusForAll": {

   "count": 137071,

   "result": [

     {

       "merchantProductId": "101590100101",

       "code": 400,

       "message": "purchasable not found",

       "startedAt": null,

       "finishedAt": null

     },

     {

       "merchantProductId": "101590100101",

       "code": 400,

       "message": "purchasable not found",

       "startedAt": null,

       "finishedAt": null

     }

   ]

}

  }

}

Árak és készletadatok lekérdezése

A purchasable query segítségével lekérdezhető, hogy egy bizonyos termék egy adott boltban milyen ár(akk)al és készletszinttel szerepel.

Request

{
  purchasable(storeId: "a6f4d42f-d2a9-40b7-8799-06a5973f4b64", merchantProductId: 129740) {
    id
    product {
      id
      title
    }
    prices {
      amount
      currency
      validSince
      validUntil
      label
    }
    stock
  }
}

Response

{
  "data": {
    "purchasable": {
      "id": "125f4e2b-0327-4d8e-b5e2-7c0b671642d0",
      "product": {
        "id": "130415",
        "title": "Algoflex Forte Dolo 400 mg filmtabletta 30 db"
      },
      "prices": [
        {
          "amount": 30443,
          "currency": "HUF",
          "validSince": null,
          "validUntil": null,
          "label": "teszt"
        }
      ],
      "stock": 551
    }
  },
  "extensions": {}
}

Termékek listázása

A purchasableList query segítségével listázható, hogy egy adott boltban milyen ár(akk)al és készletszinttel milyen terméklista található a rendszerben.

Request

query purchasableList(

  $storeSlug: String

  $listOptions: PurchasableListOptions

) {

  purchasableList(storeSlug: $storeSlug, listOptions: $listOptions) {

count

result {

     id

     stock

     identifiers {

         type

         value

     }

     maxOrderQuantity

     prices {

         amount

         currency

         validSince

         validUntil

         label

         unitPrice

         unitServing {

       size

       unit

       isEstimated

         }

     }

     product {

         id

         title

         slug

     }

}

  }

}

listOptions

limit: default 100

Response

{

  "data": {

"purchasableList": {

   "count": 42,

   "result": [

     {

       "id": "190a4605-2dd4-473c-b825-87b01c6de5dc",

       "stock": 10,

       "maxOrderQuantity": null,

       "prices": [

         {

           "amount": 16990,

           "currency": "HUF",

           "validSince": null,

           "validUntil": null,

           "label": null,

           "unitPrice": 16990,

           "unitServing": null

         }

       ],

       "product": {

         "id": "384794",

         "title": "Brazil Bélszín",

         "slug": "brazil-belszin"

       }

     },

     {

       "id": "5eb2d1ee-a2b6-47a9-bcfb-106a6b0b8e37",

       "stock": 10,

       "maxOrderQuantity": null,

       "prices": [

         {

           "amount": 13990,

           "currency": "HUF",

           "validSince": null,

           "validUntil": null,

           "label": null,

           "unitPrice": 13990,

           "unitServing": null

         }

       ],

       "product": {

         "id": "384810",

         "title": "Magyar Érlelt Hátszín",

         "slug": "erlelt-marha-hatszin"

       }

     }

   ]

}

  }

}

Termék törlése

Termék törlésével a megadott boltban megszűnik a termék árusítása, listázása. A törlés után a terméklistákban nem jelenik meg, de a korábban leadott rendeléseknél még elérhető marad megtekintésre. A funkció hívásához a bolt azonosítóra (opcionális) és a termék külső azonosítójának megadására van szükség. Ha nincs megadva a bolt azonosító a kereskedő összes boltjából törlődik a termék.

Request

mutation deletePurchasable($storeId: ID, $merchantProductId: ID!) {

  deletePurchasable(storeId: $storeId, merchantProductId: $merchantProductId)

}

Response

{

  "data": {

"deletePurchasable": null

  }

}

Boltok listája

A boltok listájával kérdezhetők le a rendszerben jelenleg aktivált fizikai üzletek.

Az ID-ra ahhoz van szükség, hogy a termékek adott boltra érvényes árát és készletadatát be lehessen küldeni.

Request

{
  storeList {
    count
    result {
      id
      name

      slug
    }
  }
}

Response

{
  "data": {
    "storeList": {
      "count": 1,
      "result": [
        {
          "id": "a6f4d42f-d2a9-40b7-8799-06a5973f4b64",
          "name": "Körúti Viktória Gyógyszertár"

          “slug”: "koruti-viktoria-gyogyszertar"
        }
      ]
    }
  }
}

cURL request példa

curl -g \

-X POST \

-H "Content-Type: application/json" \

-H "Authorization: Bearer [API_TOKEN]" \

-d '{"query":"{storeList {count result { id name slug }}}"}' \

https://api.avokado.com/merchant/api

Számla utólagos feltöltése rendeléshez

Abban az esetben ha a számla utólag kerül feltöltésre (pl. ha a számlázás a kasszázás után történik meg így a picker nem tudja fotózni az alkalmazáson keresztül) az alábbi szolgáltatás segítségével lehet csatolni. A megrendelés azonosítása történhet rendelés azonosító vagy ügyfélkártya alapján. Ügyfélkártya azonosításkor az utolsó sikeres megrendeléshez lesz csatolva a feltöltött számla.

A response VOID típusú, hibás feltöltés esetén a szabványos GraphQL hibaüzenet tartalmazza a hiba forrását.

Request

mutation uploadOrderInvoiceDocument(

  $orderId: ID

  $orderPublicId: ID

  $customerCardId: ID

  $file: Upload!

) {

  uploadOrderInvoiceDocument(

    orderId: $orderId

    orderPublicId: $orderPublicId

    customerCardId: $customerCardId

    invoiceDocumentType: EXTERNAL_ORDER_PRODUCT_INVOICE

    file: $file

  )

}

cURL request példa

curl --location 'https://api.avokado.com/merchant/api' \

--header 'Content-Type: application/json' \

--header 'Authorization: [API_TOKEN]' \

--data '{"query":"mutation uploadOrderInvoiceDocument(\n  $orderId: ID\n  $orderPublicId: ID\n  $customerCardId: ID\n  $file: Upload!\n) {\n  uploadOrderInvoiceDocument(\n    orderId: $orderId\n    orderPublicId: $orderPublicId\n    customerCardId: $customerCardId\n    invoiceDocumentType: EXTERNAL_ORDER_PRODUCT_INVOICE\n    file: $file\n  )\n}","variables":{"0":["[FILE_BOUNDARY_ID]"],"orderPublicId":"[AVOKADO_ORDER_ID]"}}'

Rendelések letöltése

Az Avokado által küldött webhook tartalma

{

  "id": "162686.121862229",

  "type": "order.notification",

  "order": {

    "id": "1A2B/2",

    "venue_id": "f7c77c1c-d1db-4a33-bf43-ce6f4d7d680b",

    "status": "READY",

    "resource_url": "https://api.avokado.com/merchant/w/orders/d234b1a4-b004-4922-84d7-a7bc287c47de"

  },

  "created_at": "2025-02-11T13:22:09.038Z"

}