sugester / api

API do Sugestera

Sugester API

Opis jak zintegrować własną aplikację lub serwis z systemem http://sugester.pl/

Dzięki API można z innych systemów dodawać posty/sugestie/błędy itp

Po zalogowaniu się do Sugester w menu Ustawienie > API znajdują się przykłady działające na danym koncie. Są one też dostępne na stronie http://api.sugester.pl/app/account/api

Spis treści

• API Token
• Przykłady wywołania
  • Dodanie klienta
  • Pobieranie danych wszystkich klientów
  • Pobieranie danych klienta
  • Aktualizacja danych klienta
  • Skasowanie klienta
  • Dodanie zadania
  • Pobieranie danych wszystkich zadań(z helpdesku)
  • Pobieranie danych zadania
    • Dodanie komentarza do zadania
  • Dodanie dealu
  • Aktualizacja dealu
  • Pobieranie danych wszystkich deali
  • Pobieranie danych dealu
  • Usunięcie dealu
  • Dodanie kontaktu
  • Pobieranie danych kontaktu
  • Aktualizacja danych kontaktu
  • Dodanie nowej listy odbiorców
  • Pobranie danych listy odbiorców
  • Aktualizacja danych listy odbiorców
  • Dodanie nowej sugestii
  • Dodanie konta partnerskiego
  • Integracje
    • Dodanie nowego klienta
    • Dodanie nowego dealu
• Klient - specyfikacja
• Post - specyfikacja

API token

Kod autoryzacyjny API (API_TOKEN) należy pobrać z ustawień aplikacji w menu: Ustawienia > API > Kod autoryzacyjny API. Dzięku niemu w wywołaniach API nie trzeba będzie podawać swojego loginu/hasła.

Przykłady wywołania

Dodanie nowego klienta:

curl http://YOUR-PREFIX.sugester.pl/app/clients.json\
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"client": {
    "name":"client 1 from API",
    "email": "[email protected]",
    "note": "note 1"
  }
}'

Pobranie danych wszystkich klientów:

curl http://YOUR-PREFIX.sugester.pl/app/clients.json?api_token=YOUR_API_TOKEN

Pobranie danych jednego klienta:

curl http://YOUR-PREFIX.sugester.pl/app/clients/1234.json?api_token=YOUR_API_TOKEN

Aktualizacja danych klienta:

curl http://YOUR-PREFIX.sugester.pl/app/clients/1234.json\
     -X PUT \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"client": {
    "note": "note from API"
  }
}'

Usunięcie klienta:

curl -X DELETE  http://YOUR-PREFIX.sugester.pl/app/clients/12345.json?api_token=YOUR_API_TOKEN

Dodanie nowego zadania:

curl http://YOUR-PREFIX.sugester.pl/app/posts.json \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"post": {
    "title":"task title 1 from API",
    "content": "task content 1",
    "task_kind": "task",
    "client_id": null,
    "responsible_id": 1234
  }
}'

Pobieranie danych wszystkich zadań(z helpdesku):

curl http://YOUR-PREFIX.sugester.pl/app.json?api_token=YOUR_API_TOKEN

Pobieranie danych jednego zadania:

curl http://YOUR-PREFIX.sugester.pl/app/posts/1234.json?api_token=YOUR_API_TOKEN

Dodanie komentarza do zadania o id post_id:

curl http://YOUR-PREFIX.sugester.pl/app/posts.json \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"post": {
    "post_id": 123,
    "title":"comment for task 123",
    "content": "comment content 1",
    "task_kind": "comment",
    "client_id": null,
    "responsible_id": 1234
  }
}'

Dodanie nowego dealu:

curl http://YOUR-PREFIX.sugester.pl/app/deals.json\
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"deal": {
    "name":"deal 1 from API",
    "description": "desc 1",
    "client_id": null
  }
}'

Aktualizacja dealu:

curl http://YOUR_PREFIX.sugester.pl/app/deals/1234.json\
    -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '
{
"api_token": "YOUR_API_TOKEN",
"deal": {
   "description": "new description from API"
 }
}'

Pobieranie danych wszystkich deali:

curl http://YOUR-PREFIX.sugester.pl/app/deals.json?api_token=YOUR_API_TOKEN

Pobieranie danych dealu:

curl http://YOUR-PREFIX.sugester.pl/app/deals/1234.json?api_token=YOUR_API_TOKEN

Usunięcie dealu:

