Rapid Translate API

Wstęp

Ten Rapid Translate API pozwala Twojej aplikacji przesyłać dokumenty do tłumaczenia uwierzytelnionego, sprawdzać aktualny status i ceny oraz odbierać gotowe pliki – bez konieczności kontaktowania się Twojego zespołu z naszym zespołem. API jest przeznaczone dla firm, które zlecają tłumaczenia w imieniu swoich klientów.

Wszystkie prośby są kierowane do https://www.rapidtranslate.org/api/v1 przez HTTPS. Żądania i odpowiedzi są w formacie JSON, z wyjątkiem tworzenia zamówienia, które przesyła pliki jako multipart/form-data. Wszystkie kwoty są zwracane w formie centy całkowite w USD, a wszystkie znaczniki czasu podano w formacie UTC ISO‑8601.

Kolekcja Listonosza

Wolisz klikać w API przed napisaniem kodu? Nasza kolekcja Postman zawiera wszystkie wstępnie skonfigurowane punkty końcowe — uwierzytelnianie, przykładowe treści i parametry zapytania.

Pobierz kolekcję Postman

1. W programie Postman wybierz Plik → Importuj i wybierz pobrany plik.
2. Otwórz kolekcję Zmienne i ustaw klucz API do klucza od Ustawienia biznesowe → Klucze API.
3. (Opcjonalnie) Ustaw adres URL bazowy dla Twojego środowiska — domyślnie jest to środowisko produkcyjne.
4. Wyślij dowolne zapytanie. Użyj klucza Sandbox do testowania bez składania zamówień płatnych.

Uwierzytelnianie

Uwierzytelniaj każde żądanie za pomocą swojego tajnego klucza API jako tokenu nośnika i poproś o odpowiedź JSON. Wymagane są oba nagłówki:

Autoryzacja: Nośnik YOUR_API_KEY Akceptacja: application/json

Generuj i rotuj klucze w panelu sterowania w Ustawieniach firmowych → Klucze API . Klucze są wyświetlane jednorazowo podczas tworzenia i przechowywane w postaci hashowanej — jeśli zgubisz klucz, możesz go rotować. Każdy klucz należy do jednego trybu (Live lub Sandbox) i zawiera stały zestaw zakresów.

Zakresy

Każdy punkt końcowy wymaga określonej zdolności klucza. Klucz, który nie spełnia wymaganego zakresu, zwraca 403 zabroniony_zakres.

Tryb piaskownicy i testowy

Tryb testowy jest właściwością klucza , a nie Twojego konta. Klucz Sandbox działa w w pełni symulowanym środowisku, natomiast klucz Live składa rzeczywiste, rozliczane zamówienia. Możesz używać obu jednocześnie.

Zamówienia w trybie sandbox korzystają z tych samych procedur walidacji, mapowania pól i rzeczywistych cen, ale pomijają przechowywanie plików, OCR i realizację. Po utworzeniu zamówienie w trybie sandbox automatycznie przechodzi przez cykl życia (przetwarzanie → ukończone), uruchamiając te same webhooki, co zamówienie na żywo i na koniec dostarczając statyczny przykładowy dokument.

Każda odpowiedź i webhook niesie ze sobą tryb na żywo flagę, dzięki której integracja będzie mogła się rozgałęziać bez konieczności sprawdzania klucza:

• tryb na żywo: prawda — rzeczywiste, płatne zamówienie
• tryb na żywo: fałsz — piaskownica / kolejność testowania

Limity stawek

Liczba żądań jest ograniczona do organizacji. Domyślny limit wynosi 120 żądań na minutę. Przekroczenie go zwraca 429 rate_limited; spróbuj ponownie po krótkim odczekaniu. Jeśli Twoja integracja wymaga wyższego limitu, skontaktuj się z wsparcie@rapidtranslate.org.

Odpowiedzi

Każda pomyślna odpowiedź zawiera swój ładunek dane klucz. Lista punktów końcowych dodaje meta blok z paginacją.

Pojedynczy zasób

{
  "data": {
    "id": "9b1c...-uuid",
    "reference": "APO-10432",
    "status": "processing",
    "total": 11270,
    "currency": "USD"
  }
}

Lista stronicowana

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 134,
    "last_page": 6
  }
}

Błędy

Błędy korzystają ze standardowych kodów stanu HTTP i zwracają stabilny, czytelny dla maszyny kod. kod_błędu obok wiadomości ludzkiej. Błędy walidacji dodają pole z kluczem błędy obiekt.

