Intégration Billingo
Billingo est une plateforme de facturation en ligne hongroise conforme à NAV Online Számla 3.0. Une fois configurée dans CADENSA, vous pouvez émettre des factures fiscales hongroises légalement valides directement depuis vos entrées de temps — avec déclaration NAV automatique et synchronisation de votre carnet d'adresses Billingo.
Prérequis
- Un compte Billingo actif (avec accès API)
- Une clé API Billingo v3 (voir ci-dessous)
- Au moins un bloc de facturation (számlablokk) configuré dans Billingo
- Rôle Admin minimum sur l'unité CADENSA
Étape 1 — Obtenir votre clé API Billingo
- Connectez-vous sur app.billingo.hu
- Dans le menu gauche, cliquez sur Beállítások (Paramètres)
- Cliquez sur API dans le menu des paramètres
- Cliquez sur + Új API kulcs létrehozása (Créer une nouvelle clé API)
- Donnez un nom à la clé (ex.
CADENSA) - Copiez la clé générée immédiatement — elle n'est affichée qu'une seule fois
Ne partagez jamais votre clé API et ne la committez pas dans votre gestionnaire de versions. Toute personne disposant de cette clé peut créer des factures en votre nom.
Étape 2 — Configurer dans CADENSA
- Ouvrez Paramètres → Facture dans CADENSA
- Sélectionnez Billingo 🇭🇺 comme fournisseur
- Un message d'information apparaît :
Trouvez votre clé API Billingo sur : app.billingo.hu → Beállítások → API → API kulcs létrehozása
- Collez votre clé API dans le champ API Key
- Cliquez sur Tester la connexion — un
vert confirme la validité - Cliquez sur Enregistrer
Le bouton Enregistrer reste désactivé jusqu'à ce que le test de connexion réussisse.
Étape 3 — Définir les valeurs par défaut
| Paramètre | Valeur recommandée (HU) | Description |
|---|---|---|
| Devise par défaut | HUF | Devise utilisée sur les nouvelles factures |
| TVA % par défaut | 27 | Taux standard hongrois (ÁFA) |
| Délai de paiement (jours) | 8 ou 30 | Jours avant échéance |
| Type de document par défaut | Facture | Pré-sélectionné dans le dialogue de génération |
| Pays de l'émetteur | HU | Code pays ISO 3166-1 alpha-2 de votre entreprise |
Le champ Pays de l'émetteur active des suggestions de TVA intelligentes (autoliquidation, détection d'export) dans le dialogue de génération de facture. Sans lui, CADENSA se rabat sur le taux de TVA domestique de l'acheteur. Voir Génération de factures — Suggestion de TVA pour plus de détails.
Étape 4 — Paramètres spécifiques à Billingo
| Paramètre | Description |
|---|---|
| ID du bloc de facturation | Le bloc de facturation Billingo à utiliser. CADENSA sélectionne automatiquement le premier bloc actif si ce champ est vide. Pour un bloc spécifique, entrez l'ID depuis Billingo → Beállítások → Bizonylattömbök. |
| ID du compte bancaire | Optionnel. L'ID de votre compte bancaire Billingo — apparaît sur la facture. |
| Mode de paiement | Mode de paiement par défaut (wire_transfer, cash, bankcard, etc.). |
| Langue de la facture | Langue d'émission (hu, en, de, fr, etc.). |
Étape 5 — (Optionnel) Mode Sandbox / Test
Activez le mode Sandbox pour tester la génération de factures sans émettre de vraies factures déclarées à NAV. Les factures sandbox :
- N'apparaissent pas dans votre liste officielle Billingo
- Ne sont pas déclarées à NAV
- Sont ignorées après les tests
Interrupteur : Paramètres → Facture → Sandbox / Mode test
Émettre une facture via Billingo
- Ouvrez Rapports → définissez la plage de dates et les filtres de projet
- Cliquez sur Générer une facture
- Dans le champ Type de document, sélectionnez Facture — le canal de sortie affiche
Billingo - (Optionnel) Utilisez le sélecteur de partenaire pour choisir un client depuis votre carnet Billingo
- Remplissez les coordonnées client, le taux de TVA et la date d'échéance
- Cliquez sur Aperçu → vérifiez les lignes et les totaux
- Cliquez sur Émettre la facture (Billingo)
- Une nouvelle facture est créée et immédiatement finalisée (ce qui attribue le numéro de facture Billingo)
- La facture est automatiquement déclarée à NAV Online Számla 3.0
- La facture apparaît dans Billingo sous Számlák → Kimenő számlák
Sélecteur de partenaire
Quand Billingo est configuré, le dialogue de génération affiche un sélecteur de partenaire — une liste déroulante searchable de vos contacts Billingo.
La sélection d'un contact pré-remplit automatiquement :
- Nom de l'entreprise
- Adresse (rue, code postal, ville, pays)
- Num éro de TVA
- Adresse e-mail
Si le client n'existe pas dans votre carnet Billingo, CADENSA le crée automatiquement. Les contacts sont récupérés depuis l'endpoint /partners de Billingo (jusqu'à 100 partenaires).
CADENSA fait correspondre les partenaires par nom, sans distinction majuscules/minuscules. Si un partenaire existe déjà sous le même nom, l'enregistrement existant est mis à jour avec les nouvelles coordonnées fournies.
Taux de TVA
| Taux | Utilisation |
|---|---|
| 27% | TVA standard hongroise (ÁFA) |
| 5% | Taux réduit (certains aliments, médicaments) |
| 0% | Exonéré, livraison intracommunautaire, export |
| AAM | Exonération générale |
| TAM | Exonération objective |
| EU | Livraison intracommunautaire de biens |
| EUK | Livraison intracommunautaire (cas particulier UE) |
| MAA | Compensation forfaitaire agricole |
| F.AFA | Autoliquidation (reverse charge) |
| K.AFA | TVA sur encaissement |
| KBAUK | Export hors UE |
Si vous saisissez un taux de TVA absent de la liste ci-dessus, CADENSA applique 27% par défaut. Utilisez les taux numériques (0, 5, 27) pour les cas standards et les codes texte pour les régimes fiscaux spéciaux.
Factures en devise étrangère
Billingo fonctionne nativement en HUF. Pour les factures en autres devises (EUR, USD, GBP, etc.) :
- CADENSA récupère automatiquement le taux de change HUF actuel depuis l'API Frankfurter (données BCE)
- Le taux de change (
conversion_rate) est inclus dans la requête comme exigé par Billingo - Le taux est enregistré dans le dossier de facture CADENSA à des fins d'audit
Si l'API de taux de change est indisponible, CADENSA utilise des taux de secours approximatifs (EUR ~400 HUF, USD ~370 HUF). Pour un usage en production, assurez une connectivité sortante vers api.frankfurter.app.
Routage des documents
| Type de document | Sortie |
|---|---|
| Proforma | PDF interne (jamais envoyé à Billingo) |
| Récapitulatif de travail | PDF interne (jamais envoyé à Billingo) |
| Facture | Envoyée à l'API Billingo → PDF retourné |
Seuls les documents de type « Facture » sont envoyés à Billingo. Proforma et Récapitulatif de travail sont toujours générés en interne, quel que soit le paramètre du fournisseur.
Annulation de facture (Storno)
Pour annuler une facture Billingo depuis CADENSA :
- Ouvrez Facturation → Historique des factures
- Trouvez la facture et cliquez sur Annuler la facture
- Confirmez l'annulation
CADENSA appelle POST /documents/{id}/cancel. Une facture d'annulation est automatiquement créée dans Billingo et déclarée à NAV.
Les factures annulées ne peuvent pas être restaurées. Si vous devez refacturer, générez une nouvelle facture depuis la page Rapports.
Historique des factures et téléchargement PDF
Après la création réussie d'une facture :
- La facture apparaît dans Facturation → Historique des factures dans CADENSA
- La facture apparaît aussi dans votre compte Billingo sous Számlák → Kimenő számlák
- Vous pouvez retélécharger le PDF à tout moment depuis l'un ou l'autre emplacement
Tester la connexion
Utilisez le bouton Tester la connexion après avoir saisi votre clé API. CADENSA appelle l'endpoint /utils/time de Billingo pour vérifier :
- Que la clé API est valide et active
- Que la clé dispose des permissions requises
Un test réussi affiche :
✓ Connexion réussie
Dépannage
« Clé API invalide » / 401 Unauthorized
La clé API est invalide, expirée ou révoquée.
Solution : Générez une nouvelle clé dans Billingo (Beállítások → API → + Új API kulcs) et saisissez-la à nouveau dans CADENSA.
« Aucun bloc de facturation trouvé »
Aucun bloc de facturation configuré dans Billingo.
Solution : Dans Billingo, allez dans Beállítások → Bizonylattömbök et créez au moins un bloc actif.
Erreur « INVOICE_NO_BILLABLE_ITEMS »
Toutes les lignes ont amount = 0 — aucun taux horaire configuré.
Solution : Ouvrez Paramètres → Tarifs et configurez des taux horaires pour vos projets.
Erreur « Partenaire introuvable »
La création automatique du partenaire a échoué — généralement en raison d'un champ requis manquant (code postal, ville ou adresse).
Solution : Assurez-vous que la fiche client dans CADENSA comporte au moins un code pays et une ville. Vous pouvez aussi créer le partenaire manuellement dans Billingo puis le sélectionner via le sélecteur de partenaire.
Le PDF n'a pas de numéro de facture
L'appel à l'API Billingo a réussi mais le PDF téléchargé depuis CADENSA n'inclut pas le numéro de facture externe.
Solution : Retéléchargez le PDF depuis Facturation → Historique des factures — l'enregistrement stocké contient le numéro de facture correct de Billingo.
Limite de requêtes dépassée (429 Too Many Requests)
Billingo autorise 120 requêtes par minute. Générer de nombreuses factures rapidement peut dépasser cette limite.
Solution : Attendez 60 secondes puis réessayez. Pour la génération de factures en masse, échelonnez les requêtes.
Facture non-HUF : « conversion_rate required »
Billingo exige un taux de conversion HUF pour toutes les devises autres que le HUF.
Solution : Ceci est géré automatiquement par CADENSA (via l'API Frankfurter). Si cette erreur apparaît, vérifiez la connectivité réseau vers api.frankfurter.app. Si l'API est bloquée, CADENSA utilise des taux de secours codés en dur.
Billingo vs. Lexoffice
| Fonctionnalité | Billingo 🇭🇺 | Lexoffice 🇩🇪 |
|---|---|---|
| Marché | Hongrie | DE / AT / CH |
| Norme légale | NAV Online Számla 3.0 | ZUGFeRD / E-Rechnung |
| Authentification | Clé API (v3) | Jeton Bearer (clé API) |
| Mode sandbox | Disponible |  Non disponible |
| Sélecteur de partenaire | Endpoint /partners | Endpoint /contacts |
| Génération PDF | Synchrone | Asynchrone (polling jusqu'à 30s) |
| Finalisation de facture | Automatique | Explicite (?finalize=true) |
| Devise non domestique | Taux de conversion automatique (MNB via Frankfurter) | Pris en charge nativement |
Pages associées
- Param ètres du fournisseur de facturation — comparer tous les fournisseurs, configurer la clé API et les valeurs par défaut
- Génération de factures — générer des factures depuis les entrées de temps
- Plans d'abonnement — quel plan CADENSA est nécessaire