API RapidTranslate

Introduzione

L'API RapidTranslate consente alla tua applicazione di inviare documenti per la traduzione certificata, recuperare informazioni aggiornate sullo stato e sui prezzi e ricevere i file finiti, senza che il tuo team debba interagire con la nostra procedura di pagamento. È pensata per le aziende che effettuano ordini di traduzione per conto dei propri clienti.

Tutte le richieste vanno inviate a https://www.rapidtranslate.org/api/v1 tramite HTTPS. Le richieste e le risposte sono in formato JSON, ad eccezione della creazione dell'ordine, che prevede il caricamento di file come multipart/form-data. Tutti gli importi vengono restituiti come centesimi interi in USD, e tutti i timestamp sono espressi in UTC secondo lo standard ISO-8601.

Collezione Postman

Preferisci esplorare l'API prima di scrivere qualsiasi codice? La nostra raccolta Postman contiene tutti gli endpoint preconfigurati, con autenticazione, corpi di esempio e parametri di query inclusi.

Scarica la raccolta Postman

1. In Postman, seleziona File → Importa e scegli il file scaricato.
2. Apri la collezione Variabili e impostare apiKey a una chiave da Impostazioni aziendali → Chiavi API.
3. (Facoltativo) Imposta baseUrl per il tuo ambiente — l'impostazione predefinita è "produzione".
4. Invia qualsiasi richiesta. Utilizza una chiave Sandbox per effettuare dei test senza effettuare ordini a pagamento.

Autenticazione

Autentica ogni richiesta utilizzando la tua chiave API segreta come token bearer e richiedi una risposta in formato JSON. Entrambe le intestazioni sono obbligatorie:

Autorizzazione: Bearer YOUR_API_KEY
Accept: application/json

È possibile generare e aggiornare le chiavi nella dashboard alla voce Impostazioni aziendali → Chiavi API. Le chiavi vengono visualizzate una sola volta al momento della creazione e vengono memorizzate in forma hash: se si perde una chiave, è necessario aggiornarla. Ogni chiave appartiene a una modalità (Live o Sandbox) e presenta un insieme fisso di ambiti.

Campi di applicazione

Ogni endpoint richiede una specifica funzionalità della chiave. Una chiave priva dell'ambito richiesto restituisce 403 ambito non consentito.

Modalità sandbox e modalità di prova

La modalità di prova è una proprietà della chiave, non del tuo account. Una chiave Sandbox opera in un ambiente completamente simulato; una chiave Live effettua ordini reali e fatturabili. Puoi utilizzare entrambe contemporaneamente.

Gli ordini in modalità sandbox utilizzano le stesse procedure di convalida, mappatura dei campi e prezzi reali, ma tralasciano l’archiviazione dei file, l’OCR e l’evasione dell’ordine. Al momento della creazione, un ordine in modalità sandbox percorre automaticamente il proprio ciclo di vita (in elaborazione → completato), attivando gli stessi webhook di un ordine effettivo e, infine, fornendo un documento di esempio statico.

Ogni risposta e ogni webhook contiene un modalità live Imposta questo flag in modo che la tua integrazione possa creare un ramo senza verificare la chiave:

• livemode: true — ordine effettivo e fatturabile
• livemode: false — sandbox / ordine di prova

Limiti di frequenza

Le richieste sono soggette a un limite di frequenza per ogni organizzazione. La quota predefinita è 120 richieste al minuto. Se viene superato, restituisce 429 rate_limited; riprovare dopo una breve pausa. Se la vostra integrazione richiede un limite più alto, contattate support@rapidtranslate.org.

Risposte

Ogni risposta riuscita racchiude il proprio payload in un dati chiave. Gli endpoint dell'elenco aggiungono un meta blocco con impaginazione.

Risorsa singola

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

Elenco impaginato

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

Errori

Gli errori utilizzano i codici di stato HTTP standard e restituiscono un formato stabile e leggibile dal computer codice_errore insieme a un messaggio scritto a mano. Gli errori di convalida aggiungono un campo con chiave errori oggetto.

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

Stati degli ordini

Un ordine stato segue un ciclo di vita stabile. Questi cinque valori sono anche quelli adottati dal stato filtra per Elenco degli ordini:

Mentre un ordine è in corso di elaborazione, vengono visualizzate etichette più dettagliate (ad esempio Assegnato al traduttore, Tradurre, Spedito) potrebbero comparire. Quando è richiesta l'approvazione, un ordine può riportare brevemente pagamento_non_riuscito o credit_hold se non fosse stato possibile riscuotere l'importo, definire la modalità di pagamento e approvare nuovamente.

Valori dei campi

I set fissi accettati al momento della creazione di un ordine.

Tipi di traduzione

Risanamento

Modalità di consegna

Webhook

Invece di effettuare il polling, configura un endpoint webhook per ricevere gli eventi in tempo reale. Imposta il tuo URL e visualizza il tuo segreto di firma in Impostazioni aziendali → Webhook. I webhook sono una soluzione pratica: il recupero di un ordine è sempre attendibile.

Eventi

Busta

Ogni spedizione viene spedita con la stessa busta: una evento blocco (compreso modalità live) e uno specifico per l'evento dati blocco.

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

Il consegna_documenti L'evento aggiunge un documenti array (ciascuno con nome, download_url, versione, stato) e un portale link. Il recensione_del_cliente L'evento aggiunge una voce dettagliata prezzi blocco e un azioni.approva oggetto contenente l'URL da chiamare.

Verifica delle firme

Ogni richiesta è firmata, in modo da poter verificare che provenga da RapidTranslate. Inviamo tre intestazioni:

Calcolare la firma prevista come HMAC-SHA256 della stringa "{timestamp}.{raw_request_body}" utilizzando il segreto di firma del tuo webhook, quindi confrontalo con il valore dell'intestazione:

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

Node.js (Express) — associare la route a un parser del corpo grezzo in modo da preservare esattamente i byte:

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

Ci sono tre cose che mettono in difficoltà le persone:

• Il X-RapidTranslate-Firma L'intestazione riporta un sha256= prefisso. Effettuare il confronto con 'sha256=' + yourHmac (come sopra) oppure rimuovere il prefisso prima di effettuare il confronto — non confrontare il valore esadecimale "nudo" con l'intera intestazione.
• Esegui l'hash del corpo della richiesta grezza esattamente così come è stato ricevuto. La riserializzazione del JSON analizzato modifica gli spazi bianchi e l'ordine delle chiavi, quindi la firma non corrisponderà: leggi il corpo prima che qualsiasi middleware JSON lo analizzi.
• Confronta in tempo costante (hash_equals / crypto.timingSafeEqual), mai con == o ===.

Il {timestamp} fa parte della stringa firmata, quindi leggila dall’intestazione e inseriscila all’inizio prima di eseguire l’hash. Consente inoltre di rifiutare le consegne obsolete o riprodotte — ad esempio, qualsiasi timestamp più vecchio di cinque minuti.

Le consegne non andate a buon fine vengono riprovate con un back-off esponenziale (fino a 5 tentativi). Rispondere con un 2xx stato per confermare la ricezione.