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/mois pour démarrer)
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

Quotas et réinitialisation

Chaque clé API a un quota mensuel selon son plan (voir tarifs). Le quota se réinitialise à chaque échéance anniversaire mensuelle (et non au 1^er du mois) : le timestamp de la prochaine remise à zéro est renvoyé dans period_end, et le compteur used repart de zéro. 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. 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.