API – integracja oferty

Zastosowanie

Endpoint import-offer służy do przesyłania nowych ofert na konto dystrybutora oraz aktualizacji istniejących ofert. W przypadku braku symbolu SKU oferty, która jest wysyłana, następuje próba utworzenia nowej oferty.

Specyfikacja

Request:

POST https://drinks2cash.com/api/import-offer/json 
Content-Type: application/json 
Authorization: <api_key_dystrybutora>

Body:

{
   "price_promotion_from": string date, <opcjonalne>
   "price_promotion_to": string date, <opcjonalne>
   "offers": [
      {
          "ean": string,
          "price": float,
          "quantity_in_pack": int,
          "points": int,
          "stock": int,
          "sku": string,
          "promotion_price": float|null,
          "name": string
      }
]
}

W body należy przesłać tablicę obiektów, które reprezentują oferty, gdzie:
ean – EAN,
price – cena netto za sztukę,
quantity_in_pack – ilość sztuk w opakowaniu,
points – liczba punktów, którą może zdobyć klient w programie lojalnościowym
stock – dostepna ilość opakowań,
sku – numer ewidencyjny produktu w bazie dystrybutora,
name – nazwa produktu.

W nagłówku authorisation należy przesłać swój api_key, który jest dostępny po zalogowaniu na stronie:
Oferty -> Import: https://drinks2cash.com/order/admin-importer.

Responses:

HTTP 200 OK

{
    "code": 200,
    "reasonPhrase": "OK",
    "message": {
        "summarise": "Added: 200 offers. Error in: 1.",
        "errors": [
            {
                "sku": "sku-234",
                "message": "Product doesn't have a package defined for EAN: 8011701090087, SKU: sku-234."
            }
        ]
    }
}

W przypadku napotkania problemu podczas dodawania oferty, import nie zostanie przerwany, a informacje o niezaimportowanych produktach zostaną zwrócone w „errors”. W przypadku wystąpienia błędów należy sprawdzić sekcję „Sprawdzenie importu” w tej dokumentacji.

Możliwe powody niezaimportowania:

Błędy walidacji:
1. „Missing column, required 7 are: 1-EAN, 2-price, 3-quantity in package, 4-point’s number, 5-quantity, 6-SKU, 7-name”
W strukturze przesłanych danych brakuje kolumny. Poprawna struktura to:1- EAN, 2-cena, 3-ilość w opakowaniu, 4-liczba punktów, 5-ilość, 6-SKU, 7-nazwa

2. „EAN too short or EAN is empty. Min.5 chars”
Przesłany EAN jest zbyt krótki, minimalna ilość znaków to 5.

3. „SKU too short or SKU is empty. Min. 3 chars”
SKU jest zbyt krótkie, minimalna ilość znaków to 3.

4. „Number of points must be a number”
Przesłana liczba punktów nie jest liczbą całkowitą

5. „It was sent 2 products with the same SKU: sku-123”
Przesłano co najmniej dwa produkty z tym samym, podanym SKU.

6. „Quantity in the package must be a number”
Ilośc w opakowaniu musi być zwykłą liczbą całkowitą.

7. „Incorrect price”
Przesłana cena nie jest liczbą całkowitą lub z przecinkiem lub jest liczbą ujemną.

Błędy spójności danych:
1. „Product doesn’t have a package defined for EAN: 8011701090087, SKU: sku-234.”
Wskazany produkt nie ma zdefiniowanego opakowania w systemie drinks2cash. Przed kolejną próbą importu zdefiniuj opakowanie dla tego EAN-u na stronie https://drinks2cash.com/product/admin-product.

2. „There is an offer for EAN: 8011701090087, check whether you provided proper SKU: sku-234.”
Pod wskazanym EAN próbujesz zaimportować kilka ofert z różnym SKU. Zrewiduj tą ofertę na liście ofert https://drinks2cash-dev.test.essyo.pl/distributor/admin-distributor/offer-list i usuń nadmiarową albo z listy albo z pliku importu/ json-a.

3. „Product EAN: 8011701090087 and SKU: sku-234 have an offer with the same SKU.”
Pod wskazanym SKU istnieje oferta ze wskazanym w treści komunikatu EAN-em i jest to inny EAN od tego, który chcesz zaimportować. Sprawdź czy sku-234 to poprawne SKU dla tego produktu.

