Documentation de l’API REST

API REST conv2pdf : convertissez, fusionnez, découpez, compressez, protégez et numérotez vos PDF depuis votre application — 14 outils exposés via 5 endpoints REST. Hébergement en France, RGPD respecté. Aucun service américain n’intervient dans le processus.

Démarrage rapide

1. Créez un compte (gratuit, magic link par email)
2. Depuis votre tableau de bord, créez une clé API (plan Dev gratuit, 300 conversions offertes pour tester, valables 12 mois, sans renouvellement)
3. Authentifiez vos appels avec l’en-tête Authorization: Bearer cpdf_live_…

Base URL

https://api.conv2pdf.com/v1

SDK, OpenAPI & Postman

• SDK PHP officiel : composer require conv2pdf/php (repo et exemples).
• Spécification OpenAPI 3.0 (JSON) — pour générer un client dans un autre langage, l'importer dans un outil (Swagger, Insomnia…) ou alimenter un agent.
• Collection Postman — importez-la, renseignez votre clé, convertissez un PDF en une minute.

Authentification

Chaque requête doit inclure l’en-tête HTTP Authorization: Bearer <votre_clé>. Une clé révoquée ou inexistante renvoie un code 401. Un quota dépassé renvoie 429 avec les détails de réinitialisation.

Endpoints

GET /v1/tools

Renvoie la liste des outils disponibles, leurs limites et formats acceptés.

curl https://api.conv2pdf.com/v1/tools \
  -H "Authorization: Bearer cpdf_live_..."

POST /v1/convert/:tool

Effectue une conversion. Les fichiers sont envoyés en multipart/form-data.

14 outils disponibles. La liste machine à jour (formats acceptés, bornes de fichiers) est renvoyée par GET /v1/tools.

Paramètres optionnels (champs form-data) :

• split-pdf : ranges requis (ex : 1-5,7,10-12)
• compress-pdf : quality (low, medium par défaut, high)
• protect-pdf : password requis (4 à 64 caractères) ; optionnels prevent_print=on, prevent_copy=on
• unlock-pdf : password requis (mot de passe actuel du PDF, à retirer)
• rotate-pdf : rotation requis (90, 180 ou 270)
• watermark-pdf : text requis (texte du filigrane)
• pdf-to-image : format (png par défaut ou jpg)
• page-numbers-pdf : position (bottom-center par défaut, bottom-left, bottom-right) ; format=simple pour le numéro seul (sans total)

