FusionSystem Dokumentacja API

wersja API: v1.7 - stan na dzień 5 listopada 2018

Wstęp

FusionSystem to aplikacja marketingowa oferująca możliwość tworzenia wysokiej jakości stron satelitarnych, przechwytujących wartościowy ruch (generowanie leadów sprzedażowych). Poniższa dokumentacja API skierowana jest do developerów, właścicieli kont klienckich i agencji chcących zintegrować własne rozwiązania ze swoim kontem.

Komunikacja

API systemu FusionSystem zostało zrealizowane w modelu REST. Wykorzystuje protokół szyfrowany HTTPS (połączenia nieszyfrowane nie są obsługiwane). Komunikacja polega na wysłaniu żądania POST (parametry wysłane metodą POST mają wyższy priorytet) lub GET (maksymalna długość 8100 znaków) pod adres https://panel.fusionsystem.pl/apiv1 z użyciem kluczy autoryzacyjnych APIKEY oraz SECRETKEY. Dane zwracane są w formacie JSON. Wymiana danych odbywa się z użyciem kodowania UTF-8. W limicie długości parametrów, należy uwzględnić znaki UTF-8, które nie są liczone jako jeden znak.

API zbudowane jest z metod pogrupowanych tematycznie w moduły. Uprawnienia dostępu do poszczególnych modułów nadawane są przez administratora.
Żądania dotyczące domen IDN można kierować do api w dowolnej formie, odpowiedź zaź zwracana jest zawsze z znakami specjalnymi. Lista domen w zapytaniu nie może przekraczać 250 nazw.

Żądanie

Ścieżka dostępu:

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=MODULE&action=ACTION&key1=value1&...

gdzie:

Nazwa Opis
apikey Twój klucz APIKEY - 16 znakowy losowy ciąg znaków alfanumerycznych, przykład: 218e37ea356d0dna
secretkey Twój SECRETKEY - 32 znakowy losowy ciąg znaków alfanumerycznych, przykład: d943e000b7a3d1be2d1b5a1eb699b847
module Nazwa modułu
action Nazwa akcji do wykonania
key1 Dodatkowy parametr dla akcji. Opis parametrów wymaganych przez akcję znajdziesz w przy jej opisie.

W parametrach należy umieścić odpowiedni typ danych. Mimo iż w praktyce nie można zdefiniować typu zmiennej w QueryString, nadal serwer może odrzucić dane które nie mogą być poprawnie zinterpretowane (np. dla bool wartość "pizza"). Dodatkowe wymagania dla parametrów są zapisane w opisie akcji.

Typ parametru Dopuszczalne wartości
Boolean Przyjmowane wartości: true, yes, tak, 1 lub false, no, nie, 0. Inne wartości są traktowane jak brak parametru.
Integer Liczba z zakresu -9223372036854775808 - 9223372036854775807. Inne wartości są rzutowane jako tekst na integer.
String Tekst w kodowaniu utf-8, niepoprawne znaki spowodują błąd 1007.
Enum Jedna z wartości podanych w opisie parametru. Inne wartości są traktowane jak brak parametru.

Przykładowe zapytanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=profile&action=ping

Odpowiedź

Odpowiedź jest zwracana w formacie obiektu JSON.

Struktura odpowiedzi może zostać przedstawiona za pomocą prostej tabeli:

Nazwa indeksu Typ Opis
status Integer Otrzymuje wartość 1 gdy zapytanie jest poprawne i dostępne są dane zwrotne, w każdym innym przypadku 0.
data Object lub Array Występuje gdy status jest równy 1. Opis przyjmowanych wartości znajduje się w poszczególnych akcjach.
error Integer Występuje gdy status jest równy 0. Znaczenie błędów można odczytać z sekcji Kody błędów
message String Może wystąpić gdy status jest równy 0. Występuje sporadycznie, nie jest równoznaczny z kodem błędu i jedynie opisuje specyficzny dla danej akcji błąd.

Przykładowa odpowiedź

{
    "status": 1,
    "data": {
        "pong": 1370044800
    }
}

Uwaga! Dla czytelności dokumentacji kod odpowiedzi został sformatowany. W odpowiedzi na żądanie API zwracany jest niesformatowany obiekt JSON.

Moduł domain

Moduł zawiera zestaw akcji pozwalających na odczyt i modyfikację stron reklamowych dostępnych na koncie. W przyszłości zostanie udostępnione dodatkowe możliwości.

list

Wyświetla aktualną listę stron reklamowych (domen) zarejestrowanych na koncie.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=domain&action=list

Dodatkowe parametry:

Nazwa indeksu Wartość Opis
details
opcjonalne
true lub false Rozszerza zwracaną listę o parametry marketingowe domen: referring domains, backlinks, site, pagerank, trust i power gdzie 2 ostatnie to autorskie współczynniki (skala od 0 do 100). Parametr trust wyraża współczynnik zaufania Google'a do domeny a power określa jej moc pozycjonującą. Im wyższa wartość tym lepiej.

Odpowiedź

{
    "status": 1,
    "data": {
        "domena1.test.pl": {
            "id": 1,
            "name": "domena1.test.pl",
            "created": 1380733092,
            "expiration": 1412269151,
            "active": "on",
            "status": "active",
            "articles": 18
        },
        "domena2.test.pl": {
            "id": 2,
            "name": "domena2.test.pl",
            "created": 1389098973,
            "expiration": 1420635407,
            "active": "on",
            "status": "active",
            "articles": 24
        },
        "domena3.test.pl": {
            "id": 3,
            "name": "domena3.test.pl",
            "created": 1400172964,
            "expiration": 1431709022,
            "active": "off",
            "status": "active",
            "articles": 6
        }
    }
}

Odpowiedź w postaci object, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:

