API Novadesko v1 — Documentation

Introduction

L'API Novadesko vous permet d'accéder à toutes vos données depuis n'importe quelle application externe — site web, ERP, outil de reporting, e-commerce…

Base URL : https://api.novadesko.com/api
Routes v1 (privées) : https://api.novadesko.com/api/v1/...
Toutes les réponses sont en JSON UTF-8.

# Exemple rapide — données publiques shop
curl https://api.novadesko.com/api/shops/{slug}/export

# Exemple v1 avec token
curl https://api.novadesko.com/api/v1/documents/invoices \
  -H "Authorization: Bearer {token}"

Authentification

Les endpoints v1 nécessitent un Bearer Token obtenu via POST /api/sanctum/token. Les endpoints publics (shop export, blog) ne nécessitent pas de token.

POST /api/sanctum/token Obtenir un token

Body (JSON)

Champ	Type	Requis	Description
`email`	string	✓	Email du compte Novadesko
`password`	string	✓	Mot de passe
`device_name`	string	–	Identifiant de l'application (ex: "mon-site-web")

// Réponse 200
{
  "token": "1|abc123xyz...",
  "user": { "id": 42, "email": "you@shop.be", "default_shop_id": 78 }
}

Utilisez ce token dans chaque requête : Authorization: Bearer {token}
Toutes les données v1 sont filtrées automatiquement par votre shop.

Base URL & Headers

# Base URL
https://api.novadesko.com/api

# Headers obligatoires
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}  // endpoints v1 uniquement

Shop / Vitrine (public)

Endpoint public pour alimenter votre site vitrine. Aucun token requis.

GET /api/shops/{slug}/export Données complètes du shop

Retourne : infos générales, horaires, réseaux sociaux, produits, catégories. Le shop doit avoir website_enabled = true.

{
  "id": 78, "name": "Mon Shop", "slug": "mon-shop",
  "email": "contact@shop.be", "phone": "+32 65 00 00 00",
  "address": "Rue du Commerce 1, 7000 Mons",
  "logo": "https://web.novadesko.com/storage/logos/...",
  "hours": [{ "day": "monday", "open": "09:00", "close": "18:00", "closed": false }],
  "social_medias": [{ "type": "instagram", "url": "https://instagram.com/..." }],
  "products": [ ... ],
  "product_categories": [ ... ]
}

Blog (public)

GET /api/blog/posts Liste des articles

Query params

Param	Description
`lang`	Langue : `fr`, `nl`, `en`
`per_page`	Résultats par page
`category`	Slug de catégorie

GET /api/blog/posts/{slug} Détail d'un article

{ "id": 42, "title": "Peppol Belgique 2026", "slug": "peppol-belgique-2026",
  "content": "<p>...</p>", "image_url": "https://...",
  "published_at": "2026-03-15" }

Me — Mon shop

Informations de l'utilisateur et du shop associé au token.

GET /api/v1/me Auth Profil utilisateur + shop

{
  "user": { "id": 42, "email": "you@shop.be", "first_name": "Anthony" },
  "shop": { "id": 78, "name": "Mon Shop", "slug": "mon-shop",
    "email": "contact@shop.be", "phone": "+32 65 00 00 00" }
}

Documents

Accédez à vos documents par type. La numérotation est automatique — ne fournissez jamais de numéro.

Slugs disponibles :

invoices quotes credit-notes orders delivery-notes purchases

Récupérez la liste complète via GET /api/v1/document-types

Auth requise. Toutes les données sont filtrées par votre shop — vous ne voyez que vos propres documents.

GET /api/v1/documents/{slug} Auth Liste des documents

Query params

Param	Type	Description
`per_page`	int	Résultats par page (défaut: 25, max: 100)
`page`	int	Page (défaut: 1)
`status`	string	Filtrer par statut
`search`	string	Recherche par numéro, client…

{
  "type": "invoices",
  "count": 148,
  "documents": {
    "data": [{
      "id": 1234, "number": "FAC-2026-0042",
      "date": "2026-03-15", "due_date": "2026-04-15",
      "total_excl_tax": 826.45, "total_incl_tax": 999.99,
      "customer": { "id": 56, "name": "ACME SRL" },
      "status": { "name": "Envoyée", "color": "green" },
      "documentLines": [ // toujours inclus
        { "description": "Dev web", "qty": 1, "unit_price": 826.45, "tax_rate": 21 }
      ],
      "transactions": [ // paiements liés
        { "amount": 999.99, "date": "2026-03-20" }
      ]
    }],
    "total": 148, "current_page": 1
  }
}

GET /api/v1/documents/{slug}/{id} Auth Détail complet

Retourne le document avec toutes les lignes, le client/fournisseur complet, les transactions et les attributs.

POST /api/v1/documents/{slug} Auth Créer un document (numérotation auto)

Ne fournissez jamais de numéro de document. Novadesko attribue automatiquement le prochain numéro selon la séquence configurée.

Body (JSON)

Champ	Type	Requis	Description
`customer_id`	int	✓	ID du client
`date`	date	✓	YYYY-MM-DD
`due_date`	date	–	Date d'échéance
`notes`	string	–	Notes internes
`lines`	array	✓	Lignes du document

Structure d'une ligne

Champ	Type	Requis	Description
`description`	string	✓	Description
`quantity`	float	✓	Quantité
`unit_price`	float	✓	Prix unitaire HT
`tax_rate`	float	–	TVA % (défaut: 21)
`product_id`	int	–	Lier à un produit existant
`discount`	float	–	Remise en €

