Conventions

Cette page rassemble les règles communes à toutes les routes. Les respecter évite la plupart des erreurs 422.

Requêtes#

• Envoyez Accept: application/json sur chaque appel. L'hôte api.novafisko.com répond toujours en JSON, mais cet en-tête garantit le même comportement derrière un proxy.
• Les corps sont en JSON (Content-Type: application/json), encodés en UTF-8.
• Le dépôt de fichiers (document-imports) utilise multipart/form-data.
• Les noms de champs sont en anglais et en snake_case. Les segments d'URL sont en kebab-case (third-parties, vat-declarations).

Dates et heures#

Une date comptable n'a pas de fuseau : le 31 mars reste le 31 mars quel que soit l'endroit d'où vous appelez. Les horodatages sont stockés et renvoyés en UTC. Convertissez-les dans le fuseau de votre utilisateur au moment de l'affichage.

Montants#

Les montants sont exprimés en euros, sous forme de chaînes décimales avec un point et deux décimales : "1250.00", "0.21", "-48.40".

{
  "debit": "1250.00",
  "credit": "0.00",
  "balance": "1250.00"
}

Ce choix évite les erreurs d'arrondi des nombres flottants. Dans votre code, utilisez un type décimal (BigDecimal, decimal, Decimal, bcmath) ou travaillez en centimes entiers.

En entrée, l'API accepte aussi bien "1250.00" que 1250 ou 1250.5. Elle convertit tout en centimes avant de calculer. Nous recommandons d'envoyer des chaînes.

Une écriture doit être équilibrée au centime près : la somme des débits égale la somme des crédits, sinon la requête est refusée avec 422.

Identifiants#

NovaFisko utilise deux familles d'identifiants.

Le public_token est opaque, stable et non devinable. C'est lui que vous devez stocker pour désigner un cabinet ou un dossier. Les id numériques n'ont de sens qu'à l'intérieur de leur dossier : une route companies/{company}/entries/{id} répond 404 si l'écriture appartient à un autre dossier.

/v1/companies/k3Jd9fPq2LmX/entries/1842
              └─ public_token       └─ id

Certains champs acceptent une forme lisible à la place de l'id. Dans une écriture, par exemple, une ligne peut désigner son compte par account_id (entier) ou par account (numéro de compte, "604000"). De même, une ligne de facture accepte vat_code_id ou vat_code.

Données importées#

Les enregistrements issus d'une autre source portent trois champs : source (par exemple novadesko), external_id (l'identifiant dans la source) et synced_at. Servez-vous de external_id pour retrouver un enregistrement que vous avez vous-même poussé.

Version d'un enregistrement#

Les ressources suivies par l'historique exposent un entier version qui augmente à chaque modification. Renvoyez-le dans X-Base-Version pour activer le verrou optimiste décrit dans Idempotence.

Langue des messages#

Les libellés et messages d'erreur existent en français, néerlandais, anglais et allemand. La langue est choisie ainsi :

1. le paramètre de requête locale (routes d'historique, de corbeille et de synchronisation) ou lang (exports, licence) quand il est fourni ;
2. sinon la langue du profil de l'utilisateur propriétaire du jeton ;
3. sinon l'en-tête Accept-Language ;
4. sinon la langue par défaut de la plateforme.

GET /v1/firms/Fd7hQ2mN8sXa/licence?lang=nl HTTP/1.1
Accept-Language: nl-BE,nl;q=0.9,fr;q=0.6

En-têtes de requête#

Les en-têtes X-Device-* sont facultatifs mais utiles : ils apparaissent dans l'onglet Historique, ce qui permet à un comptable de voir qu'une modification vient de votre connecteur.

curl -X POST https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/third-parties \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: erp-atelier-prod" \
  -H "X-Device-Name: ERP%20Atelier" \
  -H "X-Client-Mutation-Id: 6f1c2f0e-7a53-4f0b-9c58-0b8a4a7c2d11" \
  -d '{"type": "supplier", "name": "Brasserie des Collines SA", "vat_number": "BE0999900134"}'

En-têtes de réponse#

Suppressions#

Une suppression ne détruit presque jamais rien immédiatement :

• un tiers, un compte, un journal, une règle ou une immobilisation part à la corbeille (X-Trashed: 1) et peut être restauré pendant la durée de rétention du dossier, 90 jours par défaut ;
• une écriture validée ne se supprime pas : elle s'extourne avec POST entries/{id}/reverse, ce qui préserve la numérotation continue.

Voir aussi#

• Erreurs et limites
• Idempotence
• Pagination
• Historique