Integracja z TurboTłumaczenia.pl

TurboTłumaczenia to serwis pozwalający w szybki i efektywny sposób tłumaczyć teksty. Aby umożliwić klientom jeszcze lepsze wykorzystanie możliwości naszej usługi, udostępniliśmy REST API.

Dostęp do API

Dostęp do API ma każdy użytkownik TurboTłumaczeń. Jeśli nie masz jeszcze konta - zarejestruj się.

Powiadomienia push oraz e-mail

Zlecenia utworzone poprzez API nie wysyłają standardowych wiadomości na adres e-mail klienta, ani powiadomień push.

Sandbox

Testowa wersja API znajduje się pod adresem http://sandbox.turbotlumaczenia.pl. Aby otrzymać dostęp do sandboxa, prosimy o kontakt na adres api@turbotlumaczenia.pl.

Sandbox obecnie posiada nieuwierzytelniony certyfikat SSL. W celu ustanowienia połączenia szyfrowanego należy ustawić odpowiednią opcję.

Np. dla curl:

--insecure

Automatyczne akceptowanie i wysyłanie zleceń

Na sandbox po 60s system automatycznie przydziela tłumacza do zlecenia. Po kolejnych 60s, tłumacz dostarcza gotowe tłumaczenie.

Przykłady

Przykładowy kod jest dostępny pod adresem https://github.com/TurboTranslations/tapi lub jest do pobrania po kliknięciu w jeden z linków w nagłówku tej strony.

Uwierzytelnienie

Każdy użytkownik posiada unikalny klucz. Uwierzytelnienie klienta jest oparte o "token-based HTTP Authentication scheme".

Klucz należy przekezać w nagłówku HTTP wywołania API:

Authorization: Token token=TOKEN_ID

Lista par językowych

Lista wszystkich par językowych obsługiwanych przez API. W przypadku konieczności tłumaczenia innej pary językowej, prosimy o kontakt na adres kontakt@turbotlumaczenia.pl.

Definicja

GET https://turbotlumaczenia.pl/tapi/v1/language_pairs

Rezultat

[
    {
        "source_language": {
            "code": "rus",
            "name": "rosyjski"
        },
        "target_language": {
            "code": "pol",
            "name": "polski"
        }
    },
    ...
]

Przykład

curl -H "Authorization: Token token=TOKEN_ID" 
"https://turbotlumaczenia.pl/tapi/v1/language_pairs"

Lista kategorii

Lista kategorii/dziedzin tekstów do tłumaczenia. Określenie kategorii jest wymagane do wyceny i złożenia zamówienia.

Definicja

GET https://turbotlumaczenia.pl/tapi/v1/categories

Rezultat

[
    {
        "name": "Dziennikarstwo / Media"
    },
    ...
]

Przykład

curl -H "Authorization: Token token=TOKEN_ID" 
"https://turbotlumaczenia.pl/tapi/v1/categories"

Wycena tekstu

Przed złożeniem właściwego zamówienia można wcześniej otrzymać wycenę tekstu do tłumaczenia.

Definicja

POST https://turbotlumaczenia.pl/tapi/v1/quotes

Rezultat

{
    "category": "Motoryzacja / lotnictwo",
    "eta": 1800,
    "price": {
        "currency": "PLN",
        "value": 2.0
    },
    "source_language": "pol",
    "target_language": "eng",
    "word_count": 2
}

Przykład

curl -d 
'{
   "category":"Motoryzacja / lotnictwo",
   "source_language":"pol",
   "target_language":"eng",
   "text":"Sample text"
}' 
-X POST -H "Content-Type: application/json" 
-H "Authorization: Token token=TOKEN_ID" 
"https://turbotlumaczenia.pl/tapi/v1/quotes"

Dodanie zlecenia

Złożenie właściwego zlecenia. Cena za tłumaczenie zostanie od razu pobrana z konta użytkownika. W przypadku braku środków API zwróci błąd.

Definicja

POST https://turbotlumaczenia.pl/tapi/v1/jobs

Rezultat

{
    "callback_url": "https://example.com/callback",
    "category": "Motoryzacja / lotnictwo",
    "client_comment": "Sample comment",
    "created_at": "2015-05-21T17:15:54Z",
    "eta": 1800,
    "favorite_translators": false,
    "id": "c9001d4140",
    "price": {
        "currency": "PLN",
        "value": 2.0
    },
    "source_language": "pol",
    "source_text": "Sample text",
    "status": "pending",
    "target_language": "eng",
    "word_count": 2
}

Parametry zapytania

Nazwa Typ Wymagany Opis
category string tak nazwa kategorii
source_language string tak kod języka źródłowego
target_language string tak kod języka docelowego
text string tak tekst do tłumaczenia
email string nie email klienta, domyślnie e-mail konta użytkownika
comment string nie dodatkowe informacje dla tłumacza
callback_url string nie url, na który zostanie wysłane tłumaczenie (więcej w sekcji "callback")
favourite_translators integer (1) nie zlecenie tylko dla ulubionych tłumaczy