Nazwa indeksu Typ Opis
id Integer Identyfikator domeny w systemie
name String Nazwa domeny
created Integer Znacznik czasowy zawierający datę rejestracji domeny
expiration Integer or Null Zwraca znacznik czasowy daty wygaśnięcia domeny lub null gdy niedostępny
active String Czy domena jest włączona on, off
status String Tekstowy status domeny w języku angielskim. Możliwe wartości: pending, active, expired, unknown
articles Integer Liczba artykułów w domenie
backlinks Integer Dla details=true
site Integer Dla details=true
pagerank Integer Dla details=true
referring Integer Dla details=true
trust Integer Dla details=true
power Integer Dla details=true

screenshot

Zwraca aktualny zrzut ekranu strony zakodowany za pomocą algorytmu base64. Zrzut ekranu odświeżany jest maksymalnie co 3 dni.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=domain&action=screenshot&domains=domena1.test.pl;domena2.test.pl

Dodatkowe parametry:

Nazwa indeksu Opis
domains Nazwy domen rozdzielone średnikiem (;) lub pojedyncza domena

Odpowiedź

{
    "status": 1,
    "data": {
        "domena1.test.pl": {
            "image": "b2JyYXplayB6YWtvZG93YW55IHogdcW8eWNpZW0gYmFzZTY0",
            "mime": "image\/png"
        },
        "domena2.test.pl": {
            "image": null
        }
    }
}

Odpowiedź w postaci object, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:

Nazwa indeksu Typ Opis
image String or Null Zawiera obrazek zakodowany z użyciem base64 lub null gdy np. nie został jeszcze wykonany
mime
opcjonalne
String Typ mime obrazu

commit

Wymuszenie aktualizacji strony reklamowej na serwerze satelitarnym (opublikowanie zmian).

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=domain&action=commit&domain=domena1.test.pl

Dodatkowe parametry:

Nazwa indeksu Opis
domain Nazwa domeny

Odpowiedź

{
    "status": 1,
    "data": "ok"
}

Odpowiedź zawiera string "ok".

Moduł article

Zawiera zestaw akcji listujący wszystkie artykuły i kategorie przypisane do konkretnej domeny wraz z szczegółowymi informacjami dodatkowymi np. ilość znaków.

add

Dodanie nowego artykułu w danej domenie.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=add&domain=domena1.test.pl&name=Kompania%20w%C4%99glowa&title=Kompania%20w%C4%99glowa&text=%3Cp%3EZatrudniaj%C4%85ca%20blisko%2060%20tys.%20os%C3%B3b%20Kompania%20W%C4%99glowa%20znajduje%20si%C4%99%20w%20krytycznym%20po%C5%82o%C5%BCeniu.%3C%2Fp%3E

Dodatkowe parametry:

Nazwa indeksu Opis
domain Nazwa domeny
name Nazwa, maksymalnie 150 znaków.
title Tytuł, maksymalnie 150 znaków.
text Treść, może zawierać tagi html, jednak kod nie jest optymalizowany tak jak w panelu, zalecamy formatowanie tekstu przez panel. Kolejne akapity należy umieszczać w tagach <p>.
category
opcjonalne
Id kategorii lub 0 (brak).
description
opcjonalne
Opis artykułu, maksymalnie 250 znaków.
keywords
opcjonalne
Słowa kluczowe lub tagi, oddzielone przecinkiem, maksymalnie 250 znaków.
date
opcjonalne
Planowana data publikacji w formacie DD-MM-YYYY lub jako znacznik czasowy UNIXTIMESTAMP.
check
opcjonalne
Sprawdzanie unikalności tekstu, domyślnie true. W przypadku duplikatu zwracany jest błąd 2099.

Odpowiedź

{
    "status": 1,
    "data": {
        "id": 20
    }
}

Odpowiedź zawiera obiekt:

Nazwa indeksu Typ Opis
id Integer Identyfikator nowego artykułu w sysytemie

edit

Edycja artykułu w danej domenie.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=add&article=20&name=Kompania%20w%C4%99glowa&title=Kompania%20w%C4%99glowa

Porada: Edycja umożliwia zmianę jednej lub wielu kolumn. Daną wartość można wyczyścić podając pusty parametr. Pola, które nie mają być edytowane, NIE MOGĄ pojawić się w zapytaniu. Brak jakiegokolwiek pola poskutkuje błędem 2001. Nie można też podać pustych wartości dla name, title, text, inaczej zostanie zwrócony błąd 1005.

Dodatkowe parametry:

Nazwa indeksu Opis
article
wymagane
Identyfikator artykułu
name Nazwa, maksymalnie 150 znaków, nie może być pusta.
title Tytuł, maksymalnie 150 znaków, nie może być pusty.
text Treść, nie może być pusta, może zawierać tagi html, jednak kod nie jest optymalizowany tak jak w panelu, zalecamy formatowanie tekstu przez panel. Kolejne akapity należy umieszczać w tagach <p>.
category Id kategorii lub 0 (brak).
description Opis artykułu, maksymalnie 250 znaków.
keywords Słowa kluczowe lub tagi, oddzielone przecinkiem, maksymalnie 250 znaków.
date Planowana data publikacji w formacie DD-MM-YYYY lub jako znacznik czasowy UNIXTIMESTAMP.
check Sprawdzanie unikalności tekstu, domyślnie true. W przypadku duplikatu zwracany jest błąd 2099. Działa tylko przy podaniu parametru text

Odpowiedź

{
    "status": 1,
    "data": {
        "id": 20
    }
}

Odpowiedź zawiera obiekt:

Nazwa indeksu Typ Opis
id Integer Identyfikator artykułu w sysytemie

list

Wyświetla aktualną listę artykułów danej domeny.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=list&domains=domena1.test.pl;domena2.test.pl

