API RapidTranslate

Introduction

L'API RapidTranslate permet à votre application d'envoyer des documents pour une traduction certifiée, de consulter l'état d'avancement et les tarifs actualisés, et de recevoir les fichiers finis — sans que votre équipe ait à passer par notre processus de paiement. Elle est conçue pour les entreprises qui passent des commandes de traduction pour le compte de leurs propres clients.

Toutes les demandes doivent être adressées à https://www.rapidtranslate.org/api/v1 via HTTPS. Les requêtes et les réponses sont au format JSON, sauf lors de la création d'une commande, où les fichiers sont téléchargés sous la forme de multipart/form-data. Tous les montants sont restitués sous la forme de centimes entiers en dollars américains, et tous les horodatages sont au format UTC ISO-8601.

Collection Postman

Vous préférez explorer l'API avant de commencer à coder ? Notre collection Postman contient tous les points de terminaison préconfigurés : authentification, exemples de corps de requête et paramètres de requête inclus.

Télécharger la collection Postman

1. Dans Postman, choisissez Fichier → Importer, puis sélectionnez le fichier téléchargé.
2. Ouvrez la collection Variables et définir apiKey à une clé provenant de Paramètres de l'entreprise → Clés API.
3. (Facultatif) Définir baseUrl pour votre environnement — la valeur par défaut est « production ».
4. Envoyez toutes vos demandes. Utilisez une clé « Sandbox » pour effectuer des tests sans passer de commandes facturables.

Authentification

Authentifiez chaque requête à l'aide de votre clé API secrète en tant que jeton « bearer », puis demandez une réponse au format JSON. Les deux en-têtes sont obligatoires :

Autorisation : Bearer VOTRE_CLÉ_API
Accept : application/json

Vous pouvez générer et renouveler des clés dans votre tableau de bord, sous « Paramètres de l'entreprise » → « Clés API ». Les clés s'affichent une seule fois lors de leur création et sont stockées sous forme hachée. Si vous perdez une clé, renouvelez-la. Chaque clé correspond à un mode (Production ou Sandbox) et dispose d'un ensemble fixe de périmètres d'accès.

Champs d'application

Chaque point de terminaison nécessite une capacité spécifique sur la clé. Une clé ne disposant pas de la portée requise renvoie 403 accès interdit_scope.

Mode bac à sable et mode test

Le mode test est une propriété de la clé, et non de votre compte. Une clé « Sandbox » fonctionne dans un environnement entièrement simulé ; une clé « Live » passe des commandes réelles et facturables. Vous pouvez utiliser les deux simultanément.

Les commandes en mode « sandbox » utilisent les mêmes processus de validation, de mappage des champs et de tarification réelle, mais ne prennent pas en charge le stockage des fichiers, la reconnaissance optique de caractères (OCR) ni l'exécution de la commande. Dès sa création, une commande en mode « sandbox » suit automatiquement son cycle de vie (en cours de traitement → terminé), en déclenchant les mêmes webhooks qu'une commande en production et en fournissant enfin un exemple de document statique.

Chaque réponse et chaque webhook contient un livemode Activez cette option pour que votre intégration puisse créer une branche sans vérifier la clé :

• livemode : true — commande réelle et facturable
• livemode : false — environnement de test / commande test

Limites de débit

Le nombre de requêtes est limité par organisation. Le quota par défaut est de 120 requêtes par minute. Si cette valeur est dépassée, le résultat est 429 rate_limited; réessayez après une courte pause. Si votre intégration nécessite une limite plus élevée, contactez support@rapidtranslate.org.

Réponses

Chaque réponse réussie encapsule sa charge utile dans un données clé. Les points de terminaison de la liste ajoutent un méta bloc avec pagination.

Ressource unique

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

Liste paginée

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

Erreurs

Les erreurs utilisent les codes d'état HTTP standard et renvoient une réponse stable et lisible par machine code_d'erreur accompagné d'un message rédigé en français. Les erreurs de validation ajoutent un champ indexé par clé erreurs objet.

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

Statuts des commandes

La commande statut suit un cycle de vie stable. Ces cinq valeurs sont également celles adoptées par la statut filtrer par Liste des commandes:

Tant qu'une commande est en cours de traitement, des étiquettes plus détaillées (par exemple Attribué au traducteur, Traduire, Expédié) peuvent également apparaître. Lorsqu'une autorisation est requise, une commande peut indiquer brièvement paiement_échoué ou credit_hold si le prélèvement n'a pas pu être effectué, déterminer le mode de paiement et valider à nouveau.

Valeurs des champs

Les ensembles fixes acceptés lors de la création d'une commande.

Types de traduction

Redressement

Modes de livraison

Webhooks

Au lieu d'effectuer des requêtes régulières, configurez un point de terminaison Webhook pour recevoir les événements au fur et à mesure qu'ils se produisent. Définissez votre URL et consultez votre clé de signature dans « Paramètres de l'entreprise » → « Webhooks ». Les Webhooks sont très pratiques : les informations récupérées via un Webhook font toujours autorité.

Événements

Enveloppe

Chaque envoi est présenté dans la même enveloppe : une événement bloc (y compris livemode) et un élément spécifique à l'événement données bloc.

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

Les livraison_de_documents L'événement ajoute un documents tableau (chacun contenant nom, lien_de_téléchargement, version, statut) et un portail lien. Le avis_client L'événement ajoute une liste détaillée tarification bloc et un actions.approve objet contenant l'URL à appeler.

Vérification des signatures

Chaque requête est signée afin que vous puissiez vérifier qu’elle provient bien de RapidTranslate. Nous envoyons trois en-têtes :

Calculez la signature attendue en utilisant l'algorithme HMAC-SHA256 sur la chaîne de caractères « {timestamp}.{raw_request_body} » en utilisant votre clé secrète de signature du webhook, puis comparez-la à la valeur de l'en-tête :

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

Node.js (Express) — implémenter la route avec un analyseur de corps brut afin de conserver les octets exacts :

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

Il y a trois choses qui posent problème :

• Les X-RapidTranslate-Signature L'en-tête contient un sha256= préfixe. Soit comparer avec 'sha256=' + yourHmac (comme ci-dessus) ou supprimer le préfixe avant de comparer — ne comparez pas la valeur hexadécimale seule avec l'en-tête complet.
• Hachez le corps de la requête brute exactement tel qu’il a été reçu. La resérialisation du JSON analysé modifie les espaces et l’ordre des clés, ce qui empêche la signature de correspondre — lisez le corps avant que n’importe quel middleware JSON ne l’analyse.
• Comparer en temps constant (hash_equals / crypto.timingSafeEqual), jamais avec == ou ===.

Les {timestamp} fait partie de la chaîne signée ; il faut donc le lire dans l'en-tête et l'ajouter au début avant de procéder au hachage. Cela permet également de rejeter les envois périmés ou réutilisés — par exemple, tout horodatage datant de plus de cinq minutes.

Les livraisons ayant échoué font l'objet d'une nouvelle tentative avec un délai d'attente exponentiel (jusqu'à 5 tentatives). Répondre par un 2xx statut pour accuser réception.