RapidTranslate-API

Einleitung

Mit der RapidTranslate-API kann Ihre Anwendung Dokumente zur beglaubigten Übersetzung einreichen, aktuelle Status- und Preisinformationen abrufen und die fertigen Dateien erhalten – ohne dass Ihr Team unseren Bestellvorgang nutzen muss. Sie richtet sich an Unternehmen, die im Auftrag ihrer eigenen Kunden Übersetzungsaufträge erteilen.

Alle Anfragen sind zu richten an https://www.rapidtranslate.org/api/v1 über HTTPS. Anfragen und Antworten erfolgen im JSON-Format, mit Ausnahme der Auftragserstellung, bei der Dateien als multipart/form-data. Alle Beträge werden zurückerstattet als ganzzahlige Cent in USD, und alle Zeitangaben erfolgen im UTC-Format gemäß ISO-8601.

Postman-Sammlung

Möchten Sie sich lieber erst mit der API vertraut machen, bevor Sie Code schreiben? In unserer Postman-Sammlung sind alle Endpunkte bereits vorkonfiguriert – einschließlich Authentifizierung, Beispiel-Content-Teils und Abfrageparameter.

Postman-Sammlung herunterladen

1. Wählen Sie in Postman „Datei“ → „Importieren“ und wählen Sie die heruntergeladene Datei aus.
2. Öffnen Sie die Sammlung Variablen und festlegen apiKey zu einem Schlüssel aus Unternehmens-Einstellungen → API-Schlüssel.
3. (Optional) Festlegen baseUrl für Ihre Umgebung – standardmäßig ist „Produktion“ eingestellt.
4. Senden Sie eine beliebige Anfrage. Verwenden Sie einen Sandbox- Schlüssel, um zu testen, ohne kostenpflichtige Bestellungen aufzugeben.

Authentifizierung

Authentifizieren Sie jede Anfrage mit Ihrem geheimen API-Schlüssel als Bearer-Token und fordern Sie eine JSON-Antwort an. Beide Header sind erforderlich:

Autorisierung: Bearer YOUR_API_KEY
Accept: application/json

Sie können Schlüssel in Ihrem Dashboard unter „Geschäftseinstellungen“ → „API-Schlüssel“ generieren und rotieren. Schlüssel werden bei der Erstellung einmalig angezeigt und in gehashter Form gespeichert – sollten Sie einen Schlüssel verlieren, rotieren Sie ihn. Jeder Schlüssel gehört zu einem Modus (Live oder Sandbox) und verfügt über einen festen Satz von Gültigkeitsbereichen.

Anwendungsbereiche

Jeder Endpunkt erfordert eine bestimmte Funktion des Schlüssels. Ein Schlüssel, bei dem der erforderliche Geltungsbereich fehlt, gibt Folgendes zurück: 403 forbidden_scope.

Sandbox- und Testmodus

Der Testmodus ist eine Eigenschaft des Schlüssels, nicht Ihres Kontos. Ein Sandbox-Schlüssel wird in einer vollständig simulierten Umgebung ausgeführt; ein Live-Schlüssel gibt echte, abrechnungsfähige Bestellungen auf. Sie können beide gleichzeitig verwenden.

Sandbox-Bestellungen unterliegen denselben Validierungs- und Feldzuordnungsregeln sowie den tatsächlichen Preisen, jedoch entfallen dabei die Dateispeicherung, die OCR und die Auftragsabwicklung. Bei der Erstellung durchläuft eine Sandbox-Bestellung automatisch ihren gesamten Lebenszyklus (Bearbeitung → abgeschlossen), wobei dieselben Webhooks wie bei einer Live-Bestellung ausgelöst werden und schließlich ein statisches Beispieldokument bereitgestellt wird.

Jede Antwort und jeder Webhook enthält einen Live-Modus Flag, damit Ihre Integration eine Verzweigung erstellen kann, ohne den Schlüssel zu überprüfen:

• livemode: true — echter, abrechnungsfähiger Auftrag
• livemode: false — Sandbox / Testbestellung

Ratenbegrenzungen

Die Anzahl der Anfragen ist pro Organisation begrenzt. Das Standardkontingent beträgt 120 Anfragen pro Minute. Wird dieser Wert überschritten, wird 429 rate_limited; versuchen Sie es nach einer kurzen Wartezeit erneut. Falls Ihre Integration einen höheren Grenzwert benötigt, wenden Sie sich bitte an support@rapidtranslate.org.

