API zewnętrzne – integracja sklepu internetowego

API zewnętrzne AMPER (/external/v1/) udostępnia do odczytu katalog produktów, kategorie, zdjęcia, stany magazynowe, promocje i rodzaje wysyłki. Dane są zawsze widziane oczami jednego klienta (kontrahenta) – z jego cenami, asortymentem i promocjami. Typowe zastosowania: zasilenie sklepu internetowego, porównywarki cenowej albo wygenerowanie pliku XML.

Przykładowy projekt: Examplegenerator projectpliku -XML generatingdla CENEO.PL XML file.

Prerequisites

Czego potrzebujesz

1. Adres serwera AMPER APIWS KEY– np. https://amper-xyz-ws.ampliapps.com (w przykładach: {amper_ws_url}).
2. AMPERKlucz webAPI serivce– URLidentyfikator w formacie UUID (w przykładach: {amper_api_key}).

ToOba getotrzymasz those,od please, contact withdziału IT supportfirmy, ofz companyktórą yousię wantintegrujesz. toKlucz integrategeneruje with.administrator w panelu AMPER i przypisuje go do konkretnego konta klienta.

Example requestUwierzytelnienie

C#Klucz przekazujesz w parametrze api_key w adresie każdego zapytania:

varGET client = new RestClient("https://{amper_ws_url}/external/v1/products/?api_key={amper_api_key}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

• API obsługuje wyłącznie metodę GET.
• Klucz jest przypisany do konta klienta: API zwraca produkty dostępne dla tego klienta, jego ceny i jego promocje – tak, jak widzi je w sklepie B2B.
• Klucz ma datę ważności i administrator może go wyłączyć. Wygasły lub wyłączony klucz daje odpowiedź 401.
• Klucz daje dostęp do danych handlowych klienta. Przechowuj go po stronie serwera – nigdy w kodzie strony www ani aplikacji mobilnej.

Dostępne zasoby

Każdy zasób ma listę (/external/v1/<zasób>/) i odczyt pojedynczego obiektu (/external/v1/<zasób>/{id}/).

Przydatne filtry:

• /external/v1/products/?ids=101,205,317 – tylko wskazane produkty,
• /external/v1/products/?category_id=12 – produkty z kategorii,
• /external/v1/product-files/?product=101 albo ?product_external_id=SKU-ABC-001 – zdjęcia jednego produktu.

Paginacja

• NodeJSBez parametrów
   odpowiedź zawiera całą listę jako tablicę JSON.
• Z parametrami limit i offset odpowiedź jest stroną w kopercie:

var request = require('request');
var options = {
  'method'"count": 'GET',1817,
  'url'"next": 'http:"https://{amper_ws_url}/external/v1/products/?api_key={amper_api_key}'...&limit=500&offset=500",
  };"previous": request(options,null,
  function"results": (error,[ response)... {
  if (error) throw new Error(error);
  console.log(response.body);]
});

Przy dużym katalogu pobieraj dane stronami (np. limit=500), aż next będzie równe null.

Limity

• PHPNajwyżej CURL3 jednoczesne zapytania na klucz.
   Kolejne dostają odpowiedź 429 Too Many Requests z nagłówkiem Retry-After: 1 – odczekaj wskazaną liczbę sekund i ponów zapytanie. Strony pobieraj po kolei albo najwyżej dwie, trzy naraz.
• Około 800 zapytań na minutę z jednego adresu IP.
• Dane katalogowe (produkty, kategorie, zdjęcia) zmieniają się rzadko – wystarczy je odświeżać co kilka godzin. Częściej odświeżaj tylko stany i ceny. Nie pobieraj całego katalogu co kilka minut.

Odpowiedzi

Produkt

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'http://{amper_ws_url}/external/v1/products/?api_key={amper_api_key}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests

url = "http://{amper_ws_url}/external/v1/products/?api_key={amper_api_key}"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

replace "amper_ws_url" and "amper_api_key" with your data

Response

As a response you will get JSON. Example response with list of products

[
    {
  "id": 1037,
  "name": "BAHAMA zapach samochodowy NASZYJNIK Wild Hibiskus /1szt",
  "friendly_name": "Zapach samochodowy Bahama Wild Hibiskus",
  "short_code": "850267",
  "description": "Zapachy inspirowane wakacjami oraz trendami konsumenckimi.",
  Bahama"short_description": & Co. to nie tylko akcesoria do samochodu, ale również atrakcyjne gadżety, stanowiące element dekoracyjny."",
  "ean": "978020137962"5904000850267",
  "sku": "850267",
  "cn_code": "33074900",
  "vat": 23,
  "default_unit_of_measure": "szt.",
  "weight": "0.20",
  "default_price": 25.43,
  "25.43"currency_code": }"PLN",
  "product_external_id": "850267",
  "list_price": 29.90,
  "cumulative_unit_of_measure": "karton",
  "cumulative_converter": "24.00",
  "can_be_split": true,
  "cumulative_unit_ratio_splitter": "6.00",
  "unit_roundup": false,
  "capacity": null,
  "stock_availability_customer": 1,
  "brand": "Bahama & Co.",
  "manufacturer": "Bahama",
  "attributes": [
    {
      "id": 1034,4,
      "slug": "zapach",
      "name": "VORTEX TKANINA wielofunkcyjna z mikrofibry /1szt"Zapach",
      "short_code"values": "623765",
        "description": "Uniwersalne zastosowanie",
        "ean": "978020137962",
        "sku": "623765",
        "vat": 23,
        "default_unit_of_measure": "op.",
        "weight": "0.38",
        "default_price": "31.52"
    },[
        { "id": 951,31, "name": "CALIFORNIA zapach samochodowy SCENT CONTROL Ice /1szt"Hibiskus", "short_code"slug": "851233"hibiskus-31", "description"selected": true, "Papieroweicon": zawieszkinull zapachowe:}
      \nInnowacyjna technologia dostosowania intensywności zapachu – wystarczy odpowiednio ustawić zawieszkę. \nPapier pokryty zapachowymi olejkami.\nW zestawie sznurek umożliwiający wygodne zawieszanie zapachu. \nDostępne zapachy: Coronado cherry; Ice; New Car; Sea Breeze"],
      "ean"color": null,
      "978020137962"show_on_tile": false
    }
  ],
  "sku"deposit_pack_multiplier": "851233",null,
  "vat"deposit_pack_price": 23,null,
  "default_unit_of_measure"deposit_pack_type": "szt.",
        "weight": "0.33",
        "default_price": "18.38"null
},
 ]

Available methods

Here is a list of available methods. HTTP method that is allowed: GET

Products

With this method you can get list of products.

Methods

Kategoria

{ "id": 12, "name": "Zapachy samochodowe", "description": "", "category_external_id": "KAT-012" }

category_external_id to ID kategorii w systemie ERP.

CategoriesPrzypisanie produktu do kategorii

{ "product_id": 1037, "category_id": 12 }

Zdjęcie produktu

{ "product_id": 1037, "image": "https://.../products/850267.jpg", "order": 1, "product_external_id": "850267" }

order to kolejność zdjęć – zdjęcie z najniższą wartością jest główne.

Stan magazynowy

WithJeden thiswiersz methodna youprodukt, canzsumowany getze listwszystkich of categories.magazynów:

Methods

{ "product_id": 1037, "availability": "medium", "quantity": 150 }

Rodzaj

Relation between Product and Categorieswysyłki

{ "id": 3, "name": "Kurier" }

Thisid methodprzekazujesz returnsjako allshipment_type_id bindingsprzy oftworzeniu product to categorieszamówienia.

Methods

Kody odpowiedzi

Product files

Przykłady

ThisW methodprzykładach returnszastąp all{amper_ws_url} filesi attached{amper_api_key} toswoimi productdanymi.

curl

curl 

ThisPython method– returnspobranie prodct'scałego stockskatalogu stronami, z obsługą limitu:

import 

using var client = new HttpClient { Timeout = TimeSpan.FromMinutes(2) };
var url = "https://{amper_ws_url}/external/v1/stocks/

ThisNode.js method(18 returnsi listnowsze, ofwbudowany promotionsfetch)

const 

$curl of= promotions