curl -X DELETE  http://YOUR-PREFIX.sugester.pl/app/deals/12345.json?api_token=YOUR_API_TOKEN

Dodanie kontaktu:

curl http://YOUR_PREFIX.sugester.pl/app/contacts.json\
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '
{
"api_token": "YOUR_API_TOKEN",
"contact": {
   "name":"contact 1 from API",
   "description": "new contact from API",
   "first_name": "John",
   "last_name": "Doe",
   "responsible_id": 1,
   "email": "[email protected]",
   "phone": "123456789"
 }
}'

Pobieranie danych kontaktu:

curl http://YOUR-PREFIX.sugester.pl/app/contacts/1234.json?api_token=YOUR_API_TOKEN

Aktualizacja danych kontaktu:

curl http://YOUR_PREFIX.sugester.pl/app/contacts/1234.json\
    -X PUT \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '
{
"api_token": "YOUR_API_TOKEN",
"contact": {
   "description": "new description from API"
 }
}'

Dodanie listy odbiorców:

curl https://YOUR_PREFIX.sugester.pl/app/contact_lists.json \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_KEY",
"contact_list": {
    "name": "New contact list"
  }
}'

Pobieranie danych listy odbiorców:

curl https://YOUR_PREFIX.sugester.pl/app/contact_lists/10.json?api_token=YOUR_API_TOKEN

Aktualizacja danych listy odbiorców:

curl https://YOUR_PREFIX.sugester.pl/app/contact_lists/10.json \
     -X PUT \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"contact_list": {
    "name": "New contact list updated"
  }
}'

Dodanie posta o typie "błąd":

curl http://your-prefix.sugester.pl/app/posts.json \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "API_TOKEN",
"post": {
    "title":"post title2",
    "content": "post content 2",
    "kind": "error"
  }
}'

Dodanie nowego konta:

curl http://YOUR-PREFIX.sugester.pl/app/account.json \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"account": {
    "prefix":"sugester2",
    "initial_module": "crm",
    "from_partner": "partner1"
 },
"user": {
    "login": "login1",
    "email": "[email protected]",
    "password": "password1"
 }
}'

Integracje

Dodanie nowego klienta

curl https://YOUR_PREFIX.sugester.pl/app/clients.json \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"client": {
    "name": "client 2 from External APP via API",
    "email": "[email protected]",
    "note": "note ext 2",
    "external_ids": {
        "myapp_client_id": "17"
    }
  }
}'

Dodanie nowego dealu

curl https://YOUR_PREFIX.sugester.pl/app/deals.json \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '
{
"api_token": "YOUR_API_TOKEN",
"deal": {
    "name": "deal 2 from External APP via API",
    "description": "desc 2",
    "price": 117,
    "client": {
        "name": "client 2 from External APP via API",
        "email": "[email protected]",
        "external_ids": {
            "myapp_client_id": "17"
        }
    },
    "external_ids": {
        "myapp_invoice_id": "21"
    }
  }
}'

Specyfikacja pól Klienta

{
	"id": id klienta
	"name": nazwa klienta
	"tax_no": numer nip
	"post_code": kod pocztowy
	"city": miejscowosc
	"street": ulica
	"first_name": imię
	"country": kraj
	"email": e-mail
	"phone": telefon
	"www": strona www
	"fax": fax
	"created_at": utworzenie
	"updated_at": aktualizcja
	"street_no": ulica
	"kind": rodza ('buyer/seller')
	"bank": nazwa banku
	"bank_account": konto bankowe
	"bank_account_id":
	"shortcut": skrót nazwy klienta
	"note": notatka
	"last_name": nazwisko
	"discount": zniżka
	"payment_to_kind": domyślny cza płatności faktury
	"use_delivery_address": adres korespondencyjny aktywny
	"delivery_address":  adres korespondencyjny
	"mobile_phone": telefon komórkowy
	"company": czy firma
	"register_number": numer regon
	"description": opis
	"project_id": id projektu
	"contact_id": id kontaktu głównego
	"appendixes_count": ilość załączników
	"posts_count": ilość emaili/zadań
	"contacts_count": ilość kontaktów
	"last_activity": ostatnia aktywność
	"string1..10": pola dodatkowe
	"integer1..10": pola dodatkowe
	"decimal1..10": pola dodatkowe
	"checkbox1..10": pola dodatkowe
	"date1..10": pola dodatkowe
	"text1..10": pola dodatkowe
	"datetime1..10": pola dodatkowe
	"avatar_file_name": avatar
	"avatar_content_type"
	"avatar_file_size"
	"avatar_updated_at"
	"status_id": id statusu
	"category_id": id kategorii
	"department_id": id departamentu
	"position": pozycja
	"creator_id": id osoby ktora dodala
	"updater_id": id osoby ktora ostatnio aktualizowala
	"responsible_id": id osoby odpowiedzialnej
	"province": wojewodztwo
	"sensitive_data": czy dane ukryte
	"external_id": ID klienta
	"token": token klienta
	"paid_from": od kiedy płatny
	"paid_to": do kiedy płatny
	"paid_total": suma płatności od klienta
}

