Integracja przez API

Zmodyfikowano dnia pon, 7 Lip o 10:48 RANO

Jeśli potrzebujesz więcej szczegółowych informacji, zachęcamy do zapoznania się z oficjalną dokumentacją techniczną dostępną pod tym linkiem:

https://app.dealavo.com/api/v3/docs

Klucz API (api_key) oraz identyfikator konta (account_id) znajdziesz w zakładce “Moje konto” w sekcji "Publiczne API".

Limity

System narzuca limit maksymalnej liczby wierszy, które mogą być zwrócone w ramach jednego zapytania, wynoszący 20 000.

Ograniczenia danych

Dane udostępniane są na podstawie stanu aplikacji bezpośrednio po aktualizacji. Oznacza to, że wszelkie zmiany wprowadzone po ostatnim update, takie jak dodanie nowych etykiet, staną się widoczne dopiero po kolejnej aktualizacji.

Kolejność danych w raporcie

Wyniki zwracane przez API są domyślnie sortowane według kilku kryteriów, aby zapewnić spójność i intuicyjność danych:

Update Time: od najnowszych do najstarszych
Article: sortowanie według nazwy artykułu
Cena Oferty bez Wysyłki: sortowanie według ceny oferty

Autentykacja

Dostęp do API wymaga autentykacji przy użyciu klucza API (api_key) oraz identyfikatora konta (account_id).

https://app.dealavo.com/api/v3/updates?account_id=<account_id>&api_key=<api_key>

Endpoint’y

Lista Dostępnych Dat Aktualizacji

Żądanie GET: /api/v3/updates

https://app.dealavo.com/api/v3/updates?account_id=<account_id>&api_key=<api_key>

Endpoint ten zwraca listę dat, w których nastąpiły aktualizacje danych. Każda data jest zapisana w formacie YYYY_MM_DD_HH_MM, co umożliwia łatwą identyfikację konkretnego momentu aktualizacji.

Przykładowa odpowiedź:

{
    "update_dates": [
        "2024_03_13_12_00",
        "2024_03_13_06_00",
        "2024_03_12_23_30",
        "2024_03_12_18_00",
        "2024_03_12_12_00",
        "2024_03_12_06_00",
        "2024_03_11_23_30",
        "2024_03_11_18_00"
    ]
}

Lista Dostępnych Kolumn dla Klienta

Żądanie GET: /api/v3/columns

https://app.dealavo.com/api/v3/columns?account_id=<account_id>&api_key=<api_key>

Ten endpoint udostępnia kompletną listę kolumn, które są dostępne dla klienta w ramach danych raportów.

Przykładowa odpowiedź:

{
    "columns": [
        "Id",
        "Article",
        "Retailer",
        "Retailer offer name",
        "Retailer price",
        "Availability",
        "Wholesale price",
        "Source",
        "Labels",
        "Price",
        "Url",
        "Crossed out price",
        "Brand",
        "Catalogue Price",
        "Maximum Price",
        "Minimum Price",
        "Stock",
        "EAN",
        "Producer",
        "Product code",
        "Promotion description",
        "Url",
        "Price with shipping",
        "Previous price",
        "Vat",
        "Currency",
        "Original price",
        "Retailer price with shipping",
        "Update time"
    ]
}

Generowanie raportów

Żądanie POST: /api/v3/reports

https://app.dealavo.com/api/v3/report?account_id=<account_id>&api_key=<api_key>

{
    "columns": "all",
    "settings": {
        "csv_delimiter": ";",
        "nested_data_separator": ",",
        "page": 1
    }
}

Umożliwia generowanie raportów z możliwością konfiguracji:

Wybór kolumn

Użytkownik może określić, które kolumny powinny zostać uwzględnione w raporcie.
Kolumna "Update time" jest zawsze dodawana do wyników.
Kolejność kolumn w zwróconej csv jest identyczna do kolejności w zapytaniu.

Przykład wyboru specyficznych kolumn:

{
    "columns": ["Id", "Labels"]
}

Aby otrzymać wszystkie dostępne kolumny:

{
    "columns": "all"
}

Okres czasu

Możliwość określenia daty początkowej (start_date) i końcowej (end_date) dla danych zawartych w raporcie.