Exemple : Image → PDF (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/image-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@photo.jpg"

Exemple : Fusion PDF (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/merge-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@doc1.pdf" \
  -F "file=@doc2.pdf" \
  -F "file=@doc3.pdf"

Exemple : Compression (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/compress-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@gros.pdf" \
  -F "quality=medium"

Exemple : PDF → Word (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/pdf-to-word \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@rapport.pdf"

Renvoie un fichier .docx éditable. Un PDF scanné (sans couche texte) renvoie 422 pdf_scanned_needs_ocr : l'OCR existe pour les comptes Premium, sur le site uniquement, et n'est pas exposé par l'API ; au-delà de 500 pages, 422 pdf_too_many_pages.

Exemple : PDF → Image (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/pdf-to-image \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@rapport.pdf" \
  -F "format=png"

Rend chaque page en image à 150 DPI et renvoie une archive .zip (une image par page). Champ format : png (défaut) ou jpg. Au-delà de 100 pages, 422 too_many_pages ; si le résultat dépasse la taille maximale, 422 output_too_large.

Exemple : Protection par mot de passe (curl)

curl -X POST https://api.conv2pdf.com/v1/convert/protect-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@confidentiel.pdf" \
  -F "password=secret123" \
  -F "prevent_print=on" \
  -F "prevent_copy=on"

Chiffrement AES-256. Le PDF généré demandera le mot de passe à l’ouverture et appliquera les restrictions cochées.

Réponse en cas de succès

L’objet quota n’est présent que pour les appels authentifiés par clé API.

{
  "job_id": "abc123…",
  "status": "success",
  "download_url": "/v1/download/abc123…",
  "size_bytes": 124533,
  "quota": {
    "plan": "starter",
    "quota": 1000,
    "used": 42,
    "soft_cap_limit": 1100,
    "status": "ok",
    "period_end": 1715789012345
  }
}

GET /v1/download/:jobId

Télécharge le fichier converti. Le fichier est servi avec son type MIME (application/pdf, le format DOCX pour PDF → Word, ou application/zip pour PDF → Image) et Cache-Control: no-store. Disponible une heure après la conversion.

curl https://api.conv2pdf.com/v1/download/abc123… \
  -H "Authorization: Bearer cpdf_live_..." \
  -o sortie.pdf

GET /v1/job/:jobId

Renvoie le statut et les métadonnées d’un job (status, taille, dates). Pratique pour vérifier qu’une conversion est prête avant de la télécharger.

curl https://api.conv2pdf.com/v1/job/abc123… \
  -H "Authorization: Bearer cpdf_live_..."

DELETE /v1/job/:jobId

Supprime immédiatement un job et son fichier, sans attendre l’expiration automatique (1 h).

curl -X DELETE https://api.conv2pdf.com/v1/job/abc123… \
  -H "Authorization: Bearer cpdf_live_..."

Exemples : Node.js

import { readFile } from 'node:fs/promises';

const file = await readFile('./photo.jpg');
const formData = new FormData();
formData.append('file', new Blob([file]), 'photo.jpg');

const res = await fetch('https://api.conv2pdf.com/v1/convert/image-to-pdf', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer cpdf_live_...' },
  body: formData
});
const data = await res.json();
console.log(data.download_url);

Exemples : Python

import requests

with open('photo.jpg', 'rb') as f:
    r = requests.post(
        'https://api.conv2pdf.com/v1/convert/image-to-pdf',
        headers={'Authorization': 'Bearer cpdf_live_...'},
        files={'file': f}
    )
print(r.json()['download_url'])

Exemples : PHP

SDK officiel (recommandé)

Installez le SDK : composer require conv2pdf/php. Voir le repo et ses exemples.

use Conv2pdf\Conv2pdf;

$c = new Conv2pdf('cpdf_live_...');
$job = $c->convert('image-to-pdf', 'photo.jpg');
$c->download($job['download_url'], 'photo.pdf');

Sans dépendance (requête brute)

$ch = curl_init('https://api.conv2pdf.com/v1/convert/image-to-pdf');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer cpdf_live_...'],
  CURLOPT_POSTFIELDS => ['file' => new CURLFile('photo.jpg')],
]);
$data = json_decode(curl_exec($ch), true);
echo $data['download_url'];

Codes d’erreur

Toute réponse d’erreur porte un champ error : un code stable, sur lequel brancher du code. Les champs supplémentaires listés ci-dessous disent quoi corriger. Les refus à l’entrée (upload, plan, contenu) portent aussi plan ; les erreurs survenues pendant la conversion portent job_id et status (rejected pour un verdict sur le fichier, failed pour une panne).

Quotas et réinitialisation

Chaque compte a un quota selon son plan (voir tarifs API), partagé par toutes ses clés. Sur les plans payants, le quota est mensuel et se réinitialise à chaque échéance anniversaire (et non au 1^er du mois) : le timestamp de la prochaine remise à zéro est renvoyé dans quota_period_end, et le compteur used repart de zéro. Sur le plan Dev, les 300 conversions offertes à l’inscription sont valables 12 mois depuis leur octroi (credits_expire_at) et ne se renouvellent pas (quota_period_end à null, comme period_end : un essai n’est pas facturé). Un email vous prévient à 80 % du quota puis à épuisement, sur tous les plans, et 30 jours avant l’expiration des crédits d’essai. Un léger dépassement est toléré (soft_cap_limit, +10 %) avant le blocage en 429.

Confidentialité

Aucun fichier (entrée ou sortie) n’est conservé au-delà d’une heure : cette API n’a aucune exception à cette règle. Une seule chose peut prolonger la vie d’un fichier, et elle passe par le site : depuis le tableau de bord, le titulaire du compte peut créer un lien de partage pour un job — y compris produit par l’API — auquel cas la copie partagée vit jusqu’à l’échéance du lien (sept jours au plus en Gratuit, trente en Premium) ou jusqu’à sa révocation. Aucun résultat n’est mis en cache. L’intégralité du traitement a lieu sur des serveurs en France (OVH Gravelines). Voir notre politique de confidentialité pour le détail.

Support

Pour toute question technique, utilisez notre formulaire de contact (sujet « Question technique »). Plans Business et Sur-mesure : support prioritaire avec SLA contractuel.