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 opakowanie, quantity_in_pack - ilość sztuk w opakowaniu, points - liczba punktów, którą może zdobyć klient , stock - dostepna ilość opakowań, sku - numer ewidencyjny 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ć. Zrewiduj czy sku-234 to poprawny 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/ImportImporty 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:

1. Aktualizacja - zawiera oferty, które zostały zaktualizowane/dodane,
2. Nowe oferty - zawiera oferty oczekujące na aktualizację, jednak przy aktualizacji za pomocą API oferty te są automatycznie aktualizowane,
3. 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,
4. 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"
        }
    ]
}

Inny prawidłowy przykład:

{
    "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"
        }
    ]
}