Dodatkowe parametry:

Nazwa indeksu Opis
domains Nazwy domen rozdzielone średnikiem (;) lub pojedyncza domena
content Zwracanie treści i plików, domyślnie false.

Odpowiedź

{
    "status": 1,
    "data": {
        "domena1.test.pl": [
            {
                "id": 1890,
                "name": "Ostrze\u017cenie przed zawiejami",
                "title": "Ostrze\u017cenie przed zawiejami",
                "publicated": 1390867200,
                "charcount": 1818,
                "category": "Jeden",
                "description": "Na og\u00f3\u0142 pochmurno, \u015bnie\u017cnie, wietrznie i mro\u017ano - takie s\u0105 prognozy na najbli\u017csze dni. Na p\u00f3\u0142nocnym-wschodzie Polski termometry maj\u0105 wskazywa\u0107 w \u015brod\u0119 nawet minus 10...",
                "tags": [
                    "organizm"
                ]
            },
            {
                "id": 240,
                "name": "Policja: Jed\u017amy wolniej i ostro\u017cniej",
                "title": "Policja: Jed\u017amy wolniej i ostro\u017cniej",
                "publicated": 1390867200,
                "charcount": 1083,
                "category": "Dwa",
                "description": "Jed\u017amy wolniej i ostro\u017cniej - apeluje policja. W ca\u0142ym kraju jazd\u0119 utrudnia zalegaj\u0105cy \u015bnieg albo b\u0142oto po\u015bniegowe i \u015bliska nawierzchnia. - W takich warunkach dochodzi...",
                "tags": [
                    "organizm"
                ]
            }
        ],
        "domena2.test.pl": [
            {
                "id": 560,
                "name": "Kompania w\u0119glowa",
                "title": "Kompania w\u0119glowa",
                "publicated": 1381401970,
                "charcount": 3766,
                "category": "Wegiel brunatny",
                "description": "Zatrudniaj\u0105ca blisko 60 tys. os\u00f3b Kompania W\u0119glowa znajduje si\u0119 w krytycznym po\u0142o\u017ceniu. Do sierpnia firma mia\u0142a 341 mln z\u0142 straty. Wed\u0142ug informacji &quot;Rzeczpospolitej&quot; jej sytuacja finansowa w tym roku pozostaje pod tak du\u017c\u0105 presj\u0105, \u017ce g\u0142\u00f3wnym ce",
                "tags": [
                    "gerardin",
                    "musi",
                    "przysz\u0142o\u015bci",
                    "sytuacji",
                    "wobec"
                ]
            },
            {
                "id": 78,
                "name": "Reprezentacja polski",
                "title": "Reprezentacja polski",
                "publicated": 1381402136,
                "charcount": 1202,
                "category": "Pi\u0142ka no\u017cna",
                "description": "Tylko cud mo\u017ce sprawi\u0107, \u017ce pi\u0142karska reprezentacja Polski pod wodz\u0105 Waldemara Fornalika wywalczy awans do mistrzostw \u015bwiata w Brazylii. Z historii znamy jednak wielu...",
                "tags": [
                    "gerardin",
                    "musi",
                    "przysz\u0142o\u015bci",
                    "sytuacji",
                    "wobec"
                ]
            }
        ]
    }
}

Odpowiedź w postaci object, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:

Nazwa indeksu Typ Opis
id Integer Identyfikator artykułu w sysytemie
name String Nazwa artykułu
title String Tytuł artykułu
publicated Integer Zwraca znacznik czasowy daty publikacji artykułu
charcount Integer Ilość znaków artykułu liczona ze spacjami
category String Nazwa kategorii do której artykuł został przypisany
description String Opis artykułu
tags Array[String] Słowa kluczowe artykułu
url String Link do artykułu
text String Treść artykułu (HTML). Dla content=true
files Array[String] Linki do załączonych plików. Dla content=true
categoryid Integer or null Identyfikator kategorii

visits

Wyświetla ilość wizyt dla artykułu w podanym miesiącu lub dniu.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=visits&year=2014&month=4&day=28&articles=1890;78

Dodatkowe parametry:

Nazwa indeksu Opis
articles Identyfikatory artykułów rozdzielone średnikiem (;) lub pojedyncza domena
year Rok którego statystyki chcemy otrzymać
month Miesiąc którego statystyki chcemy otrzymać
day
opcjonalne
Dzień którego statystyki chcemy otrzymać

Odpowiedź

{
    "status": 1,
    "data": {
        "1890": {
            "20140428": {
                "pages": 18,
                "visits": 11
            }
        },
        "70": {
            "20140428": {
                "pages": 36,
                "visits": 2
            }
        }
    }
}

Odpowiedź w postaci object, gdzie indeksy to identyfikatory artykułów, a wartości zawierają obiekty o podanej strukturze:

Nazwa indeksu Typ Opis
pages Integer Ilość odsłon wygenerowana przez unikalnych użytkowników
visits Integer Ilość unikalnych wizyt użytkowników

categories

Wyświetla aktualną listę kategorii danej domeny.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=categories&domains=domena1.test.pl;domena2.test.pl

Dodatkowe parametry:

Nazwa indeksu Opis
domains Nazwy domen rozdzielone średnikiem (;) lub pojedyncza domena

Odpowiedź

{
    "status": 1,
    "data": {
        "domena1.test.pl": [
            {
                "id": 12,
                "name": "Jeden",
                "title": "",
                "url": null
            },
            {
                "id": 13,
                "name": "Dwa",
                "title": "Drugi",
                "url": null
            }
        ],
        "domena2.test.pl": [
            {
                "id": 17,
                "name": "Wegiel brunatny",
                "title": "",
                "url": "\/wegiel-b.html"
            },
            {
                "id": 19,
                "name": "Pi\u0142ka no\u017cna",
                "title": "",
                "url": null
            }
        ]
    }
}

