API Helpjuice v3
Dokumentacija o korištenju Helpjuice.com API V3 (JSON API)
Pregled
Verzija 3 API-ja Helpjuice strukturirana je oko REST, HTTP i JSON. URL-ovi krajnjih točaka API-ja organizirani su oko resursa, poput korisnika ili članaka. Koristi HTTP metode za navođenje radnje na resursu i HTTP kodove statusa za izražavanje statua grešaka. Resursi su predstavljeni u JSON-u slijedeći konvencionalnu shemu.
Osnovni URL
API-ju se pristupa pomoću osnovnog URL-a koji je specifičan za vaš račun. U primjerima navedenim u ovoj dokumentaciji koristimo URL vašeime računa. helpjuice .com kao helpjuice za URL vašeg stvarnog API računa. Pored toga, URL staze trebaju započeti s api / v3 da bi se odredila verzija 3 API-ja. Generalno, URL će biti u obliku:
https: // <vaš račun>. helpjuice .com / api / v3 / <resurs>.
Autentifikacija
Svi zahtjevi za API su autentificirani davanjem vašeg API ključa. API ključ treba pružiti kao HTTP zaglavlje s imenom Autorizacija ili kao parametar upita api_key . ( Kako mogu dobiti svoj API ključ ).
Zaglavlja | Params |
---|---|
Autorizacija | api_key |
ffb722a62e8 ********************** | ffb722a62e8 ********************** |
Vaš API ključ možete pronaći na svom računu na stranici Postavke / API vjerodajnice za upute. Molimo posjetite Kako mogu dobiti svoj API ključ . Svaki račun ima svoj jedinstveni API ključ.
HTTP metode
API v3 koristi standardne HTTP metode za navođenje radnje na resursu.
Metoda | Akcija |
---|---|
GET | Dohvatite resurs |
POŠTA | Stvorite novi resurs |
STAVITI | Ažurirajte resurs |
IZBRIŠI | Uklonite resurs |
Shema
Svi API zahtjevi i tijela odgovora pridržavaju se zajedničkog JSON formata koji predstavlja pojedinačne stavke i kolekcije stavki .
Pojedinačni resursi
Pojedinačne resurse predstavlja član najvišeg nivoa nazvan prema resursu u obliku jednine. Ispod je prikaz jednog kontakta. Ovo bi se moglo koristiti u tijelu zahtjeva za PUT i to je ono što bi se vratilo u tijelu zahtjeva za GET.
{ "korisnik": { "email": "jsmith@example.com", "name": "John Smith", "first_name": "John", "last_name": "Smith", "role_id": "superadmin", "created_at": "2020-07-08T13: 50: 20.949Z", "updated_at": "2020-07-08T13: 50: 20.949Z" } }
Kolekcije
Zbirke resursa predstavlja član najvišeg nivoa nazvan prema resursu u množini. Ispod je prikaz kolekcije kontakata.
{ "korisnici": [ { "email": "jsmith@example.com", "name": "John Smith", "first_name": "John", "last_name": "Smith", "role_id": "superadmin", "created_at": "2020-07-08T13: 50: 20.949Z", "updated_at": "2020-07-08T13: 50: 20.949Z" }, { "email": "jdoe@example.com", "name": "John Doe", "first_name": "John", "last_name": "Srna", "role_id": "admin", "created_at": "2020-07-08T13: 50: 20.949Z", "updated_at": "2020-07-08T13: 50: 20.949Z" } ] }
Paginacija
Krajnje točke koje vraćaju zbirke resursa moraju ograničiti broj zapisa vraćenih u danom odgovoru. Tipična krajnja točka zadano će vratiti 25 zapisa, ograničenje parametra upita može se koristiti za promjenu broja vraćenih zapisa.
{
"meta": {
"trenutno": 1,
"limit": 15,
"total_pages": 4,
"ukupan_broj": 50
}
}
Parametar | Opis |
---|---|
Limit | Broj rezultata za prikaz na svakoj stranici (zadano = 25, maks. = 1000). |
Page | Trenutna stranica sa podacima. |
Greške
API koristi HTTP statusne kodove da naznači da je došlo do greške prilikom obrade zahtjeva. Postoje četiri glavne šifre statusa greške koje koristi API:
Kod | Opis |
---|---|
403 | U slučaju da API ključ nije osiguran. |
404 | U slučaju da traženi podaci ne postoje. |
422 | Zahtjev se nije mogao obraditi, obično zbog nedostajućeg ili nevaljanog parametra. |
U slučaju 422 pogreške, odgovor će također sadržavati objekt pogreške s objašnjenjem polja koja nedostaju ili su nevaljana. Evo primjera:
HTTP / 1.1 422 Neobradivi entitet { "greške": [ { "email": "nije valjan." } ] }
Pretraži
Pretražite bazu znanja
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / search? query = < helpjuice upit>
ODGOVOR sirov
{ "pretraživanja": [ { "id": 1, "name": "Članak Helpjuice", "puž": "111- helpjuice sok-članak", "tag_names": [], "answer_sample": "Kratki odgovor u nekoliko riječi", "long_answer_sample": "Duži odgovor, ali ne i cijeli članak", "kategorije": { "trenutno": { "id": 23, "name": "Korištenje Helpjuice", "url": "URL u vašu kategoriju" } }, "last_published_date": "30. srpnja 2020", "last_published_user_name": "John Doe", "is_published": tačno, "is_internal": netačno, "url": "URL vašeg članka" } ] }
Korisnici
Kreirajte novog korisnika
URL
POST https: // <vaš račun>. helpjuice .com / api / v3 / korisnici
TIJELO sirovo
{ "korisnik": { "first_name": "John", "last_name": "Srna", "email": "jhon@doe.com", "role_id": "admin", "group_ids": [1, 2] } }
Polje | Tip | Opis |
---|---|---|
first_name * | String | Ime korisnika. |
prezime | String | Prezime korisnika. |
email * | String | Jedinstvena e-adresa korisnika. |
role_id * | String | Uloga korisnika (superadmin, admin, saradnik, nacrt_pisaca, pregledač) |
group_ids | Array | ID-ovi grupa u kojima se korisnik treba pridružiti. |
Ažurirajte korisnika
URL
STAVITE https: // <vaš račun>. helpjuice .com / api / v3 / users /: id
TIJELO sirovo
{ "korisnik": { "first_name": "John" } }
Polje | Tip | Opis |
---|---|---|
ime | String | Ime korisnika. |
prezime | String | Prezime korisnika. |
String | Jedinstvena e-adresa korisnika. | |
role_id | String | Uloga korisnika (superadmin, admin, saradnik, nacrt_pisaca, pregledač) |
group_ids | Array | ID-ovi grupa u kojima se korisnik treba pridružiti. |
Dohvatite korisnika
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / users /: id
TIJELO sirovo
{ "korisnik": { "first_name": "John", "last_name": "Srna", "email": "john@doe.com", "role_id": "admin" } }
Preuzimanje svih korisnika
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / korisnici
TIJELO sirovo
{ "korisnici": [ { "email": "jsmith@example.com", "firstName": "John", "lastName": "Smith" }, { "email": "alice@example.com", "firstName": "Alice", "lastName": "Jones" } ] }
Izbrišite korisnika
URL
OBRIŠI https: // <vaš račun>. helpjuice .com / api / v3 / users /: id
Grupe
Kreirajte novu grupu
URL
POST https: // <vaš račun>. helpjuice .com / api / v3 / grupe
TIJELO sirovo
{ "grupa": { "name": "Nova grupa", "smart_load": tačno, "user_ids": [1, 2], "auto_groups": "@ gmail.com, @ email.com", } }
Polje | Tip | Opis |
---|---|---|
ime * | String | Ime grupe. |
smart_load | Boolean | Omogućite korisnike pametnog učitavanja u ovoj grupi. |
user_ids | Array | Pridružite korisnike ovoj grupi. |
auto_groups | String | Niz ekstenzija e-pošte odvojen zarezom koji će se automatski učitati u ovu grupu. smart_load mora biti omogućen. |
Ažurirajte grupu
URL
STAVITE https: // <vaš račun>. helpjuice .com / api / v3 / groups /: id
TIJELO sirovo
{ "grupa": { "smart_load": tačno, "auto_groups": "@ email.com" } }
Polje | Tip | Opis |
---|---|---|
ime | String | Ime grupe. |
smart_load | Boolean | Omogućite korisnike pametnog učitavanja u ovoj grupi. |
user_ids | Array | Pridružite korisnike ovoj grupi. |
auto_groups | String | Niz ekstenzija e-pošte odvojen zarezom koji će se automatski učitati u ovu grupu. smart_load mora biti omogućen. |
Dohvatite grupu
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / groups /: id
TIJELO sirovo
{ "grupa": { "id": 1, "name": "nova grupa", "smart_load": tačno, "created_at": "2020-07-29T09: 37: 03.529Z", "auto_groups": [ { "izraz": "@ gmail.com" }, { "expression": "@ email.com" } ], "korisnici": [ { "id": 1, "name": "John Doe", "role_id": "superadmin", }, { "id": 2, "name": "John Best", "role_id": "admin", } ] } }
Dohvati sve grupe
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / grupe
TIJELO sirovo
{ "grupe": [ { "id": 2, "name": "druga grupa", "smart_load": netačno, "created_at": "2020-07-29T09: 37: 03.529Z", "auto_groups": [], "korisnici": [ { "id": 1, "name": "Jhon Doe", "role_id": "superadmin", }, { "id": 2, "name": "Jhon Best", "role_id": "admin", } ] }, { "id": 3, "name": "nova grupa", "smart_load": netačno, "created_at": "2020-07-29T09: 37: 03.529Z", "auto_groups": [ { "expression": "@ gamil.com" } ], "korisnici": [ { "id": 1, "name": "Jhon Doe", "role_id": "superadmin", }, { "id": 2, "name": "Jhon Best", "role_id": "admin", } ] } ] }
Izbrišite grupu
URL
OBRIŠI https: // <vaš račun>. helpjuice .com / api / v3 / groups /: id
TIJELO sirovo
{ "grupa": { "delete_users": netačno } }
Polje | Tip | Opis |
---|---|---|
delete_users | Boolean | Izbrišite korisnike koji su unutar ove grupe. |
Kategorije
Kreirajte novu kategoriju
URL
POST https: // <vaš račun>. helpjuice .com / api / v3 / kategorije
TIJELO sirovo
{ "kategorija": { "parent_id": 1, "pristupačnost": 1, "description": "Moja kategorija Helpjuice", "name": "Kategorija", "codename": "kategorija", "arhivirano": false, "user_ids": [1,2], "group_ids": [1] } }
Polje | Tip | Opis |
---|---|---|
parent_id | Ceo broj | ID nadređene kategorije. |
pristupačnost | Ceo broj | (javno: 0, interno: 1, privatno: 2) ograničio je pristup člancima iznutra. |
opis | String | Opis kategorije. |
ime * | String | Naziv kategorije. |
kodno ime | String | Puž za kategoriju. |
arhivirano | Boolean | Bez obzira da li je kategorija arhivirana ili ne. |
user_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi će korisnici imati pristup njoj. |
group_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi članovi grupe imat će pristup. |
Ažurirajte kategoriju
URL
STAVITE https: // <vaš račun>. helpjuice .com / api / v3 / categories /: id
TIJELO sirovo
{ "kategorija": { "name": "Nova kategorija" } }
Polje | Tip | Opis |
---|---|---|
parent_id | Ceo broj | ID nadređene kategorije. |
pristupačnost | Ceo broj | (javno: 0, interno: 1, privatno: 2) ograničio je pristup člancima iznutra. |
opis | String | Opis kategorije. |
ime | String | Naziv kategorije. |
kodno ime | String | Puž za kategoriju. |
arhivirano | Boolean | Bez obzira da li je kategorija arhivirana ili ne. |
user_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi će korisnici imati pristup njoj. |
group_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi članovi grupe imat će pristup. |
Dohvatite kategoriju
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / categories /: id
TIJELO sirovo
{ "kategorija": { "id": 1, "name": "Naziv kategorije", "kodno ime": "111-kategorija", "pristupačnost": 0, "description": "Opis", "published_questions": [ { "id": 22, "name": "Objavljeni članak", "url": "URL vašeg članka" } ], "draft_questions": [ { "id": 23, "name": "Nacrt članka", "url": "URL vašeg članka" } ], "url": "URL u vašu kategoriju" } }
Dohvaćanje svih kategorija
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / kategorije
TIJELO sirovo
{ "kategorije": [ { "id": 5, "name": "Kategorija", "codename": "22-kategorija", "pristupačnost": 0, "description": "Opis", "published_questions": [ { "id": 22, "name": "Objavljeni članak", "url": "URL vašeg članka" } ], "draft_questions": [ { "id": 23, "name": "Nacrt članka", "url": "URL vašeg članka" } ], "url": "URL u vašu kategoriju" }, { "id": 55, "name": "Kategorija", "codename": "55-kategorija", "pristupačnost": 0, "description": "Opis", "published_questions": [ { "id": 22, "name": "Objavljeni članak", "url": "URL vašeg članka" } ], "draft_questions": [ { "id": 23, "name": "Nacrt članka", "url": "URL vašeg članka" } ], "url": "URL u vašu kategoriju" } ] }
Izbrišite kategoriju
URL
OBRIŠI https: // <vaš račun>. helpjuice .com / api / v3 / categories /: id
Članci
Napravite članak
Da bismo kreirali novi članak, potrebno je poslati samo ID nadređene kategorije, a mi ćemo stvoriti novi nacrt članka za vas.
URL
POST https: // <vaš račun>. helpjuice .com / api / v3 / articles
TIJELO sirovo
{ "članak": { "name": "novi članak", "description": "Ovo je novi članak", "codename": "novi članak", "visibility_id": 0, "body": "<p> ovo je članak članka </p>", "objavljeno": istina, "id_kategorije": [1,2], "user_ids": [1,2,6], "group_ids": [1], "contributor_user_ids": [1,2], } }
Polje | Tip | Opis |
---|---|---|
ime * | String | Naziv članka. |
opis | String | Opis članka. |
kodno ime | String | puž ili URL članka. |
vidljivost_id | Ceo broj | (javno: 0, interno: 1, privatno: 2) ograničeni pristup članku. |
tijelo | String | Tekst članka. |
objavljeno | Boolean | Da li je članak objavljen ili ne. |
id_kategorije | Array | Kategorije u kojima će se članak pojaviti. |
user_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi će korisnici imati pristup njoj. |
group_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi članovi grupe imat će pristup. |
contributor_user_ids | Array | Članovi koji doprinose članku |
Ažurirajte članak
URL
STAVITE https: // <vaš račun>. helpjuice .com / api / v3 / articles /: id
TIJELO sirovo
{ "članak": { "name": "novi članak", "codename": "novi članak" } }
Polje | Tip | Opis |
---|---|---|
ime | String | Naziv članka. |
opis | String | Opis članka. |
kodno ime | String | puž ili URL članka. |
vidljivost_id | Ceo broj | (javno: 0, interno: 1, privatno: 2) ograničeni pristup članku. |
tijelo | String | Tekst članka. |
objavljeno | Boolean | Da li je članak objavljen ili ne. |
id_kategorije | Array | Kategorije u kojima će se članak pojaviti. |
user_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi će korisnici imati pristup njoj. |
group_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi članovi grupe imat će pristup. |
contributor_user_ids | Array | Članovi koji doprinose članku |
Dohvatite članak
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / articles /: id
TIJELO sirovo
{ "članak": { "id": 1, "name": "Novi članak", "prikazi": 112, "pristupačnost": 0, "description": "moj novi članak", "codename": "novi članak", "created_at": "2020-07-29T09: 37: 03.529Z", "updated_at": "2020-07-29T09: 37: 03.529Z", "objavljeno": netačno, "odgovor": [ { "body": "<p> Novi članak </p>", "body_txt": "Novi članak", "format": "html", "updated_at": "2020-07-29T09: 37: 03.529Z" } ], "url": "URL vašeg članka" } }
Dohvatite sve članke
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / articles
TIJELO sirovo
{ "članci": [ { "id": 1, "name": "Novi članak", "prikazi": 112, "pristupačnost": 0, "description": "moj novi članak", "codename": "novi članak", "created_at": "2020-07-29T09: 37: 03.529Z", "updated_at": "2020-07-29T09: 37: 03.529Z", "objavljeno": netačno, "odgovor": [ { "body": "<p> Novi članak </p>", "body_txt": "Novi članak", "format": "html", "updated_at": "2020-07-29T09: 37: 03.529Z" } ], "url": "URL vašeg članka" }, { "id": 2, "name": "Drugi članak", "prikazi": 12, "pristupačnost": 0, "description": "moj drugi članak", "codename": "drugi članak", "created_at": "2020-07-29T09: 37: 03.529Z", "updated_at": "2020-07-29T09: 37: 03.529Z", "objavljeno": istina, "odgovor": [ { "body": "<p> Moj drugi članak </p>", "body_txt": "Moj drugi članak", "format": "html", "updated_at": "2020-07-29T09: 37: 03.529Z" } ], "url": "URL vašeg članka" } ] }
Izbrišite članak
URL
OBRIŠI https: // <vaš račun>. helpjuice .com / api / v3 / articles /: id
Aktivnosti
Dohvatite aktivnost
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / activities /: id
ODGOVOR sirov
{ "aktivnost": { "id": 1, "trackable_id": 22, "trackable_type": "Pitanje", "owner_id": 1, "action": "kreiraj", "created_at": "2020-07-29T09: 37: 03.529Z" } }
Dohvatite sve aktivnosti
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / aktivnosti
ODGOVOR sirov
{ "članci": [ { "id": 1, "trackable_id": 22, "trackable_type": "Pitanje", "owner_id": 1, "action": "kreiraj", "created_at": "2020-07-29T09: 37: 03.529Z" }, { "id": 2, "trackable_id": 22, "trackable_type": "Pitanje", "owner_id": 1, "action": "kreiraj", "created_at": "2020-07-29T09: 37: 03.529Z" } ] }
Postavke
Dohvatite postavke računa
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / settings / account
ODGOVOR sirov
{ "račun": { "name": "Vaš račun", "poddomena": "vaš_račun", "internal_kb": netačno, "expire_password_after_days": null, "contact_us_email": "support.youraccount.com", "contact_us_subject": "[Podrška] {{question.name}}", "contact_us_single_sender": netačno, "only_internal_article_requests": false, "created_at": "2020-07-29T09: 37: 03.529Z" } }
Ažurirajte postavke računa
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / postavke
ODGOVOR sirov
{ "postavke": { "name": "Vaš račun", "poddomena": "vaš_račun", "internal_kb": netačno, "expire_password_after_days": null, "contact_us_email": "support.youraccount.com", "contact_us_subject": "[Podrška] {{question.name}}", "contact_us_single_sender": netačno, "only_internal_article_requests": false, "created_at": "2020-07-29T09: 37: 03.529Z" } }
Polje | Tip | Opis |
---|---|---|
ime | String | Ime vašeg računa. |
top_questions_count | Ceo broj | Broj članaka koji će biti prikazan u vašoj kb. |
internal_kb | Boolean | Kb koristite samo interno. |
expire_password_after_days | Ceo broj | Istek lozinke za nove korisnike, broj dana. |
contact_us_email | String | Adresa e-pošte za podršku. |
contact_us_subject | String | Obratite nam se e-mailom, naslov. |
contact_us_single_sender | Boolean | Pošaljite sve e-poruke s kontaktima u polje contact_us_email. |
only_internal_article_requests | Boolean | Samo prijavljeni korisnici mogu slati zahtjeve za članke. |