Connecter PeppolKit par l'API

Votre boutique tourne sur votre propre système, ou sur une plateforme pour laquelle nous n'avons pas d'extension ? Envoyez chaque commande payée à l'API. PeppolKit établit la facture, l'envoie par e-mail à votre client et la transmet via Peppol.

Commencer gratuitement Comment ça marche

Ce qu'il vous faut

• Un compte. Créez-le gratuitement sur la page de démarrage et choisissez Autre système (API). Vous recevez un lien de connexion par e-mail ; il n'y a pas de mot de passe.
• Les coordonnées de votre entreprise. Complétez-les dans le tableau de bord sous Réglages : nom, adresse, numéro de TVA et numéro d'entreprise. Sans elles, l'API refuse une commande.
• Une clé. Dans le tableau de bord, allez dans API et cliquez sur Créer une clé. Vous ne la voyez qu'une fois. Conservez-la sur votre serveur, comme un mot de passe.

Comment appeler l'API

Tous les appels vont vers https://app.peppolkit.com/api/v1, en https, avec votre clé dans l'en-tête Authorization. Vous envoyez et recevez du JSON. Un premier test :

curl https://app.peppolkit.com/api/v1/settings \
  -H "Authorization: Bearer pk_your_key"

En cas d'erreur, vous recevez un code et un champ error avec la raison :

• 401 la clé manque ou est incorrecte.
• 409 les coordonnées de votre entreprise ne sont pas encore complétées.
• 422 la commande ou le remboursement n'est pas valide ; issues indique par champ ce qui ne va pas.
• 402 la limite de votre formule est atteinte. La commande attend et reçoit sa facture après un changement de formule ou au début du mois suivant.

Envoyer une commande

Envoyez une commande dès qu'elle est payée, avec POST /orders. La structure est celle d'une commande Shopify, pour que le code et les exemples existants soient réutilisables. Enregistrez ceci sous order.json :

{
  "id": 1042,
  "name": "#1042",
  "currency": "EUR",
  "taxes_included": true,
  "created_at": "2026-11-13T10:15:00+01:00",
  "email": "inkoop@klant.be",
  "billing_address": {
    "name": "An Peeters",
    "company": "Klant BV",
    "address1": "Kerkstraat 1",
    "zip": "9000",
    "city": "Gent",
    "country_code": "BE"
  },
  "line_items": [
    {
      "id": 1,
      "title": "Kettingset 11-speed",
      "sku": "KS-11",
      "quantity": 2,
      "price": "39.00",
      "tax_lines": [{ "rate": 0.21, "price": "13.54" }]
    }
  ],
  "shipping_lines": [
    { "title": "Verzending", "price": "6.95", "tax_lines": [{ "rate": 0.21, "price": "1.21" }] }
  ],
  "note_attributes": [{ "name": "VAT number", "value": "BE0123456749" }],
  "total_price": "84.95"
}

Et envoyez-le :

curl -X POST https://app.peppolkit.com/api/v1/orders \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d @order.json

Les champs

• id le numéro de la commande dans votre système, un nombre entier. Renvoyer le même id ne crée pas de deuxième facture : vous recevez l'existante avec status: "exists".
• name le numéro de commande tel que votre client le voit, par exemple #1042.
• currency trois lettres, par exemple EUR.
• taxes_included true si les prix sont TVA comprise, false s'ils sont hors TVA.
• created_at date et heure de la commande (ISO 8601).
• email l'adresse à laquelle la facture est envoyée.
• billing_address nom, société, adresse, code postal, ville et pays (country_code, deux lettres). shipping_address peut s'ajouter, sous la même forme.
• line_items au moins une ligne, avec id, title, quantity, le prix unitaire price et la TVA de toute la ligne dans tax_lines (rate en fraction : 0.21 vaut 21 %). Une remise sur une ligne se transmet dans discount_allocations, sous la forme [{"amount": "5.00"}].
• shipping_lines les frais de livraison, sous la même forme.
• note_attributes le numéro de TVA d'un client professionnel, sous le nom VAT number. Avec ce numéro, la facture devient une facture professionnelle.
• total_price le total payé par le client.

Les montants sont du texte avec un point comme séparateur décimal ("39.00"), jamais un nombre arrondi. Les champs que PeppolKit ne connaît pas sont ignorés.