Odpowiedź w postaci object, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:

Nazwa indeksu Typ Opis
id String Identyfikator kategorii
name String Nazwa kategorii
title String Title (opcjonalne)
url String or Null Zdefiniowany adres URL (opcjonalne)

categoryadd

Dodanie nowej kategorii w danej domenie.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=article&action=categoryadd&domain=domena1.test.pl&name=Kategoria+1

Dodatkowe parametry:

Nazwa indeksu Opis
domain Nazwa domeny
name Nazwa, maksymalnie 150 znaków.
title
opcjonalne
Tytuł, maksymalnie 150 znaków.
url
opcjonalne
Adres url dla kategorii

Odpowiedź

{
    "status": 1,
    "data": {
        "id": 20
    }
}

Odpowiedź zawiera obiekt:

Nazwa indeksu Typ Opis
id Integer Identyfikator nowej kategorii w sysytemie

Moduł file

Moduł do zarządzania plikami.

upload

Pozwala na wgranie zdjęć i dokumentów do menadżera plików. Przed wgraniem sprawdzana jest obecność danego pliku, a w przypadku znalezienia duplikatu zwracany jest link do oryginalnego pliku. W dziale Przykładowe skrypty znajduje się użyteczny kod, który może posłużyć jako wzorzec. Akcja może zwrócić błąd z zakresu 2071-2076.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=file&action=upload

Dodatkowe parametry:

Nazwa indeksu Wartość Opis
type
opcjonalne
image lub doc Pozwala na wybranie zakładki do której zostanie wgrany plik

Pliki:

Nazwa indeksu Opis
file Plik wysłany jako POST multipart/form-data

Odpowiedź

{
    "status": 1,
    "data": {
        "file_status": "uploaded",
        "url": "\/resources\/library\/image\/aabbccdd\/aaaabbbbccccddddeeeeffff_t3.png"
    }
}

Odpowiedź w postaci obiektu o podanej strukturze:

Nazwa indeksu Typ Opis
file_status String uploaded dla poprawie wgranego pliku lub found jeśli plik został już znaleziony na koncie
url String Adres względny do obrazu, powinien być używany w img src w niezmienionej postaci

Moduł campaign

Moduł do zarządzania kampaniami.

list

Wyświetla aktualną listę kampanii na koncie.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=campaign&action=list

Dodatkowe parametry:

Nazwa indeksu Wartość Opis
details
opcjonalne
true lub false Rozszerza zwracaną listę o parametry marketingowe domen: referring domains, backlinks, site, pagerank, trust i power (więcej domain / list) oraz myreferring i mybacklinks, które odnoszą się do linków z własnych stron reklamowych.

Odpowiedź

{
    "status": 1,
    "data": [
        {
            "id": 1,
            "name": "domena1.test.pl",
            "created": 1380733092
        },
        {
            "id": 2,
            "name": "domena2.test.pl",
            "created": 1389098973
        },
        {
            "id": 3,
            "name": "domena3.test.pl",
            "created": 1400172964
        }
    ]
}

Odpowiedź w postaci array, gdzie wartości zawierają obiekty o podanej strukturze:

Nazwa indeksu Typ Opis
id Integer Identyfikator kampanii w systemie
name String Nazwa domeny
created Integer Znacznik czasowy zawierający datę dodania kampanii
backlinks Integer Dla details=true
site Integer Dla details=true
pagerank Integer Dla details=true
referring Integer Dla details=true
trust Integer Dla details=true
power Integer Dla details=true
mybacklinks Integer Dla details=true Z własnych stron reklamowych.
myreferring Integer Dla details=true Z własnych stron reklamowych.

screenshot

Zwraca aktualny zrzut ekranu strony zakodowany za pomocą algorytmu base64. Zrzut ekranu odświeżany jest maksymalnie co 3 dni.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=campaign&action=screenshot&campaigns=domena1.test.pl;domena2.test.pl

Dodatkowe parametry:

Nazwa indeksu Opis
campaigns Nazwy kampanii rozdzielone średnikiem (;) lub pojedyncza domena

Odpowiedź

{
    "status": 1,
    "data": {
        "domena1.test.pl": {
            "image": "b2JyYXplayB6YWtvZG93YW55IHogdcW8eWNpZW0gYmFzZTY0",
            "mime": "image\/png"
        },
        "domena2.test.pl": {
            "image": null
        }
    }
}

Odpowiedź w postaci object, gdzie indeksy to nazwy kampanii, a wartości zawierają obiekty o podanej strukturze:

Nazwa indeksu Typ Opis
image String or Null Zawiera obrazek zakodowany z użyciem base64 lub null gdy np. nie został jeszcze wykonany
mime
opcjonalne
String Typ mime obrazu

position

Wyświetla wszystkie monitorowane słowa kluczowe wraz z aktualnymi pozycjami, opcjonalnie z historią pozycji dla wybranej daty.

Uwaga Jeśli zostanie wybranych kilka wyszukiwarek do monitorowania. Funkcja position może wtedy zwracać pozycje z danego dnia dla przypadkowej wyszukiwarki. Ewentualne zapotrzebowanie na wsparcie wielu wyszukiwarek w API prosimy zgłaszać na adres podany w stopce.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=campaign&action=position&campaigns=domena1.test.pl;domena2.test.pl

Dodatkowe parametry:

Nazwa indeksu Opis
campaigns Nazwy kampanii rozdzielone średnikiem (;) lub pojedyncza kampania
year Rok z którego raport pozycji chcemy pobrać
month Miesiąc z którego raport pozycji chcemy pobrać
day
opcjonalne
Dzień z którego raport pozycji chcemy pobrać