Antworten

Jede erfolgreiche Antwort verpackt ihre Nutzdaten in ein Daten Schlüssel. Endpunkte der Liste fügen einen Meta Block mit Paginierung.

Einzelne Ressource

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

Paginierte Liste

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

Fehler

Fehler verwenden Standard-HTTP-Statuscodes und geben einen stabilen, maschinenlesbaren Fehlercode zusammen mit einer menschlichen Nachricht. Validierungsfehler fügen ein feldbezogenes Fehler Objekt.

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

Bestellstatus

Die Bestellung Status folgt einem stabilen Lebenszyklus. Diese fünf Werte sind auch diejenigen, die von der Status Filter aktivieren Bestellungen auflisten:

Solange ein Auftrag in Bearbeitung ist, werden detailliertere Bezeichnungen (zum Beispiel Dem Übersetzer zugewiesen, Übersetzen, Versendet) können ebenfalls auftreten. Wenn eine Genehmigung erforderlich ist, kann in einem Auftrag kurz darauf hingewiesen werden, Zahlung_fehlgeschlagen oder credit_hold Falls eine Abbuchung nicht möglich war – legen Sie die Zahlungsmethode fest und genehmigen Sie den Vorgang erneut.

Feldwerte

Die festen Sätze, die bei der Erstellung eines Auftrags akzeptiert werden.

Übersetzungsarten

Wende

Versandarten

Webhooks

Anstatt Abfragen durchzuführen, richten Sie einen Webhook-Endpunkt ein, um Ereignisse in Echtzeit zu empfangen. Legen Sie Ihre URL fest und rufen Sie Ihr Signaturgeheimnis unter „Geschäftseinstellungen“ → „Webhooks“ ab. Webhooks sind eine praktische Ergänzung – das Abrufen einer Bestellung ist stets maßgebend.

Veranstaltungen

Umschlag

Jede Sendung wird in demselben Umschlag verschickt: einem Veranstaltung Block (einschließlich Live-Modus) und ein ereignisspezifisches Daten Block.

{
  "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"
    }
  }
}

Die Dokumentenlieferung Das Ereignis fügt ein Dokumente Array (jeweils mit Name, download_url, Version, Status) und ein Portal Link. Der Kundenbewertung Das Ereignis fügt eine detaillierte Aufstellung hinzu Preisgestaltung Block und ein actions.approve Objekt mit der aufzurufenden URL.

Überprüfung von Unterschriften

Jede Anfrage ist signiert, sodass Sie überprüfen können, ob sie tatsächlich von RapidTranslate stammt. Wir senden drei Header:

Berechne die erwartete Signatur als HMAC-SHA256 der Zeichenkette "{timestamp}.{raw_request_body}" Verwenden Sie dazu Ihr Webhook-Signatur-Geheimnis und vergleichen Sie es anschließend mit dem Wert im Header:

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

Node.js (Express) – Binde die Route mit einem Raw-Body-Parser ein, damit die genauen Bytes erhalten bleiben:

// 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));

Drei Dinge bereiten den Menschen Schwierigkeiten:

• Die X-RapidTranslate-Signatur Die Kopfzeile enthält eine sha256= Präfix. Entweder mit folgendem vergleichen: 'sha256=' + yourHmac (wie oben) oder entferne das Präfix vor dem Vergleich – vergleiche nicht den reinen Hexadezimalwert mit dem gesamten Header.
• Führen Sie einen Hash des rohen Request-Körpers genau so durch, wie er empfangen wurde. Durch die erneute Serialisierung von geparstem JSON ändern sich Leerzeichen und die Reihenfolge der Schlüssel, sodass die Signatur nicht mehr übereinstimmt – lesen Sie den Request-Körper, bevor er von einer JSON-Middleware geparst wird.
• Vergleiche in konstanter Zeit (hash_equals / crypto.timingSafeEqual), niemals mit == oder ===.

Die {timestamp} ist Teil der signierten Zeichenfolge, also lies sie aus dem Header aus und füge sie vor dem Hashing vor. Außerdem kannst du damit veraltete oder erneut gesendete Zustellungen zurückweisen – z. B. alle Zeitstempel, die älter als fünf Minuten sind.

Fehlgeschlagene Übermittlungen werden mit exponentiellem Backoff erneut versucht (bis zu 5 Versuche). Antworte mit einem 2xx Status zur Empfangsbestätigung.