// Exemple — créer une facture
POST /api/v1/documents/invoices
{
  "customer_id": 56,
  "date": "2026-03-24",
  "due_date": "2026-04-24",
  "lines": [
    { "description": "Développement site web", "quantity": 1, "unit_price": 1500.00, "tax_rate": 21 },
    { "description": "Hébergement mensuel", "quantity": 12, "unit_price": 15.00 }
  ]
}
→ 201 { "id": 5678, "number": "FAC-2026-0043", "status": "draft", "total_incl_tax": 2116.35 }

PUT /api/v1/documents/{slug}/{id} Auth Modifier un document

Mêmes champs que le POST. Les lignes fournies remplacent les lignes existantes.

GET /api/v1/document-types Auth Types de documents disponibles

[
  { "id": 1, "name": "Facture", "slug": "invoices" },
  { "id": 2, "name": "Devis", "slug": "quotes" },
  { "id": 3, "name": "Commande", "slug": "orders" },
  { "id": 4, "name": "Avoir", "slug": "credit-notes" }
]

Clients

GET /api/v1/customers Auth Liste des clients

Query params

Param	Description
`search`	Recherche par nom, email, TVA
`per_page`	Résultats par page

{ "data": [{ "id": 56, "first_name": "Jean", "last_name": "Dupont",
  "company": "ACME SRL", "email": "jean@acme.be",
  "vat_number": "BE0123456789", "phone": "+32 2 000 00 00" }] }

GET /api/v1/customers/{id} Auth Détail client

Retourne le client avec adresses, emails, téléphones et données complètes.

POST /api/v1/customers Auth Créer un client

Body

Champ	Requis	Description
`first_name`	–	Prénom
`last_name`	–	Nom
`company`	–	Raison sociale
`email`	–	Email principal
`vat_number`	–	Numéro TVA (BEXXXXXXXXXX)
`phone`	–	Téléphone
`address`	–	Adresse
`city`	–	Ville
`postal_code`	–	Code postal
`country_id`	–	ID pays (22 = Belgique)

PUT /api/v1/customers/{id} Auth Modifier un client

Mêmes champs que le POST, tous optionnels.

Fournisseurs

Même structure que les clients. Préfixe /api/v1/suppliers.

GET /api/v1/suppliers Auth Liste des fournisseurs

{ "data": [{ "id": 12, "company": "Fournisseur SRL", "vat_number": "BE0987654321" }] }

POST /api/v1/suppliers Auth Créer un fournisseur

Mêmes champs que POST /api/v1/customers.

Produits

GET /api/v1/products Auth Catalogue produits

{ "data": [{ "id": 12, "name": "Pizza Margherita", "sku": "PIZ-001",
  "price": 9.90, "tax_rate": 6, "stock": null, "category": "Pizzas" }] }

POST /api/v1/products Auth Créer un produit

Body

Champ	Requis	Description
`name`	✓	Nom
`price`	✓	Prix HT
`tax_rate`	–	TVA % (défaut: 21)
`sku`	–	Référence produit
`description`	–	Description
`product_category_id`	–	ID catégorie
`stock`	–	Stock initial

Commandes en ligne

Flux complet pour un site e-commerce : catalogue public → client → commande.

Flux recommandé : Le slug orders crée automatiquement un document de type Commande avec numéro CMD-XXXX.

// 1. Catalogue public (sans auth)
GET /api/shops/mon-shop/export
→ products[], product_categories[]

// 2. Créer le client (avec auth)
POST /api/v1/customers
{ "first_name": "Jean", "last_name": "Dupont", "email": "jean@example.com" }
→ { "id": 123 }

// 3. Créer la commande (avec auth)
POST /api/v1/documents/orders
{
  "customer_id": 123,
  "date": "2026-03-24",
  "lines": [
    { "product_id": 12, "quantity": 2, "unit_price": 9.90, "tax_rate": 6 }
  ]
}
→ { "id": 5678, "number": "CMD-2026-0099", "total_incl_tax": 20.99 }

Peppol (e-facturation)

Vérifiez si une entreprise est inscrite sur le réseau Peppol belge (obligatoire B2B 2026).

POST /api/peppol/check-id Vérifier un ID Peppol

POST { "vat_number": "BE0123456789" }
→ { "registered": true, "peppol_id": "0208:0123456789" }

Codes d'erreur

Code	Signification
`200`	Succès
`201`	Ressource créée
`401`	Token manquant ou invalide
`403`	Accès refusé — ressource d'un autre shop
`404`	Ressource introuvable
`422`	Erreur de validation (voir champ `errors`)
`429`	Rate limit dépassé
`500`	Erreur serveur

// Format d'erreur 422
{ "message": "The given data was invalid.",
  "errors": { "customer_id": ["The customer id is required."] } }

Cas d'usage

🌐

Site vitrine

Horaires, produits, réseaux sociaux alimentés en temps réel.

GET /api/shops/{slug}/export

🛒

E-commerce

Commandes en ligne → documents Novadesko automatiques.

POST /api/v1/documents/orders

📊

Reporting BI

Export des factures vers votre outil de reporting.

GET /api/v1/documents/invoices

🔗

Intégration ERP

Sync clients/produits entre Novadesko et votre système.

POST /api/v1/customers & /products