Wskazówka Możesz pominąć year i month, aby otrzymać ostatnią zanotowaną pozycję.

Odpowiedź

{
    "status": 1,
    "data": {
        "domena1.test.pl": {
            "konto bankowe": {
                "20140710": 41
            },
            "karta kredytowa": {
                "20140711": 6
            }
        },
        "domena2.test.pl": {
            "dobry dermatolog krak\u00f3w": {
                "20140711": 1
            },
            "dobry dermatolog": {
                "20140710": 9
            }
        }
    }
}

Odpowiedź w postaci object, gdzie indeksy to nazwy domen, a wartości zawierają obiekty strukturze fraza:historia, gdzie historia jest zbiorem dzień:wartość :

Nazwa Opis
dzień Dzień w formacie YYYYMMDD
wartość Pozycja na której została wykryta monitorowana fraza lub null jeśli nie ma danych z dnia albo nie znaleziono frazy w wynikach

pdf

Wygenerowanie raportu pozycji dla kampanii.

Uwaga Jeśli kampania nie istniała w podanym miesiącu, zostanie zwrócony błąd 1006 ze wskazaniem na błędne kolumny year,month.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=campaign&action=pdf&campaign=domena1.test.pl&year=2016&month=2

Dodatkowe parametry:

Nazwa indeksu Opis
campaign Nazwa kampanii
year Rok dla którego ma być wygenerowany raport
month Miesiąc

Odpowiedź

{
    "status": 1,
    "data": {
        "expiration": 1487942936,
        "file": "https:\/\/panel.fusionsystem.pl\/temporary\/campaign_report\/00000001-0000000002\/domain1.pl-luty-2016-a1b2c3.pdf"
    }
}

Odpowiedź zawiera obiekt:

Nazwa indeksu Typ Opis
expiration Integer Czas na pobranie pliku PDF w postaci znacznika czasowego UNIXTIMESTAMP, po którym zostanie usunięty. Zazwyczaj będzie to 24 godziny.
file String Bezpośredni adres pliku PDF.

Moduł stats

Moduł statyczny. Zawiera akcje pozwalające na odczyt liczby odwiedzin/odsłon domen jak i konkretnych artykułów.

visits

Pobiera statystyki odwiedzin i odsłon danej domeny/domen.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=stats&action=visits&year=2014&month=7&day=28&domains=domena1.test.pl;domena2.test.pl

Dodatkowe parametry:

Nazwa indeksu Opis
domains Nazwy domen rozdzielone średnikiem (;) lub pojedyncza domena
year Rok którego statystyki chcemy otrzymać
month Miesiąc którego statystyki chcemy otrzymać
day
opcjonalne
Dzień którego statystyki chcemy otrzymać

Odpowiedź

{
    "status": 1,
    "data": {
        "domena1.test.pl": {
            "20140728": {
                "pages": 427,
                "visits": 311
            }
        },
        "domena2.test.pl": {
            "20140728": {
                "pages": 1027,
                "visits": 783
            }
        }
    }
}

Odpowiedź w postaci object, gdzie indeksy to nazwy domen, a wartości zawierają obiekty o podanej strukturze:

Nazwa indeksu Typ Opis
pages Integer Ilość odsłon wygenerowana przez unikalnych użytkowników
visits Integer Ilość unikalnych wizyt użytkowników

Moduł text

Moduł zawiera zestaw akcji pozwalających na zarządzanie zleceniami działu copywritingu. Samo działanie modułu zostało przedstawione w artykule pomocy.

Zalecany sposób implementacji modułu:

  • order - wysłanie zlecenia
  • list( status=done ) - okresowe sprawdzanie gotowych tekstów
  • list( id=1;2;5, text=true ) - pobranie potrzebnych tekstów
  • update( id=1;2;5, status=used ) - oznaczenie pobranych tekstów jako wykorzystane

order

Zlecenie nowego tekstu do parafrazy lub streszczenia. Poprawnie wykonana akcja spowoduje pobranie środków z konta. W przypadku braku wystarczających środków na koncie, zostanie zwrócony błąd 2003. Wykonanie zapytania może trwać ponad minutę, zazwyczaj wystarczy kilka sekund, jednak należy ustawić odpowiednio duży timeout.

Uwaga Zlecenia trafiają do copywriterów nie związanych bezpośrednio z panelem FusionSystem, zamówienia testowe prosimy zatem wysyłać z użyciem parametru test=true lub wybierając potrzebne teksty w ostatecznych testach. Pozwoli to uniknąć niepotrzebnych nieporozumień.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=text&action=order&domain=domena1.test.pl&length=1000&premium=true&text=%3Cp%3EZatrudniaj%C4%85ca%20blisko%2060%20tys.%20os%C3%B3b%20Kompania%20W%C4%99glowa%20znajduje%20si%C4%99%20w%20krytycznym%20po%C5%82o%C5%BCeniu.%3C%2Fp%3E

Dodatkowe parametry:

Nazwa indeksu Typ Opis
domain String Nazwa domeny
length Integer Docelowa długość tekstu, minimalnie 300, maksymalnie 10000, liczba podzielna przez 100.
text String Tekst do parafrazy, minimalnie 300 znaków, maksymalnie 60000 znaków, bez tagów html.
count
opcjonalne
Integer Liczba zamawianych tekstów, z zakresu 1-10. Domyślnie: 1
Uwaga Teksty są rozdzielane na różnych copywriterów, osobne zlecenia mogą trafić do tego samego pracownika.
premium
opcjonalne
Boolean Tekst w jakości premium. Domyślnie: false
paraphrase
opcjonalne
Boolean Zleć parafrazę (w przeciwnym wypadku streszczenie). Domyślnie: true
test
opcjonalne
Boolean Test wysłania zlecenia. Domyślnie: false
Uwaga Za testowe zlecenie nie pobierzemy opłaty, count zostanie ograniczony do 2, a zlecony tekst zostanie automatycznie odesłany jako wykonane zlecenie.