4. „Maximum points exceed for product with EAN: 8011701090087, number of points was decreased to 30% of value”
Komunikat wskazuje, że dla wskazanego EAN próbujesz zaimportować/ zdefiniować wiekszą ilość punktów niż jest możliwa. System automatycznie zmniejszył ilość punktów do 30% wartości oferty.

HTTP 403 Forbidden

{
    "code": 403,
    "reasonPhrase": "Forbidden",
    "message": "Unauthorised"
}

Nie zidentyfikowano użytkownika. Należy sprawdzić poprawność api_key w panelu użytkownika dostępnym pod adresem: https://drinks2cash.com/order/admin-importer

HTTP 400 – Bad requestBody:

{
    "code": 400,
    "reasonPhrase": "Bad request",
    "data": "price_promotion_from and price_promotion_to must be a valid date"
}

Data rozpoczęcia i zakończenia promocji nie jest obowiązkowa, ale jeśli jest błedna otrzymasz ten komunikat błedu. Poprawna data to „2023-01-02”. Body:

{
    "code": 400,
    "reasonPhrase": "Bad request",
    "data": "Invalid syntax, Missing offers key"
}

W składni JSON brakuje klucza „offers”.

Sprawdzenie importu

Szczegóły importu w przejrzystej formie są dostępne w panelu administracyjnym w zakładce oferty -> import.

Importy wykonane poprzez API mają w kolumnie plik nazwę „API Import from IP”, co odróżnia je od importów z pliku .csv, które mają w tej kolumnie nazwę pliku. Szczegółowe informacje można znaleźć w czterech zakładkach:

Aktualizacja – zawiera oferty, które zostały zaktualizowane/dodane,
Nowe oferty – zawiera oferty oczekujące na aktualizację, jednak przy aktualizacji za pomocą API oferty te są automatycznie aktualizowane,
Niedostępne – zawiera oferty, których nie ma jeszcze w bazie produktów. Zdarza się to rzadko, ale w przypadku takich sytuacji zaleca się skorzystanie z opcji „zgłoś” w celu dodania nowego produktu,
Duplikaty – zawiera produkty o tym samym EAN znalezione podczas importu.

Przykład

HTTP POST https://drinks2cash.com/api/import-offer/json Content-Type: application/jsonAuthorization: <api_key_dystrybutora> Przykład prawidłowej struktury json w request body:

{
    "price_promotion_from": "203/1-02",
    "price_promotion_to": "2023-01-03",
    "offers": [
        {
            "ean": "8011701090087",
            "price": 100.23,
            "quantity_in_pack": 6,
            "points": 67,
            "stock": 200,
            "sku": "sku-234",
            "price_promotion": 23.33,
            "name": "Soplica 700ml"
        },
        {
            "ean": "0008055684020594",
            "price": 300.22,
            "quantity_in_pack": 1,
            "points": 67,
            "stock": 200,
            "sku": "ert99901",
            "price_promotion": null,
            "name": "Wyborowa 200ml"
        },
        {
            "ean": "5201006000185",
            "price": 232.23,
            "quantity_in_pack": 1,
            "points": 67,
            "stock": 200,
            "sku": "256KIP",
            "price_promotion": 242,
            "name": "Jack Daniels 500ml"
        }
    ]
}

Kolejny przykład prawidłowej struktury:

{
    "offers": [
        {
            "ean": "8011701090087",
            "price": 100.23,
            "quantity_in_pack": 6,
            "points": 67,
            "stock": 200,
            "sku": "sku-234",
            "price_promotion": 23.33,
            "name": "Soplica 700ml"
        },
        {
            "ean": "0008055684020594",
            "price": 300.22,
            "quantity_in_pack": 1,
            "points": 67,
            "stock": 200,
            "sku": "ert99901",
            "price_promotion": 23.33,
            "name": "Wyborowa 200ml"
        },
        {
            "ean": "5201006000185",
            "price": 232.23,
            "quantity_in_pack": 1,
            "points": 67,
            "stock": 200,
            "sku": "256KIP",
            "price_promotion": 23.33,
            "name": "Jack Daniels 500ml"
        }
    ]
}

API – integracja oferty

Zastosowanie

Specyfikacja

Sprawdzenie importu

Przykład

Dodaj komentarz