Parametry odpowiedzi

Nazwa Opis
callback_url podany url, na który zostanie wysłane tłumaczenie
category wybrana kategoria tłumaczenia
client_comment komentarz klienta do zlecenia
created_at czas dodania zlecenia
eta szacunkowy czas tłumaczenia w sekundach
favourite_translators informacja czy zlecenie zostało wysłane tylko do ulubionych tłumaczy
id numer zlecenia
price cena za tłumaczenie
source_language język źródlowy
target_language język docelowy
status status zlecenia (patrz tabela poniżej)
source_text tekst do tłumaczenia
target_text tłumaczenie
translator_comment komentarz od tłumacza
delivered_at czas dostarczenia tłumaczenia
word_count ilość wyrazów w tekście

Status zlecenia

Nazwa Opis
new zlecenie oczekuje na płatność
pending zlecenie przekazane do tłumaczy, oczekuje na akceptację
accepted tłumacz rozpoczął tłumaczenie tekstu
failed płatność nieudana
canceled zlecenia anulowane
delivered tłumacz wysłał gotowy tekst
completed tłumaczenie zostało zaakceptowane przez klienta lub automatycznie po 4 dniach

Przyklad

curl -d '
{
   "category":"Motoryzacja / lotnictwo",
   "source_language":"pol",
   "target_language":"eng",
   "text":"Sample text",
   "callback_url":"https://example.com/callback",
   "comment":"Sample comment"
}' 
-X POST -H "Content-Type: application/json" 
-H "Authorization: Token token=TOKEN_ID" 
"https://turbotlumaczenia.pl/tapi/v1/jobs"

Szczegóły zlecenia

Metoda zwraca m.in. przetłumaczony tekst jeśli tłumacz zakończył pracę nad zleceniem.

Definicja

GET https://turbotlumaczenia.pl/tapi/v1/jobs/:id

Rezultat

{
    "callback_url": "https://example.com/callback",
    "category": "Motoryzacja / lotnictwo",
    "created_at": "2015-05-19T11:30:09Z",
    "delivered_at": "2015-05-19T11:54:54Z",
    "eta": 1800,
    "favorite_translators": false,
    "id": "77b91dc6de",
    "price": {
        "currency": "PLN",
        "value": 2.0
    },
    "source_language": "pol",
    "source_text": "Lorem ipsum dolor sit amet",
    "status": "delivered",
    "target_language": "eng",
    "target_text": "Cras quis tincidunt lectus.",
    "translator": {
        "name": "Sandra"
    },
    "translator_comment": "Sed viverra erat vel nunc aliquet iaculis.",
    "word_count": 5
}

Przyklad

curl -H "Authorization: Token token=TOKEN_ID" 
"https://turbotlumaczenia.pl/tapi/v1/jobs/:id"

Lista zleceń

Lista ostatnich 50 zleceń posortowanych od najnowszego do najstarszego.

Definicja

GET https://turbotlumaczenia.pl/tapi/v1/jobs

Rezultat

[
    {
        "created_at": "2015-05-21T17:22:07Z",
        "id": "2712f3da8b",
        "path": "/tapi/v1/jobs/2712f3da8b",
        "source_language": "pol",
        "status": "pending",
        "target_language": "eng"
    },
    ...
]

Przykład

curl -H "Authorization: Token token=TOKEN_ID" 
"https://turbotlumaczenia.pl/tapi/v1/jobs"

Szczegóły konta

Informacje dotyczące konta użytkownika.

Definicja

GET https://turbotlumaczenia.pl/tapi/v1/account

Rezultat

{
    "balance": {
        "currency": "PLN",
        "value": "100.00"
    },
    "email": "account@example.org",
    "type": "prepaid"
}

Przykład

curl -H "Authorization: Token token=TOKEN_ID" 
"https://turbotlumaczenia.pl/tapi/v1/account"

Callback

Po wysłaniu gotowego tekstu przez tłumacza, API wysyła żądanie na podany adres callback_url metodą POST.

Parametry

Nazwa Opis
id ID zlecenia
translator_comment komentarz od tłumacza
status status zlecenia
source_language kod języka źródłowego
target_language kod języka docelowego
target_text tłumaczenie

Błędy

W przypadku wystąpienia błędu, API zwróci kod HTTP 422 (unprocessable entity) i stosowną odpowiedź.

Np.

{
    "code": 104,
    "message": "Brak tekstu do tlumaczenia"
}

Kody błędów

Numer Opis
100 nieprawidłowa kategoria tłumaczenia
101 nieprawidłowy język źródłowy
102 nieprawidłowy język docelowy
103 nieprawidłowa para językowa
104 brak tekstu do tłumaczenia
105 nieprawidłowy zwrotny adres URL
106 brak wystarczających środków na koncie
107 nieprawidłowy adres e-mail
150 inny błąd

Support

W razie pytań lub wątpliwości proszę pisać na adres api@turbotlumaczenia.pl.