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ą z 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:

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

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://www.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

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

Odpowiedź

Tablica obiektów:

Przykład

<?php

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

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://www.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

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

Dane zapytania

Odpowiedź

Obiekt:

Przykład

<?php

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

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://www.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

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

Filtry

Odpowiedź

Tablica obiektów:

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://www.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ń

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

Filtry

Odpowiedź

Tablica obiektó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_uri' => 'https://www.textbookers.com/']);

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

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

$orders = $r->json();

Dodaj nowe zlecenie

Dane zapytania

Odpowiedź

Obiekt:

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://www.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

Pobierz dane zlecenia o podanym ID.

Parametry

Odpowiedź

Obiekt:

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://www.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

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

Odpowiedź

Tablica obiektów:

Przykład

<?php

use GuzzleHttp\Client;

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

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

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

$projects = $r->json();

Dodaj nowy projekt

Dane zapytania

Odpowiedź

Obiekt:

Przykład

<?php

use GuzzleHttp\Client;

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

$token = 'należy pobrać token';
$name = 'Nazwa projektu';

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

$project = $r->json();

Usuń istniejący projekt

Parametry

Przykład

<?php

use GuzzleHttp\Client;

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

$token = 'należy pobrać token';
$projectId = 'należy pobrać ID projektu';

$r = $client->delete(sprintf('api/projects/%d', $projectId), [
    'query' => ['access_token' => $token],
]);

$r->getStatusCode();

Zmień dane projektu

Parametry

Dane zapytania

Odpowiedź

Obiekt:

Przykład

<?php

use GuzzleHttp\Client;

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

$token = 'należy pobrać token';
$projectId = 'należy pobrać ID projektu';
$name = 'Nowa nazwa projektu';

$r = $client->patch(sprintf('api/projects/%d', $projectId), [
    'query' => ['access_token' => $token],
    'json' => [
        'name' => $name,
    ],
]);

$project = $r->json();

Pobierz listę dostępnych tematów zleceń

Odpowiedź

Tablica obiektów:

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://www.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

Odpowiedź

Tablica obiektów:

Przykład

<?php

use GuzzleHttp\Client;

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

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

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

$types = $r->json();

Pobierz dane użytkownika

Pobierz dane użytkownika.

Odpowiedź

Obiekt:

Przykład

<?php

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://www.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_uri' => 'https://www.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
    }
}