Clés d'API et intégration

Clés d'API

Une clé d'API appartient à une organisation : elle ne voit que les templates de cette organisation, sans en-tête supplémentaire. Les clés sont gérées par les propriétaires et les administrateurs, dans Clés d'API.

Créer une clé

1. Cliquez sur Nouvelle clé.
2. Donnez un Nom qui identifie l'application (par exemple « ERP production »).
3. Choisissez l'Accès :
   • Rendu : lire les contrats et rendre des documents. C'est le bon choix pour une application.
   • Publication : en plus, créer des templates, enregistrer des brouillons et publier, pour publier des templates depuis un dépôt de code (« templates as code »).
4. Choisissez la Portée : la clé ne voit que les templates de ce dossier et de ses sous-dossiers ; Racine donne accès à toute l'organisation.
5. Facultatif : Expire dans (jours) (vide : pas d'expiration).
6. Facultatif, sous Limites : un débit propre (Requêtes au plus par fenêtre de (secondes)) et un Crédit de requêtes, éventuellement rechargé (Recharge de … tous les (jours)).
7. Cliquez sur Créer.

Le secret de la clé (Votre clé d'API) s'affiche une seule fois : copiez-le aussitôt dans le coffre de secrets de votre application. Il ne sera plus jamais affiché ; en cas de perte, faites une rotation.

Rotation et révocation

• Rotation : une nouvelle clé est créée avec les mêmes réglages et l'ancienne cesse de fonctionner immédiatement. Mettez à jour l'application aussitôt.
• Révoquer : les applications qui utilisent la clé sont refusées immédiatement. C'est définitif.

La liste indique pour chaque clé sa Dernière utilisation et son Expiration.

Appeler l'API

• URL de base : https://sculdoc.com/v1.
• Authentification : en-tête x-api-key avec le secret de la clé.
• Contrat complet de l'API (toutes les opérations, paramètres, réponses et erreurs) : https://sculdoc.com/v1/openapi.json.

Rendre un document

curl https://sculdoc.com/v1/renders \
	-H "x-api-key: $SCULDOC_API_KEY" \
	-H 'content-type: application/json' \
	-d '{"template":"facture-client","version":3,"data":{"customer":{"name":"Client Démo SARL"}}}' \
	-o facture.pdf

La réponse est le PDF. Avec l'en-tête Accept: application/json, elle décrit le rendu (identifiant, pages, manifeste) et donne un lien de téléchargement du document.

Le rendu synchrone est limité aux documents légers (10 secondes, 50 pages). Au-delà, ou pour de nombreux documents, utilisez les lots.

Lire le contrat d'une version

La documentation de chaque version, dans l'application, montre son contrat, ses jeux d'exemple et des exemples d'appels (onglets Contrat, Jeux d'exemple, Appels, Polices). Le JSON Schema est dans l'onglet Contrat de données de la page de la version.

SDK et CLI

Des clients existent pour TypeScript, Java, C# et Python. En TypeScript :

pnpm add @supscale/sculdoc-client

import { SculdocClient } from '@supscale/sculdoc-client';

const client = new SculdocClient({ baseUrl: 'https://sculdoc.com', apiKey: process.env.SCULDOC_API_KEY ?? '' });
const pdf = await client.render({ template: 'facture-client', version: 3, data });

Pour la production, générez plutôt le SDK d'une version avec la CLI sculdoc : il contient les types du contrat de la version épinglée et une fonction de rendu qui fixe template et version. Des données hors contrat deviennent alors une erreur de compilation.

sculdoc login --url https://sculdoc.com --key sk_…
sculdoc sdk generate --template facture-client@3 --lang ts --out sdk/   # ou java, csharp, python

La CLI sait aussi vérifier et publier des templates depuis un dépôt de code (« templates as code »), avec une clé d'accès Publication portée au dossier des templates ; une action GitHub (Supscale/sculdoc-publish-template) le fait sur chaque pull request et sur la branche principale.

Versions épinglées ou latest

Une version publiée ne change jamais : même numéro et mêmes données donnent le même document. latest désigne la plus haute version publiée et change à chaque publication.

• En production, indiquez toujours un numéro. Un appel par clé d'API qui demande latest, ou n'indique pas de version, reçoit l'avertissement version.latest (en-têtes x-sculdoc-warning et x-sculdoc-version-resolved). Une organisation peut interdire ces appels (erreur 422 version.unpinned).
• Monter de version : lisez le changelog et la comparaison des versions, en particulier les changements cassants du contrat, puis changez le numéro (et régénérez le SDK).
• Une version dépréciée reste rendable par son numéro ; une version archivée répond 410.

Lots et rendus asynchrones

Pour des documents lourds ou nombreux : POST /v1/jobs, avec 1 à 1 000 documents d'un même template (dans la limite fixée pour votre organisation). Chaque document est validé contre le contrat dès la soumission.

• Sortie : une archive ZIP (zip), un PDF fusionné (merged) ou des documents séparés (separate).
• Suivi : interrogez GET /v1/jobs/{id}, ou indiquez un callbackUrl pour être notifié à la fin (voir Webhooks).
• Les jobs apparaissent dans Rendus, onglet Jobs, avec leur progression et leurs documents.

Idempotence

Ajoutez un en-tête Idempotency-Key (une valeur unique par opération) aux rendus et aux jobs. Pendant 24 heures, un nouvel envoi avec la même clé renvoie la première réponse au lieu de rendre à nouveau : vous pouvez réessayer sans risque après une coupure réseau. La même clé avec un autre contenu est refusée (409 idempotency.mismatch).

Erreurs

Toutes les erreurs ont la même forme : un code stable, un message, la liste des champs en cause (chemins JSON) et un identifiant de requête à citer au support.

{
	"error": {
		"code": "data.invalid",
		"message": "data does not match the contract of facture-client v3",
		"issues": [{ "path": "$.customer.name", "message": "required" }]
	},
	"requestId": "01JD…"
}

Réessayez après un 429, une erreur réseau ou une erreur 5xx, avec la même clé d'idempotence. Ne réessayez pas tel quel après un 400, 403, 404, 410 ou 422.