{
  "message": "The given data was invalid.",
  "error_code": "validation_failed",
  "errors": {
    "source_language": ["The selected source language is invalid."]
  }
}

Statusy zamówień

Zamówienie status podąża za stabilnym cyklem życia. Te pięć wartości to również te akceptowane przez status filtruj na Zamówienia na liście:

W trakcie realizacji zamówienia mogą być potrzebne bardziej szczegółowe etykiety (np. Przypisane do tłumacza, Tłumaczenie, Wysłany) może również się pojawić. W przypadku konieczności zatwierdzenia zamówienie może zawierać krótki raport płatność_nieudana Lub wstrzymanie_kredytu jeśli nie udało się pobrać opłaty — wybierz metodę płatności i zatwierdź ją ponownie.

Wartości pól

Zestawy stałe akceptowane są podczas tworzenia zamówienia.

Typy tłumaczeń

Zmiana kierunku

Metody dostawy

Webhooki

Zamiast sondowania, skonfiguruj punkt końcowy webhooka, aby odbierać zdarzenia w momencie ich wystąpienia. Ustaw swój adres URL i wyświetl swój klucz podpisu w Ustawieniach firmowych → Webhooki . Webhooki to wygoda — pobranie zamówienia jest zawsze autoryzowane.

Wydarzenia

Koperta

Każda przesyłka ma taką samą kopertę: wydarzenie blok (w tym tryb na żywo) i wydarzenie specyficzne dla danego wydarzenia dane blok.

{
  "event": {
    "type": "order_status",
    "id": "evt_9b1c...",
    "livemode": true,
    "sent_at": "2026-08-28T10:20:00+00:00"
  },
  "data": {
    "order": {
      "id": "9b1c2d3e-...-uuid",
      "reference": "APO-10432",
      "status": "completed"
    }
  }
}

Ten dostawa_dokumentu wydarzenie dodaje dokumenty tablica (każda z nazwa, adres_url_pobierania, wersja, status) i portal łącze. recenzja_klienta wydarzenie dodaje wyszczególniony wycena blok i działania.zatwierdź obiekt z adresem URL do wywołania.

Weryfikacja podpisów

Każde żądanie jest podpisane, dzięki czemu możesz potwierdzić, że pochodzi od Rapid Translate Wysyłamy trzy nagłówki:

Oblicz oczekiwany podpis jako HMAC‑SHA256 ciągu "{znacznik czasu}.{surowa_treść_żądania}" używając tajnego klucza podpisu webhooka, a następnie porównaj go z wartością nagłówka:

// PHP
$expected = 'sha256=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $rawBody,
    $webhookSecret
);
$valid = hash_equals($expected, $signatureHeader);

Node.js (Express) — zamontuj trasę za pomocą surowego parsera treści, aby zachować dokładne bajty:

// app.use('/webhooks/rapidtranslate', express.raw({ type: 'application/json' }))
const crypto = require('crypto');

const timestamp = req.get('X-RapidTranslate-Timestamp');
const received  = req.get('X-RapidTranslate-Signature'); // "sha256=..."
const rawBody   = req.body;                               // Buffer, untouched

const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

const valid = received &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

Są trzy rzeczy, które ludziom przeszkadzają:

• Ten X-RapidTranslate-Podpis nagłówek zawiera sha256= prefiks. Porównaj z 'sha256=' + twójHmac (jak powyżej) lub usuń prefiks przed porównaniem — nie dopasowuj gołego kodu szesnastkowego do całego nagłówka.
• Przeprowadź hash surowego tekstu żądania dokładnie tak, jak go otrzymano. Ponowna serializacja sparsowanego JSON zmienia odstępy i kolejność kluczy, więc podpis nie będzie pasował — odczytaj tekst żądania, zanim jakiekolwiek oprogramowanie pośredniczące JSON go sparsuje.
• Porównaj w czasie stałym (hash_equals / crypto.timingSafeEqual), nigdy z == Lub ===.

Ten {znacznik czasu} jest częścią podpisanego ciągu, więc odczytaj go z nagłówka i dodaj przed haszowaniem. Pozwala to również odrzucać nieaktualne lub powtarzane przesyłki — np. te ze znacznikiem czasu starszym niż pięć minut.

Nieudane dostawy są ponawiane z wykładniczym opóźnieniem (do 5 prób). Odpowiedz 2xx status potwierdzenia odbioru.