Specyfikacja pól obiektu Post (Zadania/Sugestia/Zgłoszenie/E-mail)

{
    "id": id posta
    "title": tytuł
    "content": treść
    "kind": rodzaj sugestii ('suggestion', 'error', 'question', 'praise', 'private'),
    "user_id": id usera
    "points": liczba punktów
    "nick": nick usera
    "votes_cache": ilość oddanych głosów
    "comments_cache": ilość oddanych komentarzy
    "forum_id": id forum
    "category_id": id category
    "created_at": czas utworzenia
    "updated_at": czas ostatniej modyfikacji
    "ip": ip z którego oddano post
    "agent": info o przeglądarce
    "response": odpowiedź główna
    "response_user_id": id osoby która odpowiedziała
    "referrer": refferer
    "responsible_id": id przypisanej osoby
    "last_action_status": status ("created"),
    "email": email nadawcy
    "uid": token użytkownika,
    "spam_kind": rodzaj spamu,
    "answer": odpowiedz,
    "answered": czy jest odpowiedz,
    "duplicate_from_id": id duplikatu,
    "abstract": abstrakt,
    "status_id": id status,
    "view_count": ilość wyświetleń,
    "tags": tagi,
    "facebook_likes": ilość like facebokoowych,
    "min_votes_to_start": ilość głosów do rozpoczęcia prac,
    "use_html": czy html,
    "email_to": adres email do,
    "email_cc": adres email cc,
    "email_bcc": adres email bcc,
    "spam_score": scoring spamowy,
    "spam_report": info o spamie,
    "closed": czy zamkniete (true/false),
    "scheduled_at": przypisana data wykonania,
    "task_kind": rodzaj zadania ('feedback', 'email', 'task', 'help', 'chat', 'phone', 'lead', 'error', 'idea'),
    "priority": priorytet,
    "title_note": null,
    "user_spam_report": zgłoszenie spamu,
    "client_id": id klienta,
    "project_id": id projektu,
    "help_link": klucz linka pomocy,
    "help_content": treść pomocy,
    "post_id": id postu nadrzędnego,
    "www": strona www dodajacego post,
    "private": czy prywatny (true/false),
    "unread": czy nie przeczytany (true/false),
    "email_recipient": do kogo jest dany post (uzywane w helpdesk/mail),
    "email_reply_to": reply to  (uzywane w helpdesk/mail)
}

api's Issues

XML / Posty, Kategorie

Dzień dobry,

W waszym API na stronie http://sugester.pl/api znalazłem możliwość wyświetlania XML'i z postami etc.

Problem, że działa tylko to: GET http://NAZWA_FORUM.sugester.pl/app/posts/POST_ID.xml

Stąd pytania:

Jak wyświelić listę wszystkich kategorii w XML?
Jak wyświetlić listę wszystkich Id postów w XML?
Jak znaleźć link do załącznika, który dodałem do posta?

Dziękuje i pozdrawiam.

weird redirection from api to the app url

endpoint https://puzzlet.sugester.com/app/posts.json?page=1&order=id+desc
redirect to https://puzzlet.sugester.com/app.json

endpoints users and statuses dont support get by id

https://puzzlet.sugester.com/app/statuses/39960.json?api_token=
https://puzzlet.sugester.com/app/contacts/620167.json?api_token=
endpoints users and statuses returns html code with 404.
I thing it should be implemented geting by id aswell.

endpoint contacts by id returns 500 in header

https://puzzlet.sugester.com/app/contacts/620167.json?api_token={api_token}
returns in header errror 500 but in body is regular answer.
viz http://prntscr.com/ef1m5e

endpoint activities by id returns 500

https://puzzlet.sugester.com/app/activities/10252314.json?api_token={api_token}
returns 500 error in response
{
"status": "500",
"error": "Internal Server Error"
}