Documentation API

API VULKO

Connectez VULKO à Salesforce, HubSpot, Pipedrive, votre ERP ou votre tableau de bord interne. VULKO prévient votre outil en temps réel quand un devis est accepté, et cette API vous en livre le détail ligne par ligne. Réservée au plan Équipe.

1. Obtenir une clé API

Souscrivez au plan Équipe depuis /tarifs
Allez dans Paramètres → Connexion avec vos outils
Cliquez sur Générer une clé de connexion
Copiez la clé immédiatement — elle ne sera plus jamais affichée

2. Authentification

Toutes les requêtes nécessitent un en-tête HTTP Authorization: Bearer VOTRE_CLE. Sans clé valide ou si le plan n'est pas Équipe, l'API renvoie 401 ou 403.

Les clés inactives depuis plus de 90 jours sont automatiquement révoquées — pensez à les rafraîchir.

3. Limites

30 requêtes par minute par clé API (réponse 429 avec en-tête Retry-After sinon)
Pagination : limit max 100, défaut 50
Toutes les réponses sont au format JSON UTF-8
since attend un instant complet avec heure et fuseau (2026-08-19T12:00:00Z). Une date seule est refusée : elle serait lue à minuit UTC et décalerait la fenêtre de votre décalage horaire. Le filtre porte sur la date de dernière modification, pas de création — un devis corrigé après coup ressort donc bien.
Les lignes de devis et de facture exposent ce que votre client voit sur le document : description, quantité, unité, prix unitaire, total HT, taux de TVA, lot et section. Vos coûts internes (main d'œuvre, matériaux), vos notes privées et le nom de vos sous-traitants ne sortent jamais par l'API — même si l'outil connecté les demande.

4. Endpoints

GET/quotes

Liste les devis de votre entreprise. Filtres : status (DRAFT/SENT/ACCEPTED/REJECTED/EXPIRED), limit (1-100, défaut 50), offset (défaut 0). Ajoutez include=lines pour obtenir le détail ligne par ligne de chaque devis — omis par défaut, car la réponse devient nettement plus volumineuse. Ajoutez since=<instant ISO 8601> pour ne recevoir que les devis modifiés depuis cette date : c'est le moyen de rattraper une notification manquée sans reparcourir tout l'historique.

curl -H "Authorization: Bearer VOTRE_CLE" \
     "https://vulko.fr/api/v1/quotes?since=2026-08-19T00:00:00Z&include=lines"

PATCH/quotes/:id

Inscrit VOTRE identifiant sur un devis, via le champ externalId — et rien d'autre : toute autre propriété est refusée. C'est ce qui vous permet de distinguer un devis déjà synchronisé d'un devis à traiter, après un incident ou une relivraison. Envoyez null pour délier.

curl -X PATCH      -H "Authorization: Bearer VOTRE_CLE"      -H "Content-Type: application/json"      -d '{"externalId":"0Q0xx0000004C92"}'      https://vulko.fr/api/v1/quotes/QUOTE_ID

GET/quotes/:id

Récupère un devis unique, TOUJOURS avec ses lignes (description, quantité, unité, prix unitaire, total HT, taux de TVA, lot et section), la devise, le taux de retenue de garantie, et un bloc signature (date, signataire, texte accepté, empreinte de preuve). C'est l'endpoint à appeler à la réception d'un webhook quote.* pour obtenir le détail complet.

curl -H "Authorization: Bearer VOTRE_CLE" \
     "https://vulko.fr/api/v1/quotes/QUOTE_ID"

GET/quotes/:id/document

Renvoie une URL signée (valable 5 minutes) vers le PDF FIGÉ du devis — la copie produite à l'envoi ou à la signature, pas un rendu recalculé. Un devis encore en brouillon n'en a pas : la réponse est alors un 409 explicite, pas une erreur serveur.

curl -H "Authorization: Bearer VOTRE_CLE"      "https://vulko.fr/api/v1/quotes/QUOTE_ID/document?type=pdf"

GET/invoices

Liste les factures. Mêmes filtres que /quotes — include=lines et since compris. Inclut le statut (DRAFT/SENT/PAID/OVERDUE/CANCELED).

curl -H "Authorization: Bearer VOTRE_CLE" \
     "https://vulko.fr/api/v1/invoices?status=PAID"

GET/invoices/:id

Récupère une facture unique avec ses lignes, sur le même principe que /quotes/:id.

curl -H "Authorization: Bearer VOTRE_CLE" \
     "https://vulko.fr/api/v1/invoices/INVOICE_ID"

GET/clients

Liste les clients. Recherche par q (nom, email ou ville), pagination via limit + offset, since pour ne recevoir que les fiches modifiées depuis un instant donné, et externalId pour retrouver une fiche par l'identifiant de votre propre système.

curl -H "Authorization: Bearer VOTRE_CLE" \
     "https://vulko.fr/api/v1/clients?q=dupont"

POST/clients

Crée un nouveau client. Champ obligatoire : name. Optionnels : email, phone, address, city, zipCode, type (PARTICULIER ou PROFESSIONNEL), notes, externalId. IDEMPOTENT si vous fournissez externalId : un identifiant déjà connu renvoie la fiche existante avec le code 200 au lieu d'en créer une seconde, et 201 signale une vraie création. Rejouer un appel est donc sans danger.

curl -X POST \
     -H "Authorization: Bearer VOTRE_CLE" \
     -H "Content-Type: application/json" \
     -d '{"name":"SARL Dupont","email":"contact@dupont.fr","type":"PROFESSIONNEL","externalId":"0011t00000XYZ"}' \
     https://vulko.fr/api/v1/clients

5. Format des erreurs

{
  "error": {
    "code": "validation_error",
    "message": "Le nom du client est requis."
  }
}

Codes possibles : unauthorized (401), plan_required (403), validation_error (400), bad_request (400), not_found (404), conflict (409), document_unavailable (409), storage_unavailable (503), server_error (500).

Le 429 de dépassement de quota fait exception : il ne passe pas par cette enveloppe et renvoie { "code": "TOO_MANY_REQUESTS", "message": … } à plat. Traitez-le sur le code HTTP, pas sur le corps.

Besoin d'aide d'intégration ? Transmettez ce lien à votre prestataire informatique. Pour un accompagnement personnalisé, contactez contact@vulko.fr.

Prêt à essayer VULKO ?

14 jours gratuits, sans engagement.

Commencer gratuitement