La réponse contient la facture, avec des liens vers le pdf et le fichier UBL valables 30 jours. Le numéro de TVA de cet exemple n'existe pas ; si vous l'envoyez tel quel, warnings indique que VIES ne le connaît pas.

{
  "ok": true,
  "status": "issued",
  "warnings": [],
  "invoice": {
    "number": "2026-00042",
    "type": "invoice",
    "orderId": "1042",
    "issueDate": "2026-11-13",
    "total": 84.95,
    "currency": "EUR",
    "peppolStatus": "sent",
    "emailedAt": "2026-11-13T09:15:04.000Z",
    "emailTo": "inkoop@klant.be",
    "emailError": null,
    "pdfUrl": "https://app.peppolkit.com/i/…",
    "ublUrl": "https://app.peppolkit.com/i/…?format=xml",
    "warnings": []
  }
}

TVA et Peppol

PeppolKit détermine, à partir du pays du client, du numéro de TVA et de vos réglages, comment la facture est établie : TVA normale, autoliquidation ou OSS. Le numéro de TVA est vérifié dans VIES. Si le résultat diffère de ce que votre boutique a calculé, ou si le numéro n'est pas valide, vous le lisez dans warnings. Si votre client a une adresse Peppol et que l'envoi est activé, la facture part aussi via Peppol ; peppolStatus indique le résultat (sent, pending, not_on_peppol ou failed) ; si la facture n'est pas partie via Peppol, le champ est vide (null).

Envoyer un remboursement

Si vous remboursez un client, envoyez-le avec POST /refunds. PeppolKit établit une note de crédit liée à la facture de cette commande. line_item_id renvoie à l'id de la ligne dans la commande ; le montant remboursé figure dans transactions.

curl -X POST https://app.peppolkit.com/api/v1/refunds \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "refund": {
      "id": 7001,
      "order_id": 1042,
      "created_at": "2026-11-20T14:00:00+01:00",
      "refund_line_items": [{ "line_item_id": 1, "quantity": 1 }],
      "transactions": [{ "kind": "refund", "status": "success", "amount": "39.00" }]
    }
  }'

Renvoyer le même id ne crée pas de deuxième note de crédit. S'il n'y a pas de facture pour la commande, vous recevez 404.

Récupérer les factures

Avec GET /invoices?orderId=…, vous recevez la facture et les notes de crédit d'une commande. Sans orderId, vous recevez les 50 derniers documents. Avec lang (nl, fr ou en), vous choisissez la langue des avertissements. La réponse est {"invoices": […]}, avec pour chaque document les mêmes champs que ci-dessus ; type vaut invoice ou credit_note.

curl "https://app.peppolkit.com/api/v1/invoices?orderId=1042&lang=en" \
  -H "Authorization: Bearer pk_your_key"

Les coordonnées de l'entreprise par l'API

Les réglages du tableau de bord peuvent aussi être lus (GET /settings) et écrits (PUT /settings) par l'API. Pratique si vous connectez plusieurs boutiques.

curl -X PUT https://app.peppolkit.com/api/v1/settings \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Velo Atelier BV",
    "street": "Dorpsstraat 1",
    "postalCode": "9000",
    "city": "Gent",
    "country": "BE",
    "vatNumber": "BE0123456749",
    "registrationNumber": "0123456749",
    "email": "info@veloatelier.be",
    "language": "auto",
    "emailCustomers": true,
    "peppolSend": true
  }'

Tester d'abord

Vous voulez essayer sans que rien ne parte sur le vrai réseau Peppol ? Créez un deuxième compte avec une adresse qui se termine par .test, par exemple maboutique.test. Un tel compte établit de vraies factures et de vrais pdf, mais n'envoie jamais via Peppol. Désactivez aussi dans les réglages Envoyer automatiquement la facture au client par e-mail, ou utilisez votre propre adresse e-mail dans les commandes de test.

Questions fréquentes

PeppolKit par plateforme : Shopify, WooCommerce, PrestaShop, Magento, Drupal Commerce, OpenCart, Shopware, Joomla, bol.com, Lightspeed, CCV Shop, Wix et Stripe. Voyez comment cela fonctionne pour votre boutique.

Explication à titre d'orientation, pas un conseil fiscal.