Odpowiedź

{
    "status": 1,
    "data": {
        "id": [
            20
        ],
        "cost": 110,
        "count": 1
    }
}

Odpowiedź zawiera obiekt:

Nazwa indeksu Typ Opis
id Array[Integer] Identyfikatory zleceń w sysytemie
cost Integer Naliczona kwota EF
count Integer Liczba zleconych tekstów, może być mniejsza niż żądana gdy nie będzie możliwe wysłanie części zleceń. Należy zgłosić.
Jeśli nie zostanie wysłane żadne zlecenie, zamiast wartości 0 pojawi się błąd 2090

list

Pobieranie listy zleceń

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=text&action=list&domain=domena1.test.pl&status=done

Dodatkowe parametry:

Nazwa indeksu Typ Opis
domain String Nazwa domeny
id
opcjonalne
String Identyfikatory zleceń rozdzielone średnikiem
status
opcjonalne
Enum Filtruj status zlecenia: pending, done, used lub any (brak filtrowania). Domyślnie any
premium
opcjonalne
Boolean Filtruj zlecenia premium: true, false, any (brak filtrowania). Domyślnie any
text
opcjonalne
Boolean Pokaż zrealizowany tekst. Domyślnie false
Uwaga Ustawienie tego parametru ograniczy ilość zwróconych rekordów do 25. Opcji nie należy używać przy sprawdzaniu stanu zleceń.

Odpowiedź

{
    "status": 1,
    "data": [
        {
            "id": "1",
            "created": "1471007589",
            "received": "1471008855",
            "length": "300",
            "cost": "33",
            "premium": "1",
            "status": "done"
        },
        {
            "id": "3",
            "created": "1471007601",
            "received": "1471008863",
            "length": "300",
            "cost": "12",
            "premium": "0",
            "status": "done"
        }
    ]
}

Odpowiedź zawiera tablicę obiektów:

Nazwa indeksu Typ Opis
id Integer Identyfikator zlecenia
created Integer
UNIXTIMESTAMP
Czas wysłania zlecenia
received Integer lub null
UNIXTIMESTAMP
Czas otrzymania gotowego tekstu.
length Integer Oczekiwana długość tekstu
cost Integer Koszt zlecenia
premium Boolean Zlecenie w jakości premium
status String Status zlecenia: pending - w realizacji, done - wykonane, used - tekst wykorzystany
Dla text=true
title String lub null Tytuł sparafrazowanego tekstu
text String lub null Gotowy tekst

update

Zmiana statusu zlecenia. Zlecenie musi mieć status done lub used, nie można też zmienić statusu dla tekstów użytych w panelu.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=text&action=list&domain=domena1.test.pl&id=1;2;5&status=used

Dodatkowe parametry:

Nazwa indeksu Typ Opis
domain String Nazwa domeny
id String Identyfikatory zleceń rozdzielone średnikiem
status Enum Status do ustawienia: done lub used

Odpowiedź

{
    "status": 1,
    "data": {
        "count": 3
    }
}

Odpowiedź zawiera obiekt:

Nazwa indeksu Typ Opis
count Integer Liczba znalezionych zleceń

Moduł position

Udostępnia akcje umożliwiające wykonanie eksportu raportów pozycji według następujących kryteriów: domen i czasu.

list

Wyświetla wszystkie monitorowane słowa kluczowe domeny wraz z aktualnymi pozycjami, opcjonalnie z historią pozycji dla wybranej daty.

Uwaga Jeśli zostanie wybranych kilka wyszukiwarek do monitorowania. Funkcja list może wtedy zwracać pozycje z danego dnia dla przypadkowej wyszukiwarki. Ewentualne zapotrzebowanie na wsparcie wielu wyszukiwarek w API prosimy zgłaszać na adres podany w stopce.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=position&action=list&domains=domena1.test.pl;domena2.test.pl

Dodatkowe parametry:

Nazwa indeksu Opis
domains Nazwy domen rozdzielone średnikiem (;) lub pojedyncza domena
year Rok z którego raport pozycji chcemy pobrać
month Miesiąc z którego raport pozycji chcemy pobrać
day
opcjonalne
Dzień z którego raport pozycji chcemy pobrać

Wskazówka Możesz pominąć year i month, aby otrzymać ostatnią zanotowaną pozycję.

Odpowiedź

{
    "status": 1,
    "data": {
        "domena1.test.pl": {
            "konto bankowe": {
                "20140710": 41
            },
            "karta kredytowa": {
                "20140711": 6
            }
        },
        "domena2.test.pl": {
            "dobry dermatolog krak\u00f3w": {
                "20140711": 1
            },
            "dobry dermatolog": {
                "20140710": 9
            }
        }
    }
}

Odpowiedź w postaci object, gdzie indeksy to nazwy domen, a wartości zawierają obiekty strukturze fraza:historia, gdzie historia jest zbiorem dzień:wartość :

Nazwa Opis
dzień Dzień w formacie YYYYMMDD
wartość Pozycja na której została wykryta monitorowana fraza lub null jeśli nie ma danych z dnia albo nie znaleziono frazy w wynikach

pdf

Wygenerowanie raportu pozycji dla strony reklamowej.

Uwaga Jeśli strona nie istniała w systemie w podanym miesiącu, zostanie zwrócony błąd 1006 ze wskazaniem na błędne kolumny year,month.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=position&action=pdf&domain=domena1.test.pl&year=2016&month=2

Dodatkowe parametry:

Nazwa indeksu Opis
domain Nazwa domeny
year Rok dla którego ma być wygenerowany raport
month Miesiąc

