API

Serwis TextBookers udostępnia RESTowe API umożliwiające dostęp do niektórych funkcjonalności serwisu. Autoryzacja dokonywana jest za pomocą standardu OAuth. Wszelkie zapytania należy wykonywać poprzez HTTPS. Bez użycia tego protokołu login, hasło, ID klienta oraz tajny klucz będą publicznie dostępne.

Logowanie

Aby mieć możliwość zalogowania do API, należy zarejestrować aplikację korzystającą API, podając jej adres URI. Możesz zarejestrować wiele aplikacji.

  1. Przejdź do ustawień.
  2. Przejdź do API.
  3. Wybierz 'dodaj aplikację'.
  4. Podaj adres swojej aplikacji (np. http://mojserwis.pl).

Po pomyślnej rejestracji zostanie wyświetlone ID klienta i tajny klucz, które posłużą do logowania.

Przed rozpoczęciem korzystania z API musisz się do niego zalogować. Służy do tego wywołanie:

GET https://www.textbookers.com/oauth/v2/token?client_id=ID_KLIENTA&client_secret=TAJNY_KLUCZ&grant_type=password&username=TWOJ_EMAIL&password=TWOJE_HASLO

ID_KLIENTA i TAJNY_KLUCZ znajdziesz w szczegółach zarejestrowanej aplikacji. TWOJ_EMAIL i TWOJE_HASLO to login i hasło do Twojego konta w serwisie TextBookers.

Odpowiedź

{
    "access_token": "TOKEN",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "refresh token"
}

Do każdego z wywołań poniżej należy dodać parametr access_token o wartości otrzymanej w odpowiedzi, np.:

GET https://www.textbookers.com/api/user?access_token=TOKEN

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$r = $client->get('oauth/v2/token', [
    'query' => [
        'client_id'     => 'ID_KLIENTA',
        'client_secret' => 'TAJNY_KLUCZ',
        'grant_type'    => 'password',
        'username'      => 'TWOJ_EMAIL',
        'password'      => 'TWOJE_HASLO'
    ]
]);

$loginData = $r->json();

Wywołania

Wywołania mogą składać się z filtrów, placeholderów i danych zapytania. Wszelkie filtry dodawane są do zapytania (np. ?order=123), parametry są umieszczane w miejscach placeholderów (np. {id}), natomiast dane zapytania przekazywane są w formacie JSON w ciele (body) zapytania.

Pobierz listę tekstów

GET /api/articles

Domyślnie pobierane są zatwierdzone teksty. Listę tekstów można filtrować za pomocą filtrów, które można dodać do parametrów zapytania.

Filtry

Nazwa Format/Wartość Opis
id \d+ ID tekstu.
order \d+ ID zlecenia.
project \d+ ID projektu.
creationStatus to-accept Status tekstu.

Odpowiedź

Tablica obiektów:

Nazwa Typ Opis
id integer ID tekstu.
order model Zlecenie, w ramach którego został napisany tekst.
title string Tytuł tekstu.
content string Treść tekstu.
rate integer Ocena wystawiona przez klienta.
rateDesc string Uzasadnienie oceny klienta.
correctionReason string Co jest wg zleceniodawcy do poprawienia w tekście
complaintReason string Uzasadnienie reklamacji.
utilized boolean Czy tekst został wykorzystany przez klienta.
autoAccepted boolean Czy tekst został zatwierdzony automatycznie przez system.
project model Projekt, do którego należy tekst.

Przykład

<?php

/**
 * Pobranie tekstów do akceptacji z wybranego zlecenia
 */

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';
$orderId = 'należy pobrać ID zlecenia';

$r = $client->get('api/articles', [
    'query' => [
        'order'             => $orderId,
        'creationStatus'    => 'to-accept',
        'access_token'      => $token
    ]
]);

$articles = $r->json();

Zmień dane tekstu

PATCH /api/articles/{id}

Możliwe jest zmienienie statusu tekstu na zatwierdzony (accepted) lub odrzucony (rejected). Zmiana jest możliwa tylko w przypadku tekstów, które są gotowe do zatwierdzenia. Zmiana statusu już zatwierdzonego tekstu spowoduje błąd. Można też oznaczyć tekst jako wykorzystany lub jako niewykorzystany.

Parametry

Nazwa Typ Opis
id int ID zlecenia

Dane zapytania

Nazwa Typ/Wartość Wymagany Opis
creationStatus accepted|rejected nie Status tekstu.
utilized utilized|not-utilized nie Czy tekst został wykorzystany.

Odpowiedź

Obiekt:

Nazwa Typ Opis
id integer ID tekstu.
order model Zlecenie, w ramach którego został napisany tekst.
title string Tytuł tekstu.
content string Treść tekstu.
rate integer Ocena wystawiona przez klienta.
rateDesc string Uzasadnienie oceny klienta.
correctionReason string Co jest wg zleceniodawcy do poprawienia w tekście
complaintReason string Uzasadnienie reklamacji.
utilized boolean Czy tekst został wykorzystany przez klienta.
autoAccepted boolean Czy tekst został zatwierdzony automatycznie przez system.
project model Projekt, do którego należy tekst.

Przykład

<?php

/* Akceptowanie gotowych tekstów z podanego zlecenia */

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';
$articleId = 'należy pobrać ID tekstu';

$r = $client->patch('api/articles/' . $articleId, [
    'query' => ['access_token' => $token],
    'json'  => [
        'creationStatus'    => 'accepted'
    ]
]);

Pobierz listę copywriterów

GET /api/copywriters

Pobiera copywriterów, którzy wykonują zlecenia o podanych parametrach i nie są obciążeni dużą ilością zleceń.

Filtry

Nazwa Format/Wartość Opis
language [a-z]{2} Symbol języka (pl, en, de).
subject \d+ ID tematu zleceń.
articleType \d+ ID typu tekstów.

Odpowiedź

Tablica obiektów:

Nazwa Typ Opis
copywriterRate float Średnia ocena copywritera.
copywriterRates collection Tablica ocen copywritera wg typów tekstów w formacie [<język> => [<id typu> => <ocena>, <id typu> => <ocena>...]...].
copywriterName string Nazwa copywritera.
id integer ID użytkownika.

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';
$subjectId = 'należy pobrać ID tematu';
$articleTypeId = 'należy pobrać ID typu tekstu';

$r = $client->get('api/copywriters', [
    'query' => [
        'language'      => 'pl',
        'subject'       => $subjectId,
        'articleType'   => $articleTypeId,
        'access_token'  => $token
    ]
]);

$copywriters = $r->json();

Pobierz listę zleceń

GET /api/orders

Pobiera listę zleceń spełniających podane w filtrach kryteria.

Filtry

Nazwa Format/Wartość Opis
id \d+ ID zlecenia.
project \d+ ID projektu.
status (incomplete|\d+) Status zlecenia. Możliwe wartości: 0 - zlecenia w toku, 1 - w pełni zrealizowane, 2 - zrealizowane częściowo, 3 - niezrealizowane, incomplete - zl. posiadające status 2 lub 3.
offset \d+ Offset.
limit \d+ Limit.

Odpowiedź

Tablica obiektów:

Nazwa Typ Opis
id integer ID zlecenia.
createdAt datetime Data dodania zlecenia.
deadline datetime Termin realizacji zlecenia.
individual boolean Czy zlecenie będzie zrealizowane przez jednego copywritera.
author model Copywriter wybrany przez klienta.
minChars integer Minimalna liczba znaków w pojedynczym tekście.
keywords collection Słowa kluczowe, które muszą znaleźć się w tekstach.
totalCost float Koszt całego zlecenia w punktach.
language string Język tekstów.
articlesCount integer Liczba zamówionych tekstów.
acceptedCount integer Liczba zatwierdzonych tekstów.
toAcceptCount integer Liczba tekstów oczekujących na zatwierdzenie.
rejectedCount integer Liczba tekstów oczekujących na poprawę (odrzuconych przez klienta).
status integer Status zlecenia: 0 - w trakcie realizacji, 1 - wykonane, 2 - wykonane częściowo, 3 - niewykonane w ogóle
orderDescription string Opis zamówienia.
subject model Temat tekstów.
project model Projekt, do którego domyślnie trafią teksty.
articleType model Typ pisanych tekstów.

Przykład

<?php

/**
 * Pobranie zakończonych zleceń, w ramach których nie wszystkie teksty
 * zostały napisane
 */

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';

$r = $client->get('api/orders', [
    'query' => [
        'status'        => 'incomplete',
        'access_token'  => $token
    ]
]);

$orders = $r->json();

Dodaj nowe zlecenie

POST /api/orders

Dane zapytania

Nazwa Typ/Wartość Wymagany Opis
language string tak Język zlecenia (pl, en, de).
subject integer tak ID tematu zlecenia.
articleType integer tak ID typu pisanych tekstów.
keywords array tak Tablica ze słowami kluczowymi.
minChars integer tak Minimalna liczba znaków w pojedynczym tekście.
articlesCount integer tak Liczba zamówionych tekstów.
project integer tak ID projektu, do którego domyślnie trafią teksty.
orderDescription string nie Opis zlecenia.
author integer nie ID copywritera, który ma wykonać zlecenie. Copywritera można wybrać tylko wtedy, gdy podany w zleceniu typ tekstu posiada parametr individual=1.

Odpowiedź

Obiekt:

Nazwa Typ Opis
minChars integer Minimalna liczba znaków w pojedynczym tekście.
keywords collection Słowa kluczowe, które muszą znaleźć się w tekstach.
language string Język tekstów.
articlesCount integer Liczba zamówionych tekstów.
subject model Temat tekstów.
project model Projekt, do którego domyślnie trafią teksty.
articleType model Typ pisanych tekstów.
id integer ID zlecenia.
createdAt datetime Data dodania zlecenia.
deadline datetime Termin realizacji zlecenia.
individual boolean Czy zlecenie będzie zrealizowane przez jednego copywritera.
author model Copywriter wybrany przez klienta.
totalCost float Koszt całego zlecenia w punktach.
acceptedCount integer Liczba zatwierdzonych tekstów.
toAcceptCount integer Liczba tekstów oczekujących na zatwierdzenie.
rejectedCount integer Liczba tekstów oczekujących na poprawę (odrzuconych przez klienta).
status integer Status zlecenia: 0 - w trakcie realizacji, 1 - wykonane, 2 - wykonane częściowo, 3 - niewykonane w ogóle
orderDescription string Opis zamówienia.

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';
$subjectId = 'należy pobrać ID tematu';
$articleTypeId = 'należy pobrać ID typu tekstu';
$projectId = 'należy pobrać ID projektu';

$r = $client->post('api/orders', [
    'query' => ['access_token' => $token],
    'json'  => [
        'language'      => 'pl',
        'subject'       => $subjectId,
        'articleType'   => $articleTypeId,
        'keywords'      => ['słowo 1', 'słowo 2'], // zawsze tablica
        'minChars'      => 300,
        'articlesCount' => 2,
        'project'       => $projectId,
        'orderDescription' => 'Dodatkowy opis zlecenia'
    ]
]);

$newOrderData = $r->json();

Pobierz dane zlecenia

GET /api/orders/{id}

Pobierz dane zlecenia o podanym ID.

Parametry

Nazwa Typ Opis
id int ID zlecenia

Odpowiedź

Obiekt:

Nazwa Typ Opis
minChars integer Minimalna liczba znaków w pojedynczym tekście.
keywords collection Słowa kluczowe, które muszą znaleźć się w tekstach.
language string Język tekstów.
articlesCount integer Liczba zamówionych tekstów.
subject model Temat tekstów.
project model Projekt, do którego domyślnie trafią teksty.
articleType model Typ pisanych tekstów.
id integer ID zlecenia.
createdAt datetime Data dodania zlecenia.
deadline datetime Termin realizacji zlecenia.
individual boolean Czy zlecenie będzie zrealizowane przez jednego copywritera.
author model Copywriter wybrany przez klienta.
totalCost float Koszt całego zlecenia w punktach.
acceptedCount integer Liczba zatwierdzonych tekstów.
toAcceptCount integer Liczba tekstów oczekujących na zatwierdzenie.
rejectedCount integer Liczba tekstów oczekujących na poprawę (odrzuconych przez klienta).
status integer Status zlecenia: 0 - w trakcie realizacji, 1 - wykonane, 2 - wykonane częściowo, 3 - niewykonane w ogóle
orderDescription string Opis zamówienia.

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';
$orderId = 'należy pobrać ID zlecenia';

$r = $client->get('api/orders/' . $orderId, [
    'query' => ['access_token'  => $token]
]);

$orderData = $r->json();

Pobierz listę projektów

GET /api/projects

Pobiera listę projektów należących do użytkownika.

Odpowiedź

Tablica obiektów:

Nazwa Typ Opis
id integer ID projektu.
name string Nazwa projektu.
default boolean Czy projekt jest domyślny.
articlesCount integer Liczba tekstów w projekcie.
archived boolean Czy projekt znajduje się w archiwum.
createdAt datetime Data utworzenia projektu.

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';

$r = $client->get('api/projects', [
    'query' => ['access_token' => $token]
]);

$projects = $r->json();

Pobierz listę dostępnych tematów zleceń

GET /api/subjects

Odpowiedź

Tablica obiektów:

Nazwa Typ Opis
id integer ID tematu.
name string Nazwa tematu.

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';

$r = $client->get('api/subjects', [
    'query' => ['access_token' => $token]
]);

$subjets = $r->json();

Pobierz listę dostępnych typów tekstów

GET /api/types

Odpowiedź

Tablica obiektów:

Nazwa Typ Opis
id integer ID typu tekstu.
name string Nazwa typu tekstu.
description string Opis typu tekstu.
costPl float Cena za 1000 znaków dla j. polskiego.
costEn float Cena za 1000 znaków dla j. angielskiego.
costDe float Cena za 1000 znaków dla j. niemieckiego.
individual boolean Czy zarealizację zlecenia dla tego typu odpowiada jeden copywriter.

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';

$r = $client->get('api/types', [
    'query' => ['access_token' => $token]
]);

$types = $r->json();

Pobierz dane użytkownika

GET /api/user

Pobierz dane użytkownika.

Odpowiedź

Obiekt:

Nazwa Typ Opis
id integer ID użytkownika.
points float Punkty wykupione na zakup tekstów.
firstName string Imię.
lastName string Nazwisko
companyName string Nazwa firmy.
address string Adres.
postalCode string Kod pocztowy.
city string Miejscowość.
nip string NIP.
iban string Numer konta bankowego IBAN.
notifyCreated boolean Czy powiadamiać mailem o tekstach utworzonych przez copywritera.
legalForm string Forma prawna (osoba prywatna czy firma)
identityNo string Nr PESEL.
createdAt datetime Data rejestracji.

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

$token = 'należy pobrać token';

$r = $client->get('api/user', [
    'query' => ['access_token' => $token]
]);

$userData = $r->json();

Przykłady

Wznowienie zlecenia

<?php

use GuzzleHttp\Client;

$client = new Client(['base_url' => 'https://textbookers.com/']);

// Pobieranie tokenu

try {
    $r = $client->get('oauth/v2/token', [
        'query' => [
            'client_id'     => 'ID_KLIENTA',
            'client_secret' => 'TAJNY_KLUCZ',
            'grant_type'    => 'password',
            'username'      => 'TWOJ_EMAIL',
            'password'      => 'TWOJE_HASLO'
        ]
    ]);
} catch (GuzzleHttp\Exception\ClientException $e) {
    // obsługa błędu
}

$authData = $r->json();
$token = $authData['access_token'];

// Pobieranie niezrealizowanych zleceń

$r = $client->get('api/orders', [
    'query' => [
        'status'       => 'incomplete',
        'access_token' => $token
    ]
]);

if ($r->getStatusCode() != 200) {
    // obsługa błędu
}

$orders = $r->json();

// Wznawianie zleceń

foreach ($orders as $o) {
    $newOrder = [
        'language'      => $o['language'],
        'subject'       => $o['subject']['id'],
        'articleType'   => $o['articleType']['id'],
        'keywords'      => $o['keywords'],
        'minChars'      => $o['minChars'],
        'articlesCount' => $o['articlesCount'] - $o['acceptedCount'],
        'project'       => $o['project']['id'],
        'orderDescription' => $o['orderDescription']
    ];

    $r = $client->post('api/orders', [
        'body'  => $newOrder,
        'query' => ['access_token' => $token]
    ]);

    if ($r->getStatusCode() != 201) {
        // obsługa błędu
    }
}