Aller au contenu
Documentation
Guide API Démo
Français
Ouvrir l'application

Créer un dossier

Cas d'usage pas à pas pour créer un dossier comptable par l'API, avec son plan comptable, ses journaux, son exercice et ses comptes bancaires.

Mis à jour le 05/10/2026 Modifier cette page

Ce guide crée un dossier belge prêt à recevoir des écritures. En un seul appel, NovaFisko installe le plan comptable du pays, les journaux, les codes TVA, l'exercice et ses périodes.

Prérequis : un jeton de session ou un jeton d'intégration avec les capacités read et write, détenu par un administrateur ou un gestionnaire du cabinet.

Étape 1 : identifier le cabinet

Le public_token du cabinet figure dans la réponse de auth/me.

curl https://api.novafisko.com/v1/auth/me \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

{
  "id": 12,
  "name": "Claire Dumont",
  "email": "claire.dumont@fiduciaire-exemple.be",
  "locale": "fr",
  "is_platform_admin": false,
  "is_demo": false,
  "firms": [{"public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple", "role": "admin"}],
  "managed_firms": [{"public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple"}]
}

Vous ne pouvez créer un dossier que dans un cabinet listé dans managed_firms. Si l'utilisateur n'en gère qu'un seul, le champ firm de l'étape 3 devient facultatif.

Étape 2 (facultative) : préremplir depuis le numéro d'entreprise

La détection d'entreprise interroge CompanySearch pour la Belgique et la France. Elle vous évite de saisir l'adresse et la forme juridique.

curl "https://api.novafisko.com/v1/lookup/search?q=0999.900.134&country=BE" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

Reprenez les champs d'identité de la fiche renvoyée dans le corps de l'étape 3. Les packs pays disponibles sont listés par GET /v1/country-packs et les formes juridiques par GET /v1/reference/legal-forms.

Étape 3 : créer le dossier

curl -X POST https://api.novafisko.com/v1/companies \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "firm": "Fd7hQ2mN8sXa",
    "country_pack": "BE",
    "code": "ATELIER",
    "name": "Atelier du Vélo SRL",
    "enterprise_number": "0999.900.134",
    "vat_number": "BE0999900134",
    "legal_form": "SRL",
    "street": "Rue des Carmes",
    "house_number": "18",
    "postal_code": "5000",
    "city": "Namur",
    "country": "BE",
    "vat_regime": "quarterly",
    "locale": "fr",
    "fiscal_year": {"code": "2026", "starts_on": "2026-01-01", "ends_on": "2026-12-31"},
    "banks": [
      {"code": "BNK1", "label": "Compte à vue Belfius", "iban": "BE68539007547034"}
    ]
  }'

Champs principaux

Champ Obligatoire Description
name oui Dénomination, 200 caractères max
firm non public_token du cabinet gestionnaire (12 caractères)
country_pack non BE par défaut. Détermine le plan comptable, la TVA et les contrôles
code non Code court du dossier, 20 caractères max, lettres, chiffres, tirets. Converti en majuscules
enterprise_number non Vérifié selon le pays (modulo 97 pour la Belgique)
vat_number non Format et clé de contrôle vérifiés selon le pays
legal_form, legal_form_code non Libellé libre ou code du référentiel
street, house_number, box, postal_code, city, country non Adresse structurée
vat_regime non monthly, quarterly, franchise, exempt ou unit selon le pack
locale non fr, nl, en ou de. Par défaut, la langue de l'utilisateur
fiscal_year non Si présent, starts_on et ends_on sont obligatoires. Sinon l'exercice civil courant est créé
banks non Un journal financier par compte : code (6 caractères max), label, iban

Réponse 201

{
  "id": 318,
  "public_token": "Av4eLo7Nm2Sr",
  "firm_id": 4,
  "code": "ATELIER",
  "name": "Atelier du Vélo SRL",
  "legal_form": "SRL",
  "enterprise_number": "0999.900.134",
  "vat_number": "BE0999900134",
  "address": "Rue des Carmes 18, 5000 Namur",
  "street": "Rue des Carmes",
  "house_number": "18",
  "postal_code": "5000",
  "city": "Namur",
  "country": "BE",
  "country_pack": "BE",
  "vat_regime": "quarterly",
  "currency": "EUR",
  "locale": "fr",
  "is_active": true,
  "version": 1,
  "firm": {"id": 4, "public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple"},
  "fiscal_years": [
    {
      "id": 702,
      "code": "2026",
      "starts_on": "2026-01-01T00:00:00.000000Z",
      "ends_on": "2026-12-31T00:00:00.000000Z",
      "is_closed": false,
      "periods": [
        {"id": 9001, "number": 1, "label": "01/2026", "starts_on": "2026-01-01T00:00:00.000000Z", "ends_on": "2026-01-31T00:00:00.000000Z", "is_locked": false}
      ]
    }
  ],
  "journals": [
    {"id": 2101, "code": "ACH", "label": "Achats", "type": "purchase", "control_account": {"id": 55090, "number": "440000", "label": "Fournisseurs"}},
    {"id": 2102, "code": "VEN", "label": "Ventes", "type": "sale", "control_account": {"id": 55041, "number": "400000", "label": "Clients"}},
    {"id": 2105, "code": "BNK1", "label": "Compte à vue Belfius", "type": "financial", "iban": "BE68539007547034"}
  ]
}

Conservez public_token : c'est l'identifiant du dossier dans toutes les routes suivantes. Les listes periods et journals sont abrégées ici.

Étape 4 : vérifier l'installation

curl https://api.novafisko.com/v1/companies/Av4eLo7Nm2Sr/accounts?postable=1 \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

curl https://api.novafisko.com/v1/companies/Av4eLo7Nm2Sr/vat-codes \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

Ces deux appels renvoient le plan comptable et les codes TVA du dossier, avec les id dont vous aurez besoin pour saisir des écritures.

Erreurs fréquentes

Statut Cause Correction
422, champ enterprise_number Numéro d'entreprise invalide pour le pays Vérifier la clé de contrôle
422, champ vat_number Numéro de TVA mal formé Inclure le préfixe pays, par exemple BE0999900134
422, champ firm Le cabinet n'est pas géré par l'utilisateur Utiliser un public_token de managed_firms
422, code company_limit_reached Plafond de dossiers de la licence atteint Voir Consulter la licence
403, code token_ability_missing Jeton sans la capacité write Créer un jeton adapté
Note

Sans cabinet (firm absent et aucun cabinet géré), le dossier est créé comme dossier autonome et l'utilisateur en devient le responsable. Ce cas concerne les indépendants qui tiennent eux-mêmes leur comptabilité.

Astuce

Envoyer un X-Client-Mutation-Id ne sert à rien ici : la route POST /v1/companies n'est pas rattachée à un dossier existant. Pour éviter un doublon après une coupure réseau, relisez GET /v1/companies et cherchez votre code avant de réessayer.

Voir aussi