start_date: Data początkowa zakresu (włącznie), od której chcemy otrzymać dane.

end_date: Data końcowa zakresu (włącznie), do której chcemy otrzymać dane.

Daty podajemy w formacie YYYY_MM_DD_HH_MM np. 2024_03_30_13_00.

https://app.dealavo.com/api/v3/report?account_id=<account_id>&api_key=<api_key>

{
    "columns": "all",
    "start_date": "2024_01_01_10_00",
    "end_date": "2024_01_31_23_00",
    "settings": {
        "csv_delimiter": ";",
        "nested_data_separator": ",",
        "page": 1
    }
}

Settings

Konfiguracja dodatkowych ustawień raportu.

csv_delimiter

Pojedynczy znak, który będzie separatorem kolumn. Domyślnie ;.

Przykład z domyślnym separatorem:

Id;Availability;Update time
8591022201428;Unavailable, in assortment;2024_03_13_11_00
8591022201428;Available, in assortment;2024_03_13_11_00

Przykład przecinkiem jako separator i z tekstem zawierającym przecinek, otoczonym cudzysłowami:

Id,Availability,Update time
8591022201428,"Unavailable, in assortment",2024_03_13_11_00

Zasady dotyczące ujmowania stringów w cudzysłów:

Stringi zawierające separator:
Jeżeli w stringu znajduje się separator, jest on ujmowany w cudzysłów.
Przykład: Unavailable, in assortment → "Unavailable, in assortment"
Puste stringi:
Puste stringi zawsze są ujmowane w cudzysłów.
Przykład: nazwa,,opis → nazwa;"";opis
Inne stringi:
Stringi, które nie zawierają separatora i nie są puste, nie są ujmowane w cudzysłów.
Przykład: nazwa;opis → nazwa;opis

nested_data_separator

Separator używany dla wartości w kolumnach, które są listami, np. etykiety grup. Domyślnie przecinek ,.

Przykład z alternatywnym separatorem |:

Id;Labels;Update time
8591022201428;Happy green|promocja|single;2024_03_13_11_00

Dostępne separatory to: {",", ";", "|", "\t", " ", "&", ":", "+", "_"}

Paginacja

page

Numer strony z danymi, domyślnie 1.

W przypadku braku wyników dla danej strony, system zwróci kod błędu 500 oraz wiadomość:

{
    "error": "Exceeded the number of rows. Number of rows: 246312"
}

number_of_offers_per_page

Ilość wierszy z ofertami na stronę. Domyślnie 10 000. Maksymalnie 20 000.

only_available_offers

Flaga true/false, określająca, czy raport ma zawierać tylko aktualnie dostępne oferty. Domyślnie: false.

datetime_format

Opcja umożliwiająca zmianę formatu zwracanej daty kolumny Update time w raporcie.
Domyślny format: %Y_%m_%d_%H_%M. Szczegóły formatowania można znaleźć tutaj.

format

Domyślny format raportu to csv, ale dostępny jest również format json.

Generowanie raportu w formacie JSON

Raporty w formacie JSON zawierają dwa główne elementy:

columns: Lista nazw kolumn uwzględnionych w raporcie.
data: Dane raportu, przedstawione jako lista list, gdzie każda lista odpowiada jednemu wierszowi danych.

Przykładowy raport JSON:

{
    "columns": [
        "Id",
        "Article",
        "Retailer",
        "Retailer offer name"
    ],
    "data": [
        [
            "1182986505",
            "Animonda GranCarno Original Adult wołowina i jagnięcina 400g",
            "test_dev_front",
            "Animonda GranCarno Original Adult wołowina i jagnięcina 400g"
        ],
        [
            "1182986505",
            "Animonda GranCarno Original Adult wołowina i jagnięcina 400g",
            "kingofprice (allegro.pl)",
            "Animonda GranCarno 400g adult Wołowina Pur"
        ]
    ]
}

*do raportu w formacie JSON, nie jest automatycznie dodawana kolumna “Update time“

Postman

Więcej gotowych przykładów w kolekcji Postman:

https://drive.google.com/file/d/1rqBmUsdQh3O9qYFqnI7MvwqQM9Ta7B8G/view?usp=sharing