FusionSystem Dokumentacja API

wersja API: v1.4 - stan na dzień 22 luty 2017

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. Jeśli gdzieś występuje limit długości parametru, 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.

Domeny IDN można w zapytaniach podawać w dowolnej formie, jedynie należy pamiętać o odpowiednim kodowaniu. W odpowiedzi jest zwracana nazwa ze 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.

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

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.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

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)

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.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 zewnętrznego działu copywritingu.

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.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

/**
 *  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() ){
		# łą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
		$params = http_build_query( $params );

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

		$url = 'https://panel.fusionsystem.pl/apiv1';
		
		# wysyłka z użyciem GET
		if(!$use_post)
			$url .= '?' . $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 );

		# 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,	$params );
		}

		$response = curl_exec( $curl );

		curl_close( $curl );

		$response = json_decode( $response, true );

		# brak odpowiedzi / nieprawidłowy JSON
		if( !isset( $response['status'] ) )
			die( 'Brak odpowiedzi.' );

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

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

Pobieranie listy domen wraz z zrzutami ekranów

Przykład 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>
	";
}

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
2099Duplikacja treści

Zmiany w API

Lista zmian API oraz dokumentacji.

Wersja / data Opis
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