Odpowiedź

{
    "status": 1,
    "data": {
        "expiration": 1487942936,
        "file": "https:\/\/panel.fusionsystem.pl\/temporary\/domain_report\/00000001-0000000002\/domain1.pl-luty-2016-a1b2c3.pdf"
    }
}

Odpowiedź zawiera obiekt:

Nazwa indeksu Typ Opis
expiration Integer Czas na pobranie pliku PDF w postaci znacznika czasowego UNIXTIMESTAMP, po którym zostanie usunięty. Zazwyczaj będzie to 24 godziny.
file String Bezpośredni adres pliku PDF.

Moduł profile

Wyświetla podstawowe informacje o koncie klienta oraz dostępnych dla niego zasobach i limitach.

about

Wyświetla podstawowe informacje o koncie.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=profile&action=about

Odpowiedź

{
    "status": 1,
    "data": {
        "id": 187,
        "login": "kontotestowe",
        "name": "Ambro\u017cy Fusion",
        "created": 1377599421,
        "expiration": null,
        "balance": 4212
    }
}

Struktura odpowiedzi:

Nazwa indeksu Typ Opis
id Integer Identyfikator użytkownika
login String Login użytkownika do systemu
name String Nazwa użytkownika
created Integer Znacznik czasowy zawierający datę utworzenia konta
expiration Integer lub null Znacznik czasowy zawierający datę wygaśnięcia konta. Gdy null to konto jest bezterminowe.
balance Integer Saldo punktów przedpłaconych (EuroFusion)

ping

Prosta akcja służąca do weryfikacji połączenia.

Przykładowe zapytanie

Żądanie

https://panel.fusionsystem.pl/apiv1?apikey=APIKEY&secretkey=SECRETKEY&module=profile&action=ping

Odpowiedź

{
    "status": 1,
    "data": {
        "pong": 1406647280
    }
}

Struktura odpowiedzi:

Nazwa indeksu Typ Opis
pong Integer Aktualna data serwera w postaci znacznika czasowego UNIXTIMESTAMP

Przykładowe skrypty

Uwaga! Publikowane skrypty zostały przetestowane z wykorzystaniem parsera PHP w wersji 5.4

Uniwersalna klasa PHP do połączenia i obsługi żądań API

Wykorzystywana przy pozostałych przykładach.

<?php

/**
 * Wyjątek dla klasy
 */
class FSApiException extends Exception {
	public $fromApi = false;
	function __construct($message, $code = 0, $fromApi = false){
		$this->fromApi = $fromApi;

		parent::__construct($message, $code);
	}
}
/**
 *  Przykładowa klasa do połączeń z API FusionSystem
 */
class FSApi {
	private $apikey		= null;
	private $secretkey	= null;

	# czas oczekiwania na odpowiedź
	public $timeout		= 30;

	public function __construct( $apikey, $secretkey ){
		# zapis kluczy
		$this->apikey		= $apikey;
		$this->secretkey	= $secretkey;
	}

	public function send( $module, $action, $params = Array(), $files = Array() ){
		# łączenie zapytania z kluczami
		$params = array_merge(
			(array) $params,
			Array(
				'apikey'	=> $this->apikey,
				'secretkey'	=> $this->secretkey,
				'module'	=> $module,
				'action'	=> $action,
			)
		);

		$curl = curl_init();

		# tworzenie QUERY_STRING
		$encoded_params = http_build_query( $params );

		# sprawdzanie długości zapytania (wysłanie przy użyciu GET jest często szybsze)
		$use_post = ( strlen( $encoded_params ) > 4000 );

		# adres API
		$url = 'https://panel.fusionsystem.pl/apiv1';
		
		# wysyłka z użyciem GET
		if(!$use_post)
			$url .= '?' . $encoded_params;

		curl_setopt( $curl,	CURLOPT_URL,			$url );
		curl_setopt( $curl,	CURLOPT_RETURNTRANSFER,	1 );
		curl_setopt( $curl,	CURLOPT_TIMEOUT,		$this->timeout );
		curl_setopt( $curl,	CURLOPT_HEADER,			0 );

		# jeśli są wysyłane pliki..
		if(count($files)){
			# czyszczenie parametrów, jeśli zostały już dodane w QUERY_STRING
			if( !$use_post )
				$params = Array();

			# załączanie plików w parametrach
			foreach($files as $key => $file){
				# php 5.5+
				if(version_compare(PHP_VERSION, '5.5.0') >= 0){
					$params[$key] = new CURLFile($file);
				# przed php 5.5
				} else {
					$params[$key] = '@'. realpath($file);
				}
			}

			# upload jako multipart
			curl_setopt( $curl,	CURLOPT_POST,		1 );
			curl_setopt( $curl,	CURLOPT_HTTPHEADER,	Array( 'Content-type: multipart/form-data' ) );
			curl_setopt( $curl,	CURLOPT_POSTFIELDS,	$params );
		} else {
			# niezbędne jest ustawienie kilku opcji przy metodzie POST
			if( $use_post ){
				curl_setopt( $curl,	CURLOPT_POST,		1 );
				curl_setopt( $curl,	CURLOPT_HTTPHEADER,	Array( 'Content-type: application/x-www-form-urlencoded' ) );
				curl_setopt( $curl,	CURLOPT_POSTFIELDS,	$encoded_params );
			}
		}

		$response = curl_exec( $curl );

		# błąd curl
		if(curl_errno($curl) > 0)
			throw new FSApiException( curl_error($curl), curl_errno($curl), false );

		curl_close( $curl );

		$response = json_decode( $response, true );

		# brak odpowiedzi / nieprawidłowy JSON
		if( !isset( $response['status'] ) )
			throw new FSApiException( 'Brak odpowiedzi lub nieprawidłowy JSON.' , 0, false );

		# błąd zwrócony przez api
		if( $response['status'] !== 1 )
			throw new FSApiException( "Błąd #{$response['error']}" . ( isset($response['message']) ? ": {$response['message']}" : '' ) , $response['error'] , true);

		# zwrócenie danych
		return $response['data'];
	}
}

