Documentation API

Intégrez la conversion PDF → Factur-X dans vos applications, ERP et logiciels comptables.

Clés live réservées aux abonnements Pro et Business (1 crédit par conversion). Clés de test sk_test_ disponibles pour tout compte vérifié.

URL de base

https://api.pont-facturx.com

Tous les endpoints ci-dessous sont préfixés par cette URL, par exemple https://api.pont-facturx.com/v1/convert.

Spécification OpenAPI

Collection Postman : importez la spec OpenAPI (Postman → Import → Link → https://www.pont-facturx.com/openapi.json). Elle sert aussi à générer un client dans votre langage.

Exemples copiables : curl, Python, TypeScript, PHP

Accès réservé Pro & Business

Pour utiliser l'API en production (clés sk_live_), votre compte doit disposer d'un abonnement Pro ou Business actif. Tout compte vérifié peut créer des clés de test sk_test_ pour évaluer l'API gratuitement. Gérez vos clés API depuis Réglages → API.

Démarrage rapide

1. Obtenir une clé API

Depuis votre espace client, allez dans Réglages → API et créez une clé. Elle est affichée une seule fois — conservez-la précieusement.

# Format de votre clé API
sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Vérifier vos crédits disponibles

Avant de convertir, vérifiez votre solde de crédits et le statut de votre compte.

curl https://api.pont-facturx.com/v1/account/usage \
  -H "Authorization: Bearer sk_live_..."

{
  "plan": "Abonnement Pro",
  "subscription_status": "active",
  "credits_available": 187,
  "free_remaining": 0,
  "subscription_remaining": 187,
  "paid_credits": 0,
  "rate_limit": "30 requests/minute"
}

3. Convertir un PDF en Factur-X

Un seul appel suffit. L'OCR est lancé automatiquement si vous n'envoyez pas invoice_data.

curl -X POST https://api.pont-facturx.com/v1/convert \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@facture.pdf" \
  -F "profile=BASIC_WL" \
  --output facture_facturx.pdf

Paramètre	Type	Description
file	multipart *requis	Fichier PDF à convertir
profile	string	MINIMUM, BASIC_WL (défaut), EN16931
invoice_data	JSON string	Données de la facture — si absent, OCR automatique

Clés de test (sk_test_)

Évaluez l'API sans abonnement : tout compte avec e-mail vérifié peut créer jusqu'à 2 clés sk_test_ depuis Réglages → API. Les clés de test utilisent exactement le même moteur que les clés live — le document Factur-X produit est identique et jamais altéré.

• Zéro crédit consommé — quotas : 5 requêtes/jour, 25/mois, 10/minute.
• Réponses marquées : en-tête X-Livemode: false et champs livemode: false, environment: "test", transmission_allowed: false dans les réponses JSON.
• Aucune conservation — fichiers supprimés immédiatement, aucun historique de conversion.
• Transmission interdite — Chorus Pro / PDP refusent une clé de test (403 transmission_forbidden_in_test_mode).
• L'en-tête Idempotency-Key est ignoré (rien n'est débité).

curl -X POST https://api.pont-facturx.com/v1/convert \
  -H "Authorization: Bearer sk_test_..." \
  -F "file=@facture.pdf" \
  --output facture_facturx.pdf

Dépassement de quota : 429 avec le code test_quota_exceeded. Passez à une clé sk_live_ pour la production.

Référence des endpoints

Tous les endpoints utilisent le même header d'authentification :
Authorization: Bearer sk_live_...

Conversion

POST/v1/extract0 crédit

OCR seulement — retourne le JSON extrait du PDF (invoice_data + raw). Utile pour vérifier/corriger avant de convertir. Ne consomme pas de crédit.

POST/v1/convert1 crédit

PDF → Factur-X. Retourne directement le PDF final en application/pdf. Passe invoice_data pour sauter l'OCR.

Validation

POST/v1/validate0 crédit

Valide un PDF Factur-X ou un XML CII brut (multipart file) : profil détecté, validation XSD, règles EN 16931 (Schematron), conteneur PDF/A. Réponse JSON structurée (valid, checks, errors). Stateless : le fichier n'est pas conservé. Aussi disponible sans compte via le validateur en ligne gratuit.

Historique

GET/v1/conversions

Liste vos 500 dernières conversions triées par date décroissante.

GET/v1/conversions/{id}

Détail d'une conversion spécifique par ID (statut, fichier, montant, SIRET…).

GET/v1/conversions/{id}/download/{kind}

Télécharge le fichier d'une conversion. kind : pdf (Factur-X) ou xml (CII brut).

Transmission Chorus Pro / PDP

POST/v1/conversions/{id}/send-pdp

Transmission Chorus Pro (bêta, pilote privé). Body JSON avec destination et recipient_siret.

GET/v1/conversions/{id}/pdp-status

Statut de la transmission Chorus Pro (bêta, pilote privé). Ajoutez ?sync=true pour déclencher une synchronisation manuelle du statut.

Compte

GET/v1/account/usage

Plan actif, crédits disponibles (free / abonnement / payés) et limite de taux.

GET/v1/auth/api-keys

Liste vos clés API actives (préfixe, date de création, dernière utilisation).

DELETE/v1/auth/api-keys/{id}

Révoque une clé API. Action immédiate et irréversible. Retourne 204 No Content.

Clés API sécurisées

Créez jusqu'à 5 clés révocables depuis votre dashboard. Chaque clé est préfixée sk_live_ et stockée hashée — visible une seule fois à la création.

Rate Limiting

30 requêtes/minute sur /v1/convert. En cas de dépassement, l'API retourne un 429 avec un header Retry-After.

Historique accessible

Listez et re-téléchargez vos conversions passées via /v1/conversions — PDF Factur-X ou XML CII brut.

Webhooks (bientôt)

Notifications en temps réel pour les conversions terminées.

Codes d'erreur

401

Clé API invalide ou manquante

{"code": "invalid_api_key", "message": "Clé API invalide ou révoquée."}

402

Crédits épuisés

{"code": "no_credits", "message": "Aucun crédit disponible. Rechargez votre compte."}

403

Abonnement inactif ou plan insuffisant

{"code": "premium_required", "message": "L'accès API est réservé aux abonnements Pro et Business."}

403

Transmission avec une clé de test

{"code": "transmission_forbidden_in_test_mode", "message": "La transmission externe est interdite avec une clé sk_test_."}

429

Rate limit dépassé

Header Retry-After inclus dans la réponse.

429

Quota du mode test atteint

{"code": "test_quota_exceeded", "message": "Quota du mode test atteint (5 requêtes/jour, 25/mois)."}

500

Erreur serveur

Réessayez ou contactez le support.

Besoin d'aide pour votre intégration ?

Notre équipe est là pour vous accompagner