Gestion des erreurs de l'API : codes de statut HTTP et messages d'erreur

En cas de problème, l'API faktoora renvoie des codes de statut HTTP standardisés et des messages d'erreur explicites. Cet article vous aide à comprendre et à corriger les erreurs les plus fréquentes.

HTTP 404 : facture introuvable

Si vous tentez de récupérer ou de modifier une facture via l'API et recevez une erreur 404, cela signifie que la ressource demandée est introuvable.

Causes fréquentes :

• faktooraId erronée : vérifiez que vous utilisez la bonne faktooraId. Elle a été renvoyée dans la réponse sous faktooraId lors de la création de la facture.
• Création asynchrone de la facture : si vous souhaitez récupérer une facture avec GET immédiatement après sa création, une erreur 404 peut survenir. L'API répond aux requêtes POST avec 202 Accepted et une faktooraId. La facture est traitée de manière asynchrone et peut ne pas être disponible pendant un court instant. Utilisez la faktooraId indiquée pour consulter le statut ou utilisez des webhooks pour être notifié lorsque le traitement est terminé.
• La facture a été supprimée : la facture demandée n'existe plus dans le système.

Solution :

Validez la faktooraId dans votre requête. Pour les factures nouvellement créées : attendez quelques secondes ou vérifiez le statut de traitement avec GET /invoices/{faktooraId}/status avant d'accéder à l'enregistrement complet de la facture.

HTTP 400 : requête incorrecte

Une erreur HTTP 400 signale un problème de validation dans la requête envoyée. C'est l'erreur la plus fréquente lors de l'intégration de l'API.

Paramètres obligatoires incorrects ou manquants

Causes :

• Des champs obligatoires sont absents (par ex. invoiceNumber, issueDate, buyer, seller)
• Les formats des champs sont incorrects (par ex. date pas au format YYYYMMDD)
• Valeurs inconnues ou invalides pour des champs énumérés (par ex. invoiceTypeCode)

Solution :

Consultez la documentation de l'API ou le schéma OpenAPI pour connaître les champs obligatoires et leurs plages de valeurs valides. La réponse d'erreur contient des indications sur le champ erroné.

Erreur de validation sur les nombres décimaux : "must be multiple of 0.01"

Lorsque vous transmettez des montants dans le tableau allowance (remises ou majorations) ou dans d'autres champs monétaires, tous les nombres décimaux doivent être limités à 2 décimales au maximum.

L'erreur survient avec :

• allowance[].amount avec plus de 2 décimales (par ex. 10.005 au lieu de 10.00)
• Des problèmes similaires avec d'autres champs monétaires

Solution :

Arrondissez tous les montants à 2 décimales. Exemple :

{
  "allowance": [
    {
      "indicator": "discount",
      "reason": "Mengenrabatt",
      "amount": 10.50,
      "taxes": [
        {
          "typeCode": "VAT",
          "categoryCode": "S",
          "rate": 19
        }
      ]
    }
  ]
}

HTTP 400 : "Docx template is disabled"

Ce message d'erreur signifie que vous avez tenté d'utiliser un modèle DOCX ou Typst lors de la création de la facture, alors que la fonction de modèles n'est pas activée.

Causes :

• Les fonctions de modèles ne sont pas activées pour votre compte
• Vous transmettez le champ template dans la requête alors que la fonction n'est pas débloquée

Solution :

Deux possibilités s'offrent à vous :

1. Omettre le champ template : supprimez l'objet template de la requête pour utiliser le modèle de facture standard.
2. Activer la fonction : contactez le support faktoora pour faire débloquer les fonctions de modèles (modèles DOCX ou Typst) pour votre compte.

Une fois les fonctions activées, vous pouvez indiquer le nom de votre modèle personnalisé avec le paramètre template.label.

L'allowance n'apparaît pas dans le PDF

Si vous transmettez des données allowance dans l'API mais qu'elles n'apparaissent pas dans le PDF de facture généré ou ne sont pas déduites du montant total, plusieurs causes sont possibles.

Causes fréquentes :

• Taux de TVA manquants : chaque entrée d'allowance nécessite un tableau taxes avec au moins une entrée VAT. Sans configuration fiscale correcte, l'allowance peut être ignorée.
• Le format de facture ne prend pas en charge les allowances : tous les formats de facture (par ex. les factures PDF simples au format simple) ne prennent pas en charge les allowances. Les allowances sont correctement traitées dans les formats structurés (ZUGFeRD, XRechnung).

Solution :

Assurez-vous que :

1. Chaque entrée d'allowance contient un tableau taxes avec au moins une entrée :

"taxes": [
  {
    "typeCode": "VAT",
    "categoryCode": "S",
    "rate": 19
  }
]

2. Vous utilisez un format de facture structuré qui prend en charge les allowances (format: "zf:2" ou format: "xrechnung").

HTTP 500 : erreur interne du serveur

Une erreur 500 signifie qu'une erreur inattendue s'est produite sur le serveur. L'erreur Cannot read properties of undefined indique une erreur de type pointeur nul dans le code.

Causes fréquentes :

• Structures de données invalides ou incohérentes : des champs sont présents, mais leur contenu ne correspond pas à ce qui est attendu.
• Références requises manquantes : si vous référencez un objet (par ex. un client via buyer.faktooraCustomerId), la référence peut ne pas être résolue.
• Erreur temporaire : des erreurs 500 occasionnelles peuvent aussi signaler une indisponibilité technique du serveur.

Solution :

1. Vérifiez que votre requête est complète et valide, en particulier les références à des ressources externes (ID client, ID de modèle).
2. Renouvelez la requête après un court délai.
3. Si l'erreur persiste, contactez le support faktoora en fournissant :
   • la requête API exacte (sans clé ni données sensibles)
   • l'horodatage de l'erreur
   • la réponse ou le message d'erreur que vous avez reçu

Bonnes pratiques pour une intégration API sans erreur

• Validez localement : vérifiez vos données avant de les envoyer à l'API (formats, champs obligatoires, limites de longueur).
• Utilisez l'environnement de démonstration : effectuez vos tests d'abord sur https://api.demo.faktoora.com/api/v1 plutôt que sur l'environnement de production https://api.faktoora.com/api/v1.
• Gérez le traitement asynchrone : la création de factures est asynchrone. Ne consultez pas le statut immédiatement après, utilisez plutôt des webhooks ou un polling espacé.
• Journalisez les réponses : enregistrez la réponse complète de l'API, en particulier pour les erreurs 400 et 500 ; elle indique le champ erroné.
• Consultez la documentation : la documentation OpenAPI contient toutes les exigences pour chaque point de terminaison.