Pobieranie listy domen wraz z zrzutami ekranów

Przykład użycia klasy do połączenia z API FusionSystem, wyświetlający domeny wraz z ich aktualnymi zrzutami ekranów.

<?php

# klasa do połączeń z api
require_once( 'fsapi.class.php' );

# kodowanie strony
header('Content-Type: text/html; charset=utf-8');

# utworzenie obiektu
$api = new fsapi( '__APIKEY__', '__SECRETKEY__' );

# pobieranie listy domen
$domains = $api->send( 'domain', 'list' );

# pobieranie zrzutów stron
$screenshot = $api->send( 'domain', 'screenshot', Array(
													'domains' => implode( ';', array_keys($domains) )
												) );

# wyświetlenie danych w czytelnej postaci
foreach( $domains as $name => $info ){
	$created = date( 'r', $info['created'] );
	$image = isset( $screenshot[$name]['image'] )
				? "<img src='data:{$screenshot[$name]['mime']};base64,{$screenshot[$name]['image']}' title='{$name}' />"
				: "<i>Brak zrzutu</i>";
	echo "
		<p>
			<strong>{$info['name']}</strong><br>
			Status: {$info['status']}<br>
			<small>Data utworzenia: {$created}<br></small>
			{$image}
		</p>
	";
}

Wgranie grafiki i dodanie artykułu

Przykład wgrania pliku oraz późniejszego użycia go w nowym artykule.

Uwaga Poniższy kod wymaga aktualnej wersji klasy php załączonej powyżej.

<?php

# klasa do połączeń z api
require_once( 'fsapi.class.php' );

# kodowanie strony
header('Content-Type: text/html; charset=utf-8');

# utworzenie obiektu
$api = new fsapi( '__APIKEY__', '__SECRETKEY__' );

# wgranie grafiki
$file = $api->send( 'file', 'upload', [], ['file' => './banner.png'] );

# dodanie artykułu zawierającego grafikę
$api->send( 'article', 'add', [
	'domain'=>'domena.pl',
	'name'=>'Artykuł z grafiką', 'title'=>'Artykuł z grafiką',
	# atrybuty alt oraz style są opcjonalne
	# jeśli wymiary będą inne niż wybranego pliku, grafika zostanie dopasowana przed eksportem
	'text'=>'<p>Oto jest grafika <img alt="" src="'. $file['url'] .'"  style="width: 487px; height: 169px;" /></p>'
	] );

# eksport danych na stronę reklamową
$api->send( 'domain', 'commit', ['domain'=>'domena.pl'] );

Kody błędów

Lista zwracanych kodów błedów wraz z legendą.

Numer błędu Opis
1000Brak odpowiedzi (prosimy zgłosić)
1001Brak autoryzacji / Błędne dane
1002Nieznany moduł / Konto nie posiada wystarczających uprawnień
1003Nieznana akcja
1004Brak uprawnień / Ograniczenie klucza API
1005Brak wymaganych parametrów dla wybranej akcji (message zawiera nazwę parametru)
1006Zasób nie istnieje lub konto nie jest jego właścicielem (message zawiera nazwę parametru)
1007Żądanie używa znaków z poza kodowania utf-8
2001Brak wybranego parametru do edycji
2002Parametr poza zakresem (message zawiera nazwę parametru)
2003Brak wystarczających środków na wykonanie akcji (message zawiera koszt)
2071Plik nie został wysłany
2072Osiągnięto maksymalną liczbę wgranych plików w ciągu 48 godzin
2073Przekroczono dopuszczalny rozmiar pliku
2074Niedozwolony typ pliku
2075Obraz jest zbyt mały
2076Obraz ma nieobsługiwany format lub jest uszkodzony
2090Błąd komunikacji z copywriterami (prosimy zgłosić)
2099Duplikacja treści

Zmiany w API

Lista zmian API oraz dokumentacji.

Wersja / data Opis
v1.7
5 listopada 2018
  • Dodany moduł: file [upload]
  • Nowe kody błędów: 2071 .. 2076
v1.6
22 sierpnia 2018
  • article - nowa akcja: categoryadd
  • article / list - nowa kolumna: categoryid
  • domain - nowa akcja: commit
v1.5
9 października 2017
  • Dodany moduł: text [order, list, update]
  • Nowe kody błędów: 2002, 2003, 2090
  • Uzupełnione informacje o typach parametrów
v1.4
22 lutego 2017
  • campaign - nowa akcja: pdf
  • position - nowa akcja: pdf
v1.3
12 września 2016
  • article / list - nowy parametr: content, nowe kolumny: text, url, files
  • domain / list - nowa kolumna: active
v1.2
20 czerwca 2016
  • position / list - poprawki zgodności wstecznej po zmianach modułu
  • Dodany moduł: campaign [list, screenshot, position]
v1.1
18 kwietnia 2016
  • article / categories - nowe kolumny: id, title, url
  • article / list - nowa kolumna: name
  • domain / list - nowa kolumna: id
  • article - nowe akcje: add, edit
  • Kody błędów 1005, 1006, zwracają nazwę parametru w message.
  • Nowe kody błędów: 2001, 2099
v1.0
5 sierpnia 2014
Wprowadzenie API.
  • Dodane moduły:
    • domain [list, screenshot]
    • article [list, visits, categories]
    • stats [visits]
    • text [brak]
    • position [list]
    • profile [about, ping]
  • Przykładowe skrypty.
  • Kody błędów