factpulse 2.0.37__py3-none-any.whl → 3.0.23__py3-none-any.whl

factpulse_helpers/client.py

@@ -1,4 +1,4 @@
-"""Client simplifié pour l'API FactPulse avec authentification JWT et polling intégrés."""
+"""Simplified client for the FactPulse API with built-in JWT authentication and polling."""
 import base64
 import json
 import logging
@@ -12,7 +12,7 @@ from typing import Any, Dict, List, Optional, Tuple, Union
 import requests
 
 import factpulse
-from factpulse import ApiClient, Configuration, TraitementFactureApi
+from factpulse import ApiClient, Configuration, InvoiceProcessingApi
 
 from .exceptions import (
     FactPulseAuthError,
@@ -25,39 +25,39 @@ logger = logging.getLogger(__name__)
 
 
 # =============================================================================
-# JSON Encoder pour Decimal et autres types non sérialisables
+# JSON Encoder for Decimal and other non-serializable types
 # =============================================================================
 
 class DecimalEncoder(json.JSONEncoder):
-    """Encoder JSON personnalisé qui gère les Decimal et autres types Python."""
+    """Custom JSON encoder that handles Decimal and other Python types."""
 
     def default(self, obj):
         if isinstance(obj, Decimal):
-            # Convertir en string pour préserver la précision monétaire
+            # Convert to string to preserve monetary precision
             return str(obj)
         if hasattr(obj, "isoformat"):
             # datetime, date, time
             return obj.isoformat()
         if hasattr(obj, "to_dict"):
-            # Modèles Pydantic ou dataclasses avec to_dict
+            # Pydantic models or dataclasses with to_dict
             return obj.to_dict()
         return super().default(obj)
 
 
 def json_dumps_safe(data: Any, **kwargs) -> str:
-    """Sérialise en JSON en gérant les Decimal et autres types Python.
+    """Serialize to JSON handling Decimal and other Python types.
 
     Args:
-        data: Données à sérialiser (dict, list, etc.)
-        **kwargs: Arguments supplémentaires pour json.dumps
+        data: Data to serialize (dict, list, etc.)
+        **kwargs: Additional arguments for json.dumps
 
     Returns:
-        String JSON
+        JSON string
 
     Example:
         >>> from decimal import Decimal
-        >>> json_dumps_safe({"montant": Decimal("1234.56")})
-        '{"montant": "1234.56"}'
+        >>> json_dumps_safe({"amount": Decimal("1234.56")})
+        '{"amount": "1234.56"}'
     """
     kwargs.setdefault("ensure_ascii", False)
     kwargs.setdefault("cls", DecimalEncoder)
@@ -65,21 +65,21 @@ def json_dumps_safe(data: Any, **kwargs) -> str:
 
 
 # =============================================================================
-# Credentials dataclasses - pour une configuration simplifiée
+# Credentials dataclasses - for simplified configuration
 # =============================================================================
 
 @dataclass
 class ChorusProCredentials:
-    """Credentials Chorus Pro pour le mode Zero-Trust.
+    """Chorus Pro credentials for Zero-Trust mode.
 
-    Ces credentials sont passés dans chaque requête et ne sont jamais stockés côté serveur.
+    These credentials are passed in each request and never stored server-side.
 
     Attributes:
-        piste_client_id: Client ID PISTE (portail API gouvernement)
-        piste_client_secret: Client Secret PISTE
-        chorus_pro_login: Login Chorus Pro
-        chorus_pro_password: Mot de passe Chorus Pro
-        sandbox: True pour l'environnement sandbox, False pour production
+        piste_client_id: PISTE Client ID (government API portal)
+        piste_client_secret: PISTE Client Secret
+        chorus_pro_login: Chorus Pro login
+        chorus_pro_password: Chorus Pro password
+        sandbox: True for sandbox environment, False for production
     """
     piste_client_id: str
     piste_client_secret: str
@@ -88,7 +88,7 @@ class ChorusProCredentials:
     sandbox: bool = True
 
     def to_dict(self) -> Dict[str, Any]:
-        """Convertit en dictionnaire pour l'API."""
+        """Convert to dictionary for API."""
         return {
             "piste_client_id": self.piste_client_id,
             "piste_client_secret": self.piste_client_secret,
@@ -100,18 +100,18 @@ class ChorusProCredentials:
 
 @dataclass
 class AFNORCredentials:
-    """Credentials AFNOR PDP pour le mode Zero-Trust.
+    """AFNOR PDP credentials for Zero-Trust mode.
 
-    Ces credentials sont passés dans chaque requête et ne sont jamais stockés côté serveur.
-    L'API FactPulse utilise ces credentials pour s'authentifier auprès de la PDP AFNOR
-    et obtenir un token OAuth2 spécifique.
+    These credentials are passed in each request and never stored server-side.
+    The FactPulse API uses these credentials to authenticate with the AFNOR PDP
+    and obtain a specific OAuth2 token.
 
     Attributes:
-        flow_service_url: URL du Flow Service de la PDP (ex: https://api.pdp.fr/flow/v1)
-        token_url: URL du serveur OAuth2 de la PDP (ex: https://auth.pdp.fr/oauth/token)
-        client_id: Client ID OAuth2 de la PDP
-        client_secret: Client Secret OAuth2 de la PDP
-        directory_service_url: URL du Directory Service (optionnel, déduit de flow_service_url)
+        flow_service_url: PDP Flow Service URL (e.g., https://api.pdp.fr/flow/v1)
+        token_url: PDP OAuth2 server URL (e.g., https://auth.pdp.fr/oauth/token)
+        client_id: PDP OAuth2 Client ID
+        client_secret: PDP OAuth2 Client Secret
+        directory_service_url: Directory Service URL (optional, derived from flow_service_url)
     """
     flow_service_url: str
     token_url: str
@@ -120,7 +120,7 @@ class AFNORCredentials:
     directory_service_url: Optional[str] = None
 
     def to_dict(self) -> Dict[str, Any]:
-        """Convertit en dictionnaire pour l'API."""
+        """Convert to dictionary for API."""
         result = {
             "flow_service_url": self.flow_service_url,
             "token_url": self.token_url,
@@ -133,14 +133,14 @@ class AFNORCredentials:
 
 
 # =============================================================================
-# Helpers pour les types anyOf - évite la verbosité des wrappers générés
+# Helpers for anyOf types - avoids verbosity of generated wrappers
 # =============================================================================
 
-def montant(value: Union[str, float, int, Decimal, None]) -> str:
-    """Convertit une valeur en string de montant pour l'API.
+def amount(value: Union[str, float, int, Decimal, None]) -> str:
+    """Convert a value to an amount string for the API.
 
-    L'API FactPulse accepte les montants comme strings ou floats.
-    Cette fonction normalise en string pour garantir la précision monétaire.
+    The FactPulse API accepts amounts as strings or floats.
+    This function normalizes to string to guarantee monetary precision.
     """
     if value is None:
         return "0.00"
@@ -153,351 +153,432 @@ def montant(value: Union[str, float, int, Decimal, None]) -> str:
     return "0.00"
 
 
-def montant_total(
-    ht: Union[str, float, int, Decimal],
-    tva: Union[str, float, int, Decimal],
-    ttc: Union[str, float, int, Decimal],
-    a_payer: Union[str, float, int, Decimal],
-    remise_ttc: Union[str, float, int, Decimal, None] = None,
-    motif_remise: Optional[str] = None,
-    acompte: Union[str, float, int, Decimal, None] = None,
+def invoice_totals(
+    total_excl_tax: Union[str, float, int, Decimal],
+    total_vat: Union[str, float, int, Decimal],
+    total_incl_tax: Union[str, float, int, Decimal],
+    amount_due: Union[str, float, int, Decimal],
+    discount_incl_tax: Union[str, float, int, Decimal, None] = None,
+    discount_reason: Optional[str] = None,
+    prepayment: Union[str, float, int, Decimal, None] = None,
 ) -> Dict[str, Any]:
-    """Crée un objet MontantTotal simplifié.
+    """Create a simplified InvoiceTotals object.
 
-    Évite d'avoir à utiliser les wrappers MontantHtTotal, MontantTvaTotal, etc.
+    Avoids having to use wrappers like TotalNetAmount, VatAmount, etc.
     """
     result = {
-        "montantHtTotal": montant(ht),
-        "montantTva": montant(tva),
-        "montantTtcTotal": montant(ttc),
-        "montantAPayer": montant(a_payer),
+        "totalNetAmount": amount(total_excl_tax),
+        "vatAmount": amount(total_vat),
+        "totalGrossAmount": amount(total_incl_tax),
+        "amountDue": amount(amount_due),
     }
-    if remise_ttc is not None:
-        result["montantRemiseGlobaleTtc"] = montant(remise_ttc)
-    if motif_remise is not None:
-        result["motifRemiseGlobaleTtc"] = motif_remise
-    if acompte is not None:
-        result["acompte"] = montant(acompte)
+    if discount_incl_tax is not None:
+        result["globalAllowanceAmount"] = amount(discount_incl_tax)
+    if discount_reason is not None:
+        result["globalAllowanceReason"] = discount_reason
+    if prepayment is not None:
+        result["prepayment"] = amount(prepayment)
     return result
 
 
-def ligne_de_poste(
-    numero: int,
-    denomination: str,
-    quantite: Union[str, float, int, Decimal],
-    montant_unitaire_ht: Union[str, float, int, Decimal],
-    montant_total_ligne_ht: Union[str, float, int, Decimal],
-    taux_tva: Optional[str] = None,
-    taux_tva_manuel: Union[str, float, int, Decimal, None] = "20.00",
-    categorie_tva: str = "S",
-    unite: str = "FORFAIT",
+def invoice_line(
+    line_number: int,
+    description: str,
+    quantity: Union[str, float, int, Decimal],
+    unit_price_excl_tax: Union[str, float, int, Decimal],
+    line_total_excl_tax: Union[str, float, int, Decimal],
+    vat_rate_code: Optional[str] = None,
+    vat_rate_value: Union[str, float, int, Decimal, None] = "20.00",
+    vat_category: str = "S",
+    unit: str = "FORFAIT",
     reference: Optional[str] = None,
-    montant_remise_ht: Union[str, float, int, Decimal, None] = None,
-    code_raison_reduction: Optional[str] = None,
-    raison_reduction: Optional[str] = None,
-    date_debut_periode: Optional[str] = None,
-    date_fin_periode: Optional[str] = None,
+    discount_excl_tax: Union[str, float, int, Decimal, None] = None,
+    discount_reason_code: Optional[str] = None,
+    discount_reason: Optional[str] = None,
+    period_start_date: Optional[str] = None,
+    period_end_date: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Crée une ligne de poste pour l'API FactPulse.
+    """Create an invoice line for the FactPulse API.
 
-    Les clés JSON sont en camelCase (convention API FactPulse).
-    Les champs correspondent exactement à LigneDePoste dans models.py.
+    JSON keys are in camelCase (FactPulse API convention).
+    Fields correspond exactly to LigneDePoste in models.py.
 
-    Pour le taux de TVA, vous pouvez utiliser soit:
-    - taux_tva: Code prédéfini (ex: "TVA20", "TVA10", "TVA5.5")
-    - taux_tva_manuel: Valeur numérique (ex: "20.00", 20, 20.0)
+    For VAT rate, you can use either:
+    - vat_rate_code: Predefined code (e.g., "TVA20", "TVA10", "TVA5.5")
+    - vat_rate_value: Numeric value (e.g., "20.00", 20, 20.0)
 
     Args:
-        numero: Numéro de la ligne
-        denomination: Libellé du produit/service
-        quantite: Quantité
-        montant_unitaire_ht: Prix unitaire HT
-        montant_total_ligne_ht: Montant total HT de la ligne
-        taux_tva: Code TVA prédéfini (ex: "TVA20") - optionnel
-        taux_tva_manuel: Taux de TVA en valeur (défaut: "20.00") - utilisé si taux_tva non fourni
-        categorie_tva: Catégorie TVA - S (standard), Z (zéro), E (exonéré), AE (autoliquidation), K (intracommunautaire)
-        unite: Unité de facturation (défaut: "FORFAIT")
-        reference: Référence article
-        montant_remise_ht: Montant de remise HT (optionnel)
-        code_raison_reduction: Code raison de la réduction
-        raison_reduction: Description textuelle de la réduction
-        date_debut_periode: Date début période de facturation (YYYY-MM-DD)
-        date_fin_periode: Date fin période de facturation (YYYY-MM-DD)
+        line_number: Line number
+        description: Product/service description
+        quantity: Quantity
+        unit_price_excl_tax: Unit price excl. tax
+        line_total_excl_tax: Line total excl. tax
+        vat_rate_code: Predefined VAT code (e.g., "TVA20") - optional
+        vat_rate_value: VAT rate value (default: "20.00") - used if vat_rate_code not provided
+        vat_category: VAT category - S (standard), Z (zero), E (exempt), AE (reverse charge), K (intra-community)
+        unit: Billing unit (default: "FORFAIT")
+        reference: Item reference
+        discount_excl_tax: Discount amount excl. tax (optional)
+        discount_reason_code: Discount reason code
+        discount_reason: Discount reason description
+        period_start_date: Billing period start date (YYYY-MM-DD)
+        period_end_date: Billing period end date (YYYY-MM-DD)
     """
     result = {
-        "numero": numero,
-        "denomination": denomination,
-        "quantite": montant(quantite),
-        "montantUnitaireHt": montant(montant_unitaire_ht),
-        "montantTotalLigneHt": montant(montant_total_ligne_ht),
-        "categorieTva": categorie_tva,
-        "unite": unite,
+        "lineNumber": line_number,
+        "itemName": description,
+        "quantity": amount(quantity),
+        "unitNetPrice": amount(unit_price_excl_tax),
+        "lineNetAmount": amount(line_total_excl_tax),
+        "vatCategory": vat_category,
+        "unit": unit,
     }
-    # Soit taux_tva (code) soit taux_tva_manuel (valeur)
-    if taux_tva is not None:
-        result["tauxTva"] = taux_tva
-    elif taux_tva_manuel is not None:
-        result["tauxTvaManuel"] = montant(taux_tva_manuel)
+    # Either vat_rate_code (code) or vat_rate_value (value)
+    if vat_rate_code is not None:
+        result["vatRate"] = vat_rate_code
+    elif vat_rate_value is not None:
+        result["manualVatRate"] = amount(vat_rate_value)
     if reference is not None:
         result["reference"] = reference
-    if montant_remise_ht is not None:
-        result["montantRemiseHt"] = montant(montant_remise_ht)
-    if code_raison_reduction is not None:
-        result["codeRaisonReduction"] = code_raison_reduction
-    if raison_reduction is not None:
-        result["raisonReduction"] = raison_reduction
-    if date_debut_periode is not None:
-        result["dateDebutPeriode"] = date_debut_periode
-    if date_fin_periode is not None:
-        result["dateFinPeriode"] = date_fin_periode
+    if discount_excl_tax is not None:
+        result["lineAllowanceAmount"] = amount(discount_excl_tax)
+    if discount_reason_code is not None:
+        result["allowanceReasonCode"] = discount_reason_code
+    if discount_reason is not None:
+        result["allowanceReason"] = discount_reason
+    if period_start_date is not None:
+        result["periodStartDate"] = period_start_date
+    if period_end_date is not None:
+        result["periodEndDate"] = period_end_date
     return result
 
 
-def ligne_de_tva(
-    montant_base_ht: Union[str, float, int, Decimal],
-    montant_tva: Union[str, float, int, Decimal],
-    taux: Optional[str] = None,
-    taux_manuel: Union[str, float, int, Decimal, None] = "20.00",
-    categorie: str = "S",
+def vat_line(
+    base_amount_excl_tax: Union[str, float, int, Decimal],
+    vat_amount: Union[str, float, int, Decimal],
+    rate_code: Optional[str] = None,
+    rate_value: Union[str, float, int, Decimal, None] = "20.00",
+    category: str = "S",
 ) -> Dict[str, Any]:
-    """Crée une ligne de TVA pour l'API FactPulse.
+    """Create a VAT line for the FactPulse API.
 
-    Les clés JSON sont en camelCase (convention API FactPulse).
-    Les champs correspondent exactement à LigneDeTVA dans models.py.
+    JSON keys are in camelCase (FactPulse API convention).
+    Fields correspond exactly to LigneDeTVA in models.py.
 
-    Pour le taux de TVA, vous pouvez utiliser soit:
-    - taux: Code prédéfini (ex: "TVA20", "TVA10", "TVA5.5")
-    - taux_manuel: Valeur numérique (ex: "20.00", 20, 20.0)
+    For VAT rate, you can use either:
+    - rate_code: Predefined code (e.g., "TVA20", "TVA10", "TVA5.5")
+    - rate_value: Numeric value (e.g., "20.00", 20, 20.0)
 
     Args:
-        montant_base_ht: Montant de la base HT
-        montant_tva: Montant de la TVA
-        taux: Code TVA prédéfini (ex: "TVA20") - optionnel
-        taux_manuel: Taux de TVA en valeur (défaut: "20.00") - utilisé si taux non fourni
-        categorie: Catégorie de TVA (défaut: "S" pour standard)
+        base_amount_excl_tax: Base amount excl. tax
+        vat_amount: VAT amount
+        rate_code: Predefined VAT code (e.g., "TVA20") - optional
+        rate_value: VAT rate value (default: "20.00") - used if rate_code not provided
+        category: VAT category (default: "S" for standard)
     """
     result = {
-        "montantBaseHt": montant(montant_base_ht),
-        "montantTva": montant(montant_tva),
-        "categorie": categorie,
+        "taxableAmount": amount(base_amount_excl_tax),
+        "vatAmount": amount(vat_amount),
+        "category": category,
     }
-    # Soit taux (code) soit taux_manuel (valeur)
-    if taux is not None:
-        result["taux"] = taux
-    elif taux_manuel is not None:
-        result["tauxManuel"] = montant(taux_manuel)
+    # Either rate_code (code) or rate_value (value)
+    if rate_code is not None:
+        result["rate"] = rate_code
+    elif rate_value is not None:
+        result["manualRate"] = amount(rate_value)
     return result
 
 
-def adresse_postale(
-    ligne1: str,
-    code_postal: str,
-    ville: str,
-    pays: str = "FR",
-    ligne2: Optional[str] = None,
-    ligne3: Optional[str] = None,
+def postal_address(
+    line1: str,
+    postal_code: str,
+    city: str,
+    country: str = "FR",
+    line2: Optional[str] = None,
+    line3: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Crée une adresse postale pour l'API FactPulse.
+    """Create a postal address for the FactPulse API.
 
     Args:
-        ligne1: Première ligne d'adresse (numéro, rue)
-        code_postal: Code postal
-        ville: Nom de la ville
-        pays: Code pays ISO (défaut: "FR")
-        ligne2: Deuxième ligne d'adresse (optionnel)
-        ligne3: Troisième ligne d'adresse (optionnel)
+        line1: First address line (number, street)
+        postal_code: Postal code
+        city: City name
+        country: ISO country code (default: "FR")
+        line2: Second address line (optional)
+        line3: Third address line (optional)
 
     Example:
-        >>> adresse = adresse_postale("123 rue Example", "75001", "Paris")
+        >>> address = postal_address("123 Example Street", "75001", "Paris")
     """
     result = {
-        "ligneUn": ligne1,
-        "codePostal": code_postal,
-        "nomVille": ville,
-        "paysCodeIso": pays,
+        "lineOne": line1,
+        "postalCode": postal_code,
+        "city": city,
+        "countryCode": country,
     }
-    if ligne2:
-        result["ligneDeux"] = ligne2
-    if ligne3:
-        result["ligneTrois"] = ligne3
+    if line2:
+        result["lineTwo"] = line2
+    if line3:
+        result["lineThree"] = line3
     return result
 
 
-def adresse_electronique(
-    identifiant: str,
+def electronic_address(
+    identifier: str,
     scheme_id: str = "0009",
 ) -> Dict[str, Any]:
-    """Crée une adresse électronique pour l'API FactPulse.
+    """Create an electronic address for the FactPulse API.
 
     Args:
-        identifiant: Identifiant de l'adresse (SIRET, SIREN, etc.)
-        scheme_id: Schéma d'identification (défaut: "0009" pour SIREN)
+        identifier: Address identifier (SIRET, SIREN, etc.)
+        scheme_id: Identification scheme (default: "0009" for SIREN)
             - "0009": SIREN
             - "0088": EAN
             - "0096": DUNS
-            - "0130": Codification propre
-            - "0225": FR - SIRET (schéma français)
+            - "0130": Custom coding
+            - "0225": FR - SIRET (French scheme)
 
     Example:
-        >>> adresse = adresse_electronique("12345678901234", "0225")  # SIRET
+        >>> address = electronic_address("12345678901234", "0225")  # SIRET
     """
     return {
-        "identifiant": identifiant,
+        "identifier": identifier,
         "schemeId": scheme_id,
     }
 
 
-def fournisseur(
-    nom: str,
+def supplier(
+    name: str,
     siret: str,
-    adresse_ligne1: str,
-    code_postal: str,
-    ville: str,
-    id_fournisseur: int = 0,
+    address_line1: str,
+    postal_code: str,
+    city: str,
+    supplier_id: int = 0,
     siren: Optional[str] = None,
-    numero_tva_intra: Optional[str] = None,
+    vat_number: Optional[str] = None,
     iban: Optional[str] = None,
-    pays: str = "FR",
-    adresse_ligne2: Optional[str] = None,
-    code_service: Optional[int] = None,
-    code_coordonnees_bancaires: Optional[int] = None,
+    country: str = "FR",
+    address_line2: Optional[str] = None,
+    service_code: Optional[int] = None,
+    bank_details_code: Optional[int] = None,
 ) -> Dict[str, Any]:
-    """Crée un fournisseur (émetteur de la facture) pour l'API FactPulse.
+    """Create a supplier (invoice issuer) for the FactPulse API.
 
-    Cette fonction simplifie la création d'un fournisseur en générant automatiquement:
-    - L'adresse postale structurée
-    - L'adresse électronique (basée sur le SIRET)
-    - Le SIREN (extrait du SIRET si non fourni)
-    - Le numéro de TVA intracommunautaire (calculé depuis le SIREN si non fourni)
+    This function simplifies supplier creation by automatically generating:
+    - Structured postal address
+    - Electronic address (based on SIRET)
+    - SIREN (extracted from SIRET if not provided)
+    - Intra-community VAT number (calculated from SIREN if not provided)
 
     Args:
-        nom: Raison sociale / dénomination
-        siret: Numéro SIRET (14 chiffres)
-        adresse_ligne1: Première ligne d'adresse
-        code_postal: Code postal
-        ville: Ville
-        id_fournisseur: ID Chorus Pro du fournisseur (défaut: 0)
-        siren: Numéro SIREN (9 chiffres) - calculé depuis SIRET si absent
-        numero_tva_intra: Numéro TVA intracommunautaire - calculé si absent
-        iban: IBAN pour le paiement
-        pays: Code pays ISO (défaut: "FR")
-        adresse_ligne2: Deuxième ligne d'adresse (optionnel)
-        code_service: ID du service fournisseur Chorus Pro (optionnel)
-        code_coordonnees_bancaires: Code coordonnées bancaires Chorus Pro (optionnel)
+        name: Company name / trade name
+        siret: SIRET number (14 digits)
+        address_line1: First address line
+        postal_code: Postal code
+        city: City
+        supplier_id: Chorus Pro supplier ID (default: 0)
+        siren: SIREN number (9 digits) - calculated from SIRET if absent
+        vat_number: Intra-community VAT number - calculated if absent
+        iban: IBAN for payment
+        country: ISO country code (default: "FR")
+        address_line2: Second address line (optional)
+        service_code: Chorus Pro supplier service ID (optional)
+        bank_details_code: Chorus Pro bank details code (optional)
 
     Returns:
-        Dict prêt à être utilisé dans une facture
+        Dict ready to be used in an invoice
 
     Example:
-        >>> f = fournisseur(
-        ...     nom="Ma Société SAS",
+        >>> s = supplier(
+        ...     name="My Company SAS",
         ...     siret="12345678900001",
-        ...     adresse_ligne1="123 Rue de la République",
-        ...     code_postal="75001",
-        ...     ville="Paris",
+        ...     address_line1="123 Republic Street",
+        ...     postal_code="75001",
+        ...     city="Paris",
         ...     iban="FR7630006000011234567890189",
         ... )
     """
-    # Auto-calcul SIREN depuis SIRET
+    # Auto-calculate SIREN from SIRET
     if not siren and len(siret) == 14:
         siren = siret[:9]
 
-    # Auto-calcul TVA intracommunautaire française
-    if not numero_tva_intra and siren and len(siren) == 9:
-        # Clé TVA = (12 + 3 * (SIREN % 97)) % 97
+    # Auto-calculate French intra-community VAT number
+    if not vat_number and siren and len(siren) == 9:
+        # VAT key = (12 + 3 * (SIREN % 97)) % 97
         try:
-            cle = (12 + 3 * (int(siren) % 97)) % 97
-            numero_tva_intra = f"FR{cle:02d}{siren}"
+            key = (12 + 3 * (int(siren) % 97)) % 97
+            vat_number = f"FR{key:02d}{siren}"
         except ValueError:
-            pass  # SIREN non numérique, on skip
+            pass  # Non-numeric SIREN, skip
 
     result: Dict[str, Any] = {
-        "nom": nom,
-        "idFournisseur": id_fournisseur,
+        "name": name,
+        "supplierId": supplier_id,
         "siret": siret,
-        "adresseElectronique": adresse_electronique(siret, "0225"),
-        "adressePostale": adresse_postale(adresse_ligne1, code_postal, ville, pays, adresse_ligne2),
+        "electronicAddress": electronic_address(siret, "0225"),
+        "postalAddress": postal_address(address_line1, postal_code, city, country, address_line2),
     }
 
     if siren:
         result["siren"] = siren
-    if numero_tva_intra:
-        result["numeroTvaIntra"] = numero_tva_intra
+    if vat_number:
+        result["vatNumber"] = vat_number
     if iban:
         result["iban"] = iban
-    if code_service:
-        result["idServiceFournisseur"] = code_service
-    if code_coordonnees_bancaires:
-        result["codeCoordonnesBancairesFournisseur"] = code_coordonnees_bancaires
+    if service_code:
+        result["supplierServiceId"] = service_code
+    if bank_details_code:
+        result["supplierBankDetailsCode"] = bank_details_code
 
     return result
 
 
-def destinataire(
-    nom: str,
+def recipient(
+    name: str,
     siret: str,
-    adresse_ligne1: str,
-    code_postal: str,
-    ville: str,
+    address_line1: str,
+    postal_code: str,
+    city: str,
     siren: Optional[str] = None,
-    pays: str = "FR",
-    adresse_ligne2: Optional[str] = None,
-    code_service_executant: Optional[str] = None,
+    country: str = "FR",
+    address_line2: Optional[str] = None,
+    service_code: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Crée un destinataire (client de la facture) pour l'API FactPulse.
+    """Create a recipient (invoice customer) for the FactPulse API.
 
-    Cette fonction simplifie la création d'un destinataire en générant automatiquement:
-    - L'adresse postale structurée
-    - L'adresse électronique (basée sur le SIRET)
-    - Le SIREN (extrait du SIRET si non fourni)
+    This function simplifies recipient creation by automatically generating:
+    - Structured postal address
+    - Electronic address (based on SIRET)
+    - SIREN (extracted from SIRET if not provided)
 
     Args:
-        nom: Raison sociale / dénomination
-        siret: Numéro SIRET (14 chiffres)
-        adresse_ligne1: Première ligne d'adresse
-        code_postal: Code postal
-        ville: Ville
-        siren: Numéro SIREN (9 chiffres) - calculé depuis SIRET si absent
-        pays: Code pays ISO (défaut: "FR")
-        adresse_ligne2: Deuxième ligne d'adresse (optionnel)
-        code_service_executant: Code du service destinataire (optionnel)
+        name: Company name / trade name
+        siret: SIRET number (14 digits)
+        address_line1: First address line
+        postal_code: Postal code
+        city: City
+        siren: SIREN number (9 digits) - calculated from SIRET if absent
+        country: ISO country code (default: "FR")
+        address_line2: Second address line (optional)
+        service_code: Recipient service code (optional)
 
     Returns:
-        Dict prêt à être utilisé dans une facture
+        Dict ready to be used in an invoice
 
     Example:
-        >>> d = destinataire(
-        ...     nom="Client SARL",
+        >>> r = recipient(
+        ...     name="Client SARL",
         ...     siret="98765432109876",
-        ...     adresse_ligne1="456 Avenue des Champs",
-        ...     code_postal="69001",
-        ...     ville="Lyon",
+        ...     address_line1="456 Champs Avenue",
+        ...     postal_code="69001",
+        ...     city="Lyon",
         ... )
     """
-    # Auto-calcul SIREN depuis SIRET
+    # Auto-calculate SIREN from SIRET
     if not siren and len(siret) == 14:
         siren = siret[:9]
 
     result: Dict[str, Any] = {
-        "nom": nom,
+        "name": name,
         "siret": siret,
-        "adresseElectronique": adresse_electronique(siret, "0225"),
-        "adressePostale": adresse_postale(adresse_ligne1, code_postal, ville, pays, adresse_ligne2),
+        "electronicAddress": electronic_address(siret, "0225"),
+        "postalAddress": postal_address(address_line1, postal_code, city, country, address_line2),
     }
 
     if siren:
         result["siren"] = siren
-    if code_service_executant:
-        result["codeServiceExecutant"] = code_service_executant
+    if service_code:
+        result["executingServiceCode"] = service_code
 
     return result
 
 
+def payee(
+    name: str,
+    siret: Optional[str] = None,
+    siren: Optional[str] = None,
+    iban: Optional[str] = None,
+    bic: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Create a payee (factor) for factoring.
+
+    The payee (BG-10 / PayeeTradeParty) is used when payment must be made
+    to a third party different from the supplier, typically a factor
+    (factoring company).
+
+    For factored invoices, you must also:
+    - Use a factored document type (393, 396, 501, 502, 472, 473)
+    - Add an ACC note with the assignment clause
+    - The payee's IBAN will be used for payment
+
+    Args:
+        name: Factor's company name (BT-59)
+        siret: Factor's SIRET number (BT-60, schemeID 0009) - 14 digits
+        siren: Factor's SIREN number (BT-61, schemeID 0002) - calculated from SIRET if absent
+        iban: Factor's IBAN - to receive payment
+        bic: Factor's bank BIC (optional)
+
+    Returns:
+        Dict ready to be used in a factored invoice
+
+    Example:
+        >>> # Simple factored invoice
+        >>> factor = payee(
+        ...     name="FACTOR SAS",
+        ...     siret="30000000700033",
+        ...     iban="FR76 3000 4000 0500 0012 3456 789",
+        ... )
+        >>> invoice = {
+        ...     "invoiceNumber": "INV-2025-001-FACT",
+        ...     "supplier": supplier(...),
+        ...     "recipient": recipient(...),
+        ...     "payee": factor,  # Factor receives payment
+        ...     "references": {
+        ...         "invoiceType": "393",  # Factored invoice
+        ...         ...
+        ...     },
+        ...     "notes": [
+        ...         {
+        ...             "content": "This receivable has been assigned to FACTOR SAS. Contract n. FACT-2025",
+        ...             "subjectCode": "ACC",  # Mandatory assignment code
+        ...         },
+        ...         ...
+        ...     ],
+        ...     ...
+        ... }
+
+    See Also:
+        - Factoring guide: docs/factoring_guide.md
+        - Factored document types: 393 (invoice), 396 (credit note), 501, 502, 472, 473
+        - ACC note: Mandatory factoring assignment clause
+    """
+    # Auto-calculate SIREN from SIRET
+    if not siren and siret and len(siret) == 14:
+        siren = siret[:9]
+
+    result: Dict[str, Any] = {
+        "name": name,
+    }
+
+    if siret:
+        result["siret"] = siret
+    if siren:
+        result["siren"] = siren
+    if iban:
+        result["iban"] = iban
+    if bic:
+        result["bic"] = bic
+
+    return result
+
+
+
+
 class FactPulseClient:
-    """Client simplifié pour l'API FactPulse.
+    """Simplified client for the FactPulse API.
 
-    Gère l'authentification JWT, le polling des tâches asynchrones,
-    et permet de configurer les credentials Chorus Pro / AFNOR à l'initialisation.
+    Handles JWT authentication, asynchronous task polling,
+    and allows configuring Chorus Pro / AFNOR credentials at initialization.
     """
 
     DEFAULT_API_URL = "https://factpulse.fr"
@@ -533,24 +614,24 @@ class FactPulseClient:
         self._api_client: Optional[ApiClient] = None
 
     def get_chorus_credentials_for_api(self) -> Optional[Dict[str, Any]]:
-        """Retourne les credentials Chorus Pro au format API."""
+        """Return Chorus Pro credentials in API format."""
         return self.chorus_credentials.to_dict() if self.chorus_credentials else None
 
     def get_afnor_credentials_for_api(self) -> Optional[Dict[str, Any]]:
-        """Retourne les credentials AFNOR au format API."""
+        """Return AFNOR credentials in API format."""
         return self.afnor_credentials.to_dict() if self.afnor_credentials else None
 
-    # Alias plus courts pour faciliter l'usage
+    # Shorter aliases for convenience
     def get_chorus_pro_credentials(self) -> Optional[Dict[str, Any]]:
-        """Alias pour get_chorus_credentials_for_api()."""
+        """Alias for get_chorus_credentials_for_api()."""
         return self.get_chorus_credentials_for_api()
 
     def get_afnor_credentials(self) -> Optional[Dict[str, Any]]:
-        """Alias pour get_afnor_credentials_for_api()."""
+        """Alias for get_afnor_credentials_for_api()."""
         return self.get_afnor_credentials_for_api()
 
     def _obtain_token(self) -> Dict[str, str]:
-        """Obtient un nouveau token JWT."""
+        """Obtain a new JWT token."""
         token_url = f"{self.api_url}/api/token/"
         payload = {"username": self.email, "password": self.password}
         if self.client_uid:
@@ -559,7 +640,7 @@ class FactPulseClient:
         try:
             response = requests.post(token_url, json=payload, timeout=30)
             response.raise_for_status()
-            logger.info("Token JWT obtenu pour %s", self.email)
+            logger.info("JWT token obtained for %s", self.email)
             return response.json()
         except requests.RequestException as e:
             error_detail = ""
@@ -568,12 +649,12 @@ class FactPulseClient:
                     error_detail = e.response.json().get("detail", str(e))
                 except Exception:
                     error_detail = str(e)
-            raise FactPulseAuthError(f"Impossible d'obtenir le token JWT: {error_detail or e}")
+            raise FactPulseAuthError(f"Unable to obtain JWT token: {error_detail or e}")
 
     def _refresh_access_token(self) -> str:
-        """Rafraîchit le token d'accès."""
+        """Refresh the access token."""
         if not self._refresh_token:
-            raise FactPulseAuthError("Aucun refresh token disponible")
+            raise FactPulseAuthError("No refresh token available")
 
         refresh_url = f"{self.api_url}/api/token/refresh/"
         try:
@@ -581,16 +662,16 @@ class FactPulseClient:
                 refresh_url, json={"refresh": self._refresh_token}, timeout=30
             )
             response.raise_for_status()
-            logger.info("Token rafraîchi avec succès")
+            logger.info("Token refreshed successfully")
             return response.json()["access"]
         except requests.RequestException:
-            logger.warning("Refresh échoué, ré-obtention d'un nouveau token")
+            logger.warning("Refresh failed, obtaining new token")
             tokens = self._obtain_token()
             self._refresh_token = tokens["refresh"]
             return tokens["access"]
 
     def ensure_authenticated(self, force_refresh: bool = False) -> None:
-        """S'assure que le client est authentifié."""
+        """Ensure the client is authenticated."""
         now = datetime.now()
 
         if force_refresh or not self._access_token or not self._token_expires_at or now >= self._token_expires_at:
@@ -608,30 +689,77 @@ class FactPulseClient:
             self._token_expires_at = now + timedelta(minutes=28)
 
     def reset_auth(self) -> None:
-        """Réinitialise l'authentification."""
+        """Reset authentication."""
         self._access_token = None
         self._refresh_token = None
         self._token_expires_at = None
         self._api_client = None
-        logger.info("Authentification réinitialisée")
+        logger.info("Authentication reset")
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        files: Optional[Dict] = None,
+        data: Optional[Dict] = None,
+        json_data: Optional[Dict] = None,
+    ) -> requests.Response:
+        """Perform an HTTP request to the FactPulse API.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: Relative endpoint (e.g., /processing/validate-pdf)
+            files: Files for multipart/form-data
+            data: Form data
+            json_data: JSON data
 
-    def get_traitement_api(self) -> TraitementFactureApi:
-        """Retourne l'API de traitement de factures."""
+        Returns:
+            API response
+
+        Raises:
+            FactPulseValidationError: On API error
+        """
+        self.ensure_authenticated()
+        url = f"{self.api_url}/api/v1{endpoint}"
+        headers = {"Authorization": f"Bearer {self._access_token}"}
+
+        try:
+            if files:
+                response = requests.request(method, url, files=files, data=data, headers=headers, timeout=60)
+            elif json_data:
+                response = requests.request(method, url, json=json_data, headers=headers, timeout=30)
+            else:
+                response = requests.request(method, url, data=data, headers=headers, timeout=30)
+        except requests.RequestException as e:
+            raise FactPulseValidationError(f"Network error: {e}")
+
+        if response.status_code >= 400:
+            try:
+                error_json = response.json()
+                error_msg = error_json.get("detail", error_json.get("errorMessage", str(error_json)))
+            except Exception:
+                error_msg = response.text or f"HTTP error {response.status_code}"
+            raise FactPulseValidationError(f"API error: {error_msg}")
+
+        return response
+
+    def get_processing_api(self) -> InvoiceProcessingApi:
+        """Return the invoice processing API."""
         self.ensure_authenticated()
         config = Configuration(host=f"{self.api_url}/api/facturation")
         config.access_token = self._access_token
         self._api_client = ApiClient(configuration=config)
-        return TraitementFactureApi(api_client=self._api_client)
+        return InvoiceProcessingApi(api_client=self._api_client)
 
     def poll_task(self, task_id: str, timeout: Optional[int] = None, interval: Optional[int] = None) -> Dict[str, Any]:
-        """Effectue un polling sur une tâche jusqu'à son achèvement."""
+        """Poll a task until completion."""
         timeout_ms = timeout or self.polling_timeout
         interval_ms = interval or self.polling_interval
 
         start_time = time.time() * 1000
         current_interval = float(interval_ms)
 
-        logger.info("Début du polling pour la tâche %s (timeout: %dms)", task_id, timeout_ms)
+        logger.info("Starting polling for task %s (timeout: %dms)", task_id, timeout_ms)
 
         while True:
             elapsed = (time.time() * 1000) - start_time
@@ -640,28 +768,28 @@ class FactPulseClient:
                 raise FactPulsePollingTimeout(task_id, timeout_ms)
 
             try:
-                logger.debug("Polling tâche %s (elapsed: %.0fms)...", task_id, elapsed)
-                api = self.get_traitement_api()
-                statut = api.obtenir_statut_tache_api_v1_traitement_taches_id_tache_statut_get(id_tache=task_id)
-                logger.debug("Réponse statut reçue: %s", statut)
+                logger.debug("Polling task %s (elapsed: %.0fms)...", task_id, elapsed)
+                api = self.get_processing_api()
+                status = api.get_task_status_api_v1_processing_tasks_task_id_status_get(task_id=task_id)
+                logger.debug("Status response received: %s", status)
 
-                status_value = statut.statut.value if hasattr(statut.statut, "value") else str(statut.statut)
-                logger.info("Tâche %s: statut=%s (%.0fms)", task_id, status_value, elapsed)
+                status_value = status.status.value if hasattr(status.status, "value") else str(status.status)
+                logger.info("Task %s: status=%s (%.0fms)", task_id, status_value, elapsed)
 
                 if status_value == "SUCCESS":
-                    logger.info("Tâche %s terminée avec succès", task_id)
-                    if statut.resultat:
-                        if hasattr(statut.resultat, "to_dict"):
-                            return statut.resultat.to_dict()
-                        return dict(statut.resultat)
+                    logger.info("Task %s completed successfully", task_id)
+                    if status.result:
+                        if hasattr(status.result, "to_dict"):
+                            return status.result.to_dict()
+                        return dict(status.result)
                     return {}
 
                 if status_value == "FAILURE":
-                    error_msg = "Erreur inconnue"
+                    error_msg = "Unknown error"
                     errors = []
-                    if statut.resultat:
-                        result = statut.resultat.to_dict() if hasattr(statut.resultat, "to_dict") else dict(statut.resultat)
-                        # Format AFNOR: errorMessage, details
+                    if status.result:
+                        result = status.result.to_dict() if hasattr(status.result, "to_dict") else dict(status.result)
+                        # AFNOR format: errorMessage, details
                         error_msg = result.get("errorMessage", error_msg)
                         for err in result.get("details", []):
                             errors.append(ValidationErrorDetail(
@@ -671,80 +799,80 @@ class FactPulseClient:
                                 source=err.get("source"),
                                 code=err.get("code"),
                             ))
-                    raise FactPulseValidationError(f"La tâche {task_id} a échoué: {error_msg}", errors)
+                    raise FactPulseValidationError(f"Task {task_id} failed: {error_msg}", errors)
 
             except (FactPulseValidationError, FactPulsePollingTimeout):
                 raise
             except Exception as e:
                 error_str = str(e)
-                logger.warning("Erreur lors du polling: %s", error_str)
+                logger.warning("Error during polling: %s", error_str)
 
-                # Rate limit (429) - attendre et réessayer avec backoff
+                # Rate limit (429) - wait and retry with backoff
                 if "429" in error_str:
                     wait_time = min(current_interval * 2, 30000)  # Max 30s
-                    logger.warning("Rate limit (429), attente de %.1fs avant retry...", wait_time / 1000)
+                    logger.warning("Rate limit (429), waiting %.1fs before retry...", wait_time / 1000)
                     time.sleep(wait_time / 1000)
                     current_interval = wait_time
                     continue
 
-                # Token expiré (401) - re-authentification
+                # Token expired (401) - re-authenticate
                 if "401" in error_str:
-                    logger.warning("Token expiré, re-authentification...")
+                    logger.warning("Token expired, re-authenticating...")
                     self.reset_auth()
                     continue
 
-                # Erreur serveur temporaire (502, 503, 504) - retry avec backoff
+                # Temporary server error (502, 503, 504) - retry with backoff
                 if any(code in error_str for code in ("502", "503", "504")):
                     wait_time = min(current_interval * 1.5, 15000)
-                    logger.warning("Erreur serveur temporaire, attente de %.1fs avant retry...", wait_time / 1000)
+                    logger.warning("Temporary server error, waiting %.1fs before retry...", wait_time / 1000)
                     time.sleep(wait_time / 1000)
                     current_interval = wait_time
                     continue
 
-                raise FactPulseValidationError(f"Erreur API: {e}")
+                raise FactPulseValidationError(f"API error: {e}")
 
             time.sleep(current_interval / 1000)
             current_interval = min(current_interval * 1.5, 10000)
 
-    def generer_facturx(
+    def generate_facturx(
         self,
-        facture_data: Union[Dict, str, Any],
+        invoice_data: Union[Dict, str, Any],
         pdf_source: Union[bytes, str, Path],
-        profil: str = "EN16931",
-        format_sortie: str = "pdf",
+        profile: str = "EN16931",
+        output_format: str = "pdf",
         sync: bool = True,
         timeout: Optional[int] = None,
     ) -> bytes:
-        """Génère une facture Factur-X.
+        """Generate a Factur-X invoice.
 
-        Accepte les données de facture sous plusieurs formes :
-        - Dict : dictionnaire Python (recommandé avec les helpers montant_total(), ligne_de_poste(), etc.)
-        - str : JSON sérialisé
-        - Modèle Pydantic : modèle généré par le SDK (sera converti via .to_dict())
+        Accepts invoice data in multiple forms:
+        - Dict: Python dictionary (recommended with helpers invoice_totals(), invoice_line(), etc.)
+        - str: Serialized JSON
+        - Pydantic model: SDK-generated model (will be converted via .to_dict())
 
         Args:
-            facture_data: Données de la facture (dict, JSON string, ou modèle Pydantic)
-            pdf_source: Chemin vers le PDF source, ou bytes du PDF
-            profil: Profil Factur-X (MINIMUM, BASIC, EN16931, EXTENDED)
-            format_sortie: Format de sortie (pdf, xml, both)
-            sync: Si True, attend la fin de la tâche et retourne le résultat
-            timeout: Timeout en ms pour le polling
+            invoice_data: Invoice data (dict, JSON string, or Pydantic model)
+            pdf_source: Path to source PDF, or PDF bytes
+            profile: Factur-X profile (MINIMUM, BASIC, EN16931, EXTENDED)
+            output_format: Output format (pdf, xml, both)
+            sync: If True, wait for task completion and return result
+            timeout: Polling timeout in ms
 
         Returns:
-            bytes: Contenu du fichier généré (PDF ou XML)
+            bytes: Generated file content (PDF or XML)
         """
-        # Conversion des données en JSON string (gère Decimal, datetime, etc.)
-        if isinstance(facture_data, str):
-            json_data = facture_data
-        elif isinstance(facture_data, dict):
-            json_data = json_dumps_safe(facture_data)
-        elif hasattr(facture_data, "to_dict"):
-            # Modèle Pydantic généré par le SDK
-            json_data = json_dumps_safe(facture_data.to_dict())
+        # Convert data to JSON string (handles Decimal, datetime, etc.)
+        if isinstance(invoice_data, str):
+            json_data = invoice_data
+        elif isinstance(invoice_data, dict):
+            json_data = json_dumps_safe(invoice_data)
+        elif hasattr(invoice_data, "to_dict"):
+            # Pydantic model generated by SDK
+            json_data = json_dumps_safe(invoice_data.to_dict())
         else:
-            raise FactPulseValidationError(f"Type de données non supporté: {type(facture_data)}")
+            raise FactPulseValidationError(f"Unsupported data type: {type(invoice_data)}")
 
-        # Préparation du PDF
+        # Prepare PDF
         if isinstance(pdf_source, (str, Path)):
             pdf_path = Path(pdf_source)
             pdf_bytes = pdf_path.read_bytes()
@@ -753,40 +881,101 @@ class FactPulseClient:
             pdf_bytes = pdf_source
             pdf_filename = "source.pdf"
 
-        # Envoi direct via requests (bypass des modèles Pydantic du SDK)
+        # Direct send via requests (bypass SDK Pydantic models)
         for attempt in range(self.max_retries + 1):
             self.ensure_authenticated()
             try:
-                url = f"{self.api_url}/api/v1/traitement/generer-facture"
+                url = f"{self.api_url}/api/v1/processing/generate-invoice"
                 files = {
-                    "donnees_facture": (None, json_data, "application/json"),
-                    "profil": (None, profil),
-                    "format_sortie": (None, format_sortie),
+                    "invoice_data": (None, json_data, "application/json"),
+                    "profile": (None, profile),
+                    "output_format": (None, output_format),
                     "source_pdf": (pdf_filename, pdf_bytes, "application/pdf"),
                 }
                 headers = {"Authorization": f"Bearer {self._access_token}"}
                 response = requests.post(url, files=files, headers=headers, timeout=60)
 
                 if response.status_code == 401 and attempt < self.max_retries:
-                    logger.warning("Erreur 401, réinitialisation du token (tentative %d/%d)", attempt + 1, self.max_retries + 1)
+                    logger.warning("Error 401, resetting token (attempt %d/%d)", attempt + 1, self.max_retries + 1)
                     self.reset_auth()
                     continue
 
-                response.raise_for_status()
+                # Handle HTTP errors with response body extraction
+                if response.status_code >= 400:
+                    error_body = None
+                    try:
+                        error_body = response.json()
+                    except Exception:
+                        error_body = {"detail": response.text or f"HTTP {response.status_code}"}
+
+                    # Detailed error logging
+                    logger.error("API error %d: %s", response.status_code, error_body)
+
+                    # Extract error details in standardized format
+                    errors = []
+                    error_msg = f"HTTP error {response.status_code}"
+
+                    if isinstance(error_body, dict):
+                        # FastAPI/Pydantic format: {"detail": [{"loc": [...], "msg": "...", "type": "..."}]}
+                        if "detail" in error_body:
+                            detail = error_body["detail"]
+                            if isinstance(detail, list):
+                                # Pydantic validation error list
+                                error_msg = "Validation error"
+                                for err in detail:
+                                    if isinstance(err, dict):
+                                        loc = err.get("loc", [])
+                                        loc_str = " -> ".join(str(l) for l in loc) if loc else ""
+                                        errors.append(ValidationErrorDetail(
+                                            level="ERROR",
+                                            item=loc_str,
+                                            reason=err.get("msg", str(err)),
+                                            source="validation",
+                                            code=err.get("type"),
+                                        ))
+                            elif isinstance(detail, str):
+                                error_msg = detail
+                        # AFNOR format: {"errorMessage": "...", "details": [...]}
+                        elif "errorMessage" in error_body:
+                            error_msg = error_body["errorMessage"]
+                            for err in error_body.get("details", []):
+                                errors.append(ValidationErrorDetail(
+                                    level=err.get("level", "ERROR"),
+                                    item=err.get("item", ""),
+                                    reason=err.get("reason", ""),
+                                    source=err.get("source"),
+                                    code=err.get("code"),
+                                ))
+
+                    # For 422 errors (validation), don't retry
+                    if response.status_code == 422:
+                        raise FactPulseValidationError(error_msg, errors)
+
+                    # For other client errors (4xx), don't retry either
+                    if 400 <= response.status_code < 500:
+                        raise FactPulseValidationError(error_msg, errors)
+
+                    # For server errors (5xx), retry if possible
+                    if attempt < self.max_retries:
+                        logger.warning("Server error %d (attempt %d/%d)", response.status_code, attempt + 1, self.max_retries + 1)
+                        continue
+                    raise FactPulseValidationError(error_msg, errors)
+
                 result = response.json()
-                task_id = result.get("id_tache")
+                # API returns camelCase: taskId (or snake_case for backwards compat)
+                task_id = result.get("taskId") or result.get("task_id")
 
                 if not task_id:
-                    raise FactPulseValidationError("Pas d'ID de tâche dans la réponse")
+                    raise FactPulseValidationError("No task ID in response")
 
                 if not sync:
                     return task_id.encode()
 
                 poll_result = self.poll_task(task_id, timeout)
 
-                if poll_result.get("statut") == "ERREUR":
-                    # Format AFNOR: errorMessage, details
-                    error_msg = poll_result.get("errorMessage", "Erreur de validation")
+                if poll_result.get("status") == "ERROR":
+                    # AFNOR format: errorMessage, details
+                    error_msg = poll_result.get("errorMessage", "Validation error")
                     errors = [
                         ValidationErrorDetail(
                             level=e.get("level", ""),
@@ -799,71 +988,74 @@ class FactPulseClient:
                     ]
                     raise FactPulseValidationError(error_msg, errors)
 
-                if "contenu_b64" in poll_result:
-                    return base64.b64decode(poll_result["contenu_b64"])
+                if "content_b64" in poll_result:
+                    return base64.b64decode(poll_result["content_b64"])
 
-                raise FactPulseValidationError("Le résultat ne contient pas de contenu")
+                raise FactPulseValidationError("Result does not contain content")
 
             except requests.RequestException as e:
+                # Network errors (connection, timeout, etc.) - no HTTP error
                 if attempt < self.max_retries:
-                    logger.warning("Erreur réseau (tentative %d/%d): %s", attempt + 1, self.max_retries + 1, e)
+                    logger.warning("Network error (attempt %d/%d): %s", attempt + 1, self.max_retries + 1, e)
                     continue
-                raise FactPulseValidationError(f"Erreur API: {e}")
+                raise FactPulseValidationError(f"Network error: {e}")
+
+        raise FactPulseValidationError("Failed after all attempts")
 
-        raise FactPulseValidationError("Échec après toutes les tentatives")
 
     @staticmethod
-    def format_montant(montant) -> str:
-        """Formate un montant pour l'API FactPulse."""
-        if montant is None:
+    def format_amount(value) -> str:
+        """Format an amount for the FactPulse API."""
+        if value is None:
             return "0.00"
-        if isinstance(montant, Decimal):
-            return f"{montant:.2f}"
-        if isinstance(montant, (int, float)):
-            return f"{montant:.2f}"
-        if isinstance(montant, str):
-            return montant
+        if isinstance(value, Decimal):
+            return f"{value:.2f}"
+        if isinstance(value, (int, float)):
+            return f"{value:.2f}"
+        if isinstance(value, str):
+            return value
         return "0.00"
 
     # =========================================================================
     # AFNOR PDP/PA - Flow Service
     # =========================================================================
     #
-    # ARCHITECTURE GRAVÉE DANS LE MARBRE - NE PAS MODIFIER SANS COMPRENDRE
+    # ARCHITECTURE SET IN STONE - DO NOT MODIFY WITHOUT UNDERSTANDING
     #
-    # Le proxy AFNOR est 100% TRANSPARENT. Il a le même OpenAPI que l'AFNOR.
-    # Le SDK doit TOUJOURS :
-    # 1. Obtenir les credentials AFNOR (mode stored: via /credentials, mode zero-trust: fournis)
-    # 2. Faire l'OAuth AFNOR lui-même
-    # 3. Appeler les endpoints avec le token AFNOR + header X-PDP-Base-URL
+    # The AFNOR proxy is 100% TRANSPARENT. It has the same OpenAPI as AFNOR.
+    # The SDK must ALWAYS:
+    # 1. Obtain AFNOR credentials (stored mode: via /credentials, zero-trust mode: provided)
+    # 2. Perform AFNOR OAuth itself
+    # 3. Call endpoints with AFNOR token + X-PDP-Base-URL header
     #
-    # Le token JWT FactPulse n'est JAMAIS utilisé pour appeler la PDP !
+    # The FactPulse JWT token is NEVER used to call the PDP!
+    # It's only used to retrieve credentials in stored mode.
     # =========================================================================
 
     def _get_afnor_credentials(self) -> "AFNORCredentials":
-        """Obtient les credentials AFNOR (mode stored ou zero-trust).
+        """Obtain AFNOR credentials (stored or zero-trust mode).
 
-        **Mode zero-trust** : Retourne les afnor_credentials fournis au constructeur.
-        **Mode stored** : Récupère les credentials via GET /api/v1/afnor/credentials.
+        **Zero-trust mode**: Returns afnor_credentials provided to constructor.
+        **Stored mode**: Retrieves credentials via GET /api/v1/afnor/credentials.
 
         Returns:
-            AFNORCredentials avec flow_service_url, token_url, client_id, client_secret
+            AFNORCredentials with flow_service_url, token_url, client_id, client_secret
 
         Raises:
-            FactPulseAuthError: Si pas de credentials disponibles
-            FactPulseServiceUnavailableError: Si le serveur est indisponible
+            FactPulseAuthError: If no credentials available
+            FactPulseServiceUnavailableError: If server is unavailable
         """
         from .exceptions import FactPulseServiceUnavailableError
 
-        # Mode zero-trust : credentials fournis au constructeur
+        # Zero-trust mode: credentials provided to constructor
         if self.afnor_credentials:
-            logger.info("Mode zero-trust: utilisation des AFNORCredentials fournis")
+            logger.info("Zero-trust mode: using provided AFNORCredentials")
             return self.afnor_credentials
 
-        # Mode stored : récupérer les credentials via l'API
-        logger.info("Mode stored: récupération des credentials via /api/v1/afnor/credentials")
+        # Stored mode: retrieve credentials via API
+        logger.info("Stored mode: retrieving credentials via /api/v1/afnor/credentials")
 
-        self.ensure_authenticated()  # S'assurer qu'on a un token JWT FactPulse
+        self.ensure_authenticated()  # Ensure we have a FactPulse JWT token
 
         url = f"{self.api_url}/api/v1/afnor/credentials"
         headers = {"Authorization": f"Bearer {self._access_token}"}
@@ -878,12 +1070,12 @@ class FactPulseClient:
             error_detail = error_json.get("detail", {})
             if isinstance(error_detail, dict) and error_detail.get("error") == "NO_CLIENT_UID":
                 raise FactPulseAuthError(
-                    "Aucun client_uid dans le JWT. "
-                    "Pour utiliser les endpoints AFNOR, soit :\n"
-                    "1. Générez un token avec un client_uid (mode stored)\n"
-                    "2. Fournissez AFNORCredentials au constructeur du client (mode zero-trust)"
+                    "No client_uid in JWT. "
+                    "To use AFNOR endpoints, either:\n"
+                    "1. Generate a token with a client_uid (stored mode)\n"
+                    "2. Provide AFNORCredentials to the client constructor (zero-trust mode)"
                 )
-            raise FactPulseAuthError(f"Erreur credentials AFNOR: {error_detail}")
+            raise FactPulseAuthError(f"AFNOR credentials error: {error_detail}")
 
         if response.status_code != 200:
             try:
@@ -891,12 +1083,12 @@ class FactPulseClient:
                 error_msg = error_json.get("detail", str(error_json))
             except Exception:
                 error_msg = response.text or f"HTTP {response.status_code}"
-            raise FactPulseAuthError(f"Échec récupération credentials AFNOR: {error_msg}")
+            raise FactPulseAuthError(f"Failed to retrieve AFNOR credentials: {error_msg}")
 
         creds = response.json()
-        logger.info(f"Credentials AFNOR récupérés pour PDP: {creds.get('flow_service_url')}")
+        logger.info(f"AFNOR credentials retrieved for PDP: {creds.get('flow_service_url')}")
 
-        # Créer un AFNORCredentials temporaire
+        # Create temporary AFNORCredentials
         return AFNORCredentials(
             flow_service_url=creds["flow_service_url"],
             token_url=creds["token_url"],
@@ -905,27 +1097,27 @@ class FactPulseClient:
         )
 
     def _get_afnor_token_and_url(self) -> Tuple[str, str]:
-        """Obtient le token OAuth2 AFNOR et l'URL de la PDP.
+        """Obtain AFNOR OAuth2 token and PDP URL.
 
-        Cette méthode :
-        1. Récupère les credentials AFNOR (mode stored ou zero-trust)
-        2. Fait l'OAuth AFNOR pour obtenir un token
-        3. Retourne le token et l'URL de la PDP
+        This method:
+        1. Retrieves AFNOR credentials (stored or zero-trust mode)
+        2. Performs AFNOR OAuth to obtain a token
+        3. Returns the token and PDP URL
 
         Returns:
             Tuple (afnor_token, pdp_base_url)
 
         Raises:
-            FactPulseAuthError: Si l'authentification échoue
-            FactPulseServiceUnavailableError: Si le service est indisponible
+            FactPulseAuthError: If authentication fails
+            FactPulseServiceUnavailableError: If service is unavailable
         """
         from .exceptions import FactPulseServiceUnavailableError
 
-        # Étape 1: Obtenir les credentials AFNOR
+        # Step 1: Get AFNOR credentials
         credentials = self._get_afnor_credentials()
 
-        # Étape 2: Faire l'OAuth AFNOR
-        logger.info(f"OAuth AFNOR vers: {credentials.token_url}")
+        # Step 2: Perform AFNOR OAuth
+        logger.info(f"AFNOR OAuth to: {credentials.token_url}")
 
         url = f"{self.api_url}/api/v1/afnor/oauth/token"
         oauth_data = {
@@ -948,15 +1140,15 @@ class FactPulseClient:
                 error_msg = error_json.get("detail", error_json.get("error", str(error_json)))
             except Exception:
                 error_msg = response.text or f"HTTP {response.status_code}"
-            raise FactPulseAuthError(f"Échec OAuth2 AFNOR: {error_msg}")
+            raise FactPulseAuthError(f"AFNOR OAuth2 failed: {error_msg}")
 
         token_data = response.json()
         afnor_token = token_data.get("access_token")
 
         if not afnor_token:
-            raise FactPulseAuthError("Réponse OAuth2 AFNOR invalide: access_token manquant")
+            raise FactPulseAuthError("Invalid AFNOR OAuth2 response: missing access_token")
 
-        logger.info("Token OAuth2 AFNOR obtenu avec succès")
+        logger.info("AFNOR OAuth2 token obtained successfully")
         return afnor_token, credentials.flow_service_url
 
     def _make_afnor_request(
@@ -967,54 +1159,54 @@ class FactPulseClient:
         files: Optional[Dict] = None,
         params: Optional[Dict] = None,
     ) -> requests.Response:
-        """Effectue une requête vers l'API AFNOR avec gestion d'auth et d'erreurs.
+        """Perform a request to the AFNOR API with auth and error handling.
 
         ================================================================================
-        ARCHITECTURE GRAVÉE DANS LE MARBRE
+        ARCHITECTURE SET IN STONE
         ================================================================================
 
-        Cette méthode :
-        1. Récupère les credentials AFNOR (mode stored: API, mode zero-trust: fournis)
-        2. Fait l'OAuth AFNOR pour obtenir un token AFNOR
-        3. Appelle l'endpoint avec :
-           - Authorization: Bearer {token_afnor}  ← TOKEN AFNOR, PAS JWT FACTPULSE !
-           - X-PDP-Base-URL: {url_pdp}  ← Pour que le proxy route vers la bonne PDP
+        This method:
+        1. Retrieves AFNOR credentials (stored mode: API, zero-trust mode: provided)
+        2. Performs AFNOR OAuth to obtain an AFNOR token
+        3. Calls the endpoint with:
+           - Authorization: Bearer {afnor_token}  <- AFNOR TOKEN, NOT FACTPULSE JWT!
+           - X-PDP-Base-URL: {pdp_url}  <- For proxy to route to correct PDP
 
-        Le token JWT FactPulse n'est JAMAIS utilisé pour appeler la PDP.
-        Il sert uniquement à récupérer les credentials en mode stored.
+        The FactPulse JWT token is NEVER used to call the PDP.
+        It's only used to retrieve credentials in stored mode.
 
         ================================================================================
 
         Args:
-            method: Méthode HTTP (GET, POST, etc.)
-            endpoint: Endpoint relatif (ex: /flow/v1/flows)
-            json_data: Données JSON (optionnel)
-            files: Fichiers multipart (optionnel)
-            params: Query params (optionnel)
+            method: HTTP method (GET, POST, etc.)
+            endpoint: Relative endpoint (e.g., /flow/v1/flows)
+            json_data: JSON data (optional)
+            files: Multipart files (optional)
+            params: Query params (optional)
 
         Returns:
-            Response de l'API
+            API response
 
         Raises:
-            FactPulseAuthError: Si 401 ou credentials manquants
-            FactPulseNotFoundError: Si 404
-            FactPulseServiceUnavailableError: Si 503
-            FactPulseValidationError: Si 400/422
-            FactPulseAPIError: Autres erreurs
+            FactPulseAuthError: If 401 or missing credentials
+            FactPulseNotFoundError: If 404
+            FactPulseServiceUnavailableError: If 503
+            FactPulseValidationError: If 400/422
+            FactPulseAPIError: Other errors
         """
         from .exceptions import (
             parse_api_error,
             FactPulseServiceUnavailableError,
         )
 
-        # Obtenir le token AFNOR et l'URL de la PDP
-        # (mode stored: récupère credentials via API, mode zero-trust: utilise credentials fournis)
+        # Get AFNOR token and PDP URL
+        # (stored mode: retrieves credentials via API, zero-trust mode: uses provided credentials)
         afnor_token, pdp_base_url = self._get_afnor_token_and_url()
 
         url = f"{self.api_url}/api/v1/afnor{endpoint}"
 
-        # TOUJOURS utiliser le token AFNOR + header X-PDP-Base-URL
-        # Le token JWT FactPulse n'est JAMAIS utilisé pour appeler la PDP !
+        # ALWAYS use AFNOR token + X-PDP-Base-URL header
+        # The FactPulse JWT token is NEVER used to call the PDP!
         headers = {
             "Authorization": f"Bearer {afnor_token}",
             "X-PDP-Base-URL": pdp_base_url,
@@ -1036,65 +1228,65 @@ class FactPulseClient:
             try:
                 error_json = response.json()
             except Exception:
-                error_json = {"errorMessage": response.text or f"Erreur HTTP {response.status_code}"}
+                error_json = {"errorMessage": response.text or f"HTTP error {response.status_code}"}
             raise parse_api_error(error_json, response.status_code)
 
         return response
 
-    def soumettre_facture_afnor(
+    def submit_invoice_afnor(
         self,
         flow_name: str,
         pdf_path: Optional[Union[str, Path]] = None,
         pdf_bytes: Optional[bytes] = None,
-        pdf_filename: str = "facture.pdf",
+        pdf_filename: str = "invoice.pdf",
         flow_syntax: str = "CII",
         flow_profile: str = "EN16931",
         tracking_id: Optional[str] = None,
         sha256: Optional[str] = None,
     ) -> Dict[str, Any]:
-        """Soumet une facture Factur-X à une PDP via l'API AFNOR.
+        """Submit a Factur-X invoice to a PDP via the AFNOR API.
 
-        L'authentification utilise soit le client_uid du JWT (mode stocké),
-        soit les afnor_credentials fournis au constructeur (mode zero-trust).
+        Authentication uses either the client_uid from JWT (stored mode),
+        or afnor_credentials provided to constructor (zero-trust mode).
 
         Args:
-            flow_name: Nom du flux (ex: "Facture FAC-2025-001")
-            pdf_path: Chemin vers le fichier PDF/A-3 (exclusif avec pdf_bytes)
-            pdf_bytes: Contenu PDF en bytes (exclusif avec pdf_path)
-            pdf_filename: Nom du fichier pour les bytes (défaut: "facture.pdf")
-            flow_syntax: Syntaxe du flux (CII ou UBL)
-            flow_profile: Profil Factur-X (MINIMUM, BASIC, EN16931, EXTENDED)
-            tracking_id: Identifiant de suivi métier (optionnel)
-            sha256: Empreinte SHA-256 du fichier (calculée auto si absent)
+            flow_name: Flow name (e.g., "Invoice INV-2025-001")
+            pdf_path: Path to PDF/A-3 file (exclusive with pdf_bytes)
+            pdf_bytes: PDF content as bytes (exclusive with pdf_path)
+            pdf_filename: Filename for bytes (default: "invoice.pdf")
+            flow_syntax: Flow syntax (CII or UBL)
+            flow_profile: Factur-X profile (MINIMUM, BASIC, EN16931, EXTENDED)
+            tracking_id: Business tracking identifier (optional)
+            sha256: SHA-256 hash of file (calculated automatically if absent)
 
         Returns:
-            Dict avec flowId, trackingId, status, sha256, etc.
+            Dict with flowId, trackingId, status, sha256, etc.
 
         Raises:
-            FactPulseValidationError: Si le PDF n'est pas valide
-            FactPulseServiceUnavailableError: Si la PDP est indisponible
-            ValueError: Si ni pdf_path ni pdf_bytes n'est fourni
+            FactPulseValidationError: If PDF is not valid
+            FactPulseServiceUnavailableError: If PDP is unavailable
+            ValueError: If neither pdf_path nor pdf_bytes is provided
 
         Example:
-            >>> # Avec un chemin de fichier
-            >>> result = client.soumettre_facture_afnor(
-            ...     flow_name="Facture FAC-2025-001",
-            ...     pdf_path="facture.pdf",
-            ...     tracking_id="FAC-2025-001",
+            >>> # With a file path
+            >>> result = client.submit_invoice_afnor(
+            ...     flow_name="Invoice INV-2025-001",
+            ...     pdf_path="invoice.pdf",
+            ...     tracking_id="INV-2025-001",
             ... )
             >>> print(result["flowId"])
 
-            >>> # Avec des bytes (ex: après génération Factur-X)
-            >>> result = client.soumettre_facture_afnor(
-            ...     flow_name="Facture FAC-2025-001",
+            >>> # With bytes (e.g., after Factur-X generation)
+            >>> result = client.submit_invoice_afnor(
+            ...     flow_name="Invoice INV-2025-001",
             ...     pdf_bytes=pdf_content,
-            ...     pdf_filename="FAC-2025-001.pdf",
-            ...     tracking_id="FAC-2025-001",
+            ...     pdf_filename="INV-2025-001.pdf",
+            ...     tracking_id="INV-2025-001",
             ... )
         """
         import hashlib
 
-        # Charger le PDF depuis le chemin si fourni
+        # Load PDF from path if provided
         filename = pdf_filename
         if pdf_path:
             pdf_path = Path(pdf_path)
@@ -1102,13 +1294,13 @@ class FactPulseClient:
             filename = pdf_path.name
 
         if not pdf_bytes:
-            raise ValueError("pdf_path ou pdf_bytes requis")
+            raise ValueError("pdf_path or pdf_bytes required")
 
-        # Calculer SHA-256 si non fourni
+        # Calculate SHA-256 if not provided
         if not sha256:
             sha256 = hashlib.sha256(pdf_bytes).hexdigest()
 
-        # Préparer flowInfo
+        # Prepare flowInfo
         flow_info = {
             "name": flow_name,
             "flowSyntax": flow_syntax,
@@ -1126,28 +1318,29 @@ class FactPulseClient:
         response = self._make_afnor_request("POST", "/flow/v1/flows", files=files)
         return response.json()
 
-    def rechercher_flux_afnor(
+
+    def search_flows_afnor(
         self,
         tracking_id: Optional[str] = None,
         status: Optional[str] = None,
         offset: int = 0,
         limit: int = 25,
     ) -> Dict[str, Any]:
-        """Recherche des flux de facturation AFNOR.
+        """Search AFNOR invoice flows.
 
         Args:
-            tracking_id: Filtrer par trackingId
-            status: Filtrer par status (submitted, processing, delivered, etc.)
-            offset: Index de début (pagination)
-            limit: Nombre max de résultats
+            tracking_id: Filter by trackingId
+            status: Filter by status (submitted, processing, delivered, etc.)
+            offset: Start index (pagination)
+            limit: Max number of results
 
         Returns:
-            Dict avec flows (liste), total, offset, limit
+            Dict with flows (list), total, offset, limit
 
         Example:
-            >>> results = client.rechercher_flux_afnor(tracking_id="FAC-2025-001")
-            >>> for flux in results["flows"]:
-            ...     print(flux["flowId"], flux["status"])
+            >>> results = client.search_flows_afnor(tracking_id="INV-2025-001")
+            >>> for flow in results["flows"]:
+            ...     print(flow["flowId"], flow["status"])
         """
         search_body = {
             "offset": offset,
@@ -1162,85 +1355,87 @@ class FactPulseClient:
         response = self._make_afnor_request("POST", "/flow/v1/flows/search", json_data=search_body)
         return response.json()
 
-    def telecharger_flux_afnor(self, flow_id: str) -> bytes:
-        """Télécharge le fichier PDF d'un flux AFNOR.
+
+    def download_flow_afnor(self, flow_id: str) -> bytes:
+        """Download the PDF file of an AFNOR flow.
 
         Args:
-            flow_id: Identifiant du flux (UUID)
+            flow_id: Flow identifier (UUID)
 
         Returns:
-            Contenu du fichier PDF
+            PDF file content
 
         Raises:
-            FactPulseNotFoundError: Si le flux n'existe pas
+            FactPulseNotFoundError: If flow doesn't exist
 
         Example:
-            >>> pdf_bytes = client.telecharger_flux_afnor("550e8400-e29b-41d4-a716-446655440000")
-            >>> with open("facture.pdf", "wb") as f:
+            >>> pdf_bytes = client.download_flow_afnor("550e8400-e29b-41d4-a716-446655440000")
+            >>> with open("invoice.pdf", "wb") as f:
             ...     f.write(pdf_bytes)
         """
         response = self._make_afnor_request("GET", f"/flow/v1/flows/{flow_id}")
         return response.content
 
-    def obtenir_facture_entrante_afnor(
+
+    def get_incoming_invoice_afnor(
         self,
         flow_id: str,
         include_document: bool = False,
     ) -> Dict[str, Any]:
-        """Récupère les métadonnées JSON d'un flux entrant (facture fournisseur).
+        """Retrieve JSON metadata of an incoming flow (supplier invoice).
 
-        Télécharge un flux entrant depuis la PDP AFNOR et extrait les métadonnées
-        de la facture vers un format JSON unifié. Supporte les formats Factur-X, CII et UBL.
+        Downloads an incoming flow from the AFNOR PDP and extracts invoice
+        metadata to a unified JSON format. Supports Factur-X, CII and UBL formats.
 
-        Note: Cet endpoint utilise l'authentification JWT FactPulse (pas OAuth AFNOR).
-        Le serveur FactPulse se charge d'appeler la PDP avec les credentials stockés.
+        Note: This endpoint uses FactPulse JWT authentication (not AFNOR OAuth).
+        The FactPulse server handles calling the PDP with stored credentials.
 
         Args:
-            flow_id: Identifiant du flux (UUID)
-            include_document: Si True, inclut le document original encodé en base64
+            flow_id: Flow identifier (UUID)
+            include_document: If True, include original document encoded in base64
 
         Returns:
-            Dict avec les métadonnées de la facture:
-                - flow_id: Identifiant du flux
-                - format_source: Format détecté (Factur-X, CII, UBL)
-                - ref_fournisseur: Numéro de facture fournisseur
-                - type_document: Code type (380=facture, 381=avoir, etc.)
-                - fournisseur: Dict avec nom, siret, numero_tva_intra
-                - site_facturation_nom: Nom du destinataire
-                - site_facturation_siret: SIRET du destinataire
-                - date_de_piece: Date de la facture (YYYY-MM-DD)
-                - date_reglement: Date d'échéance (YYYY-MM-DD)
-                - devise: Code devise (EUR, USD, etc.)
-                - montant_ht: Montant HT
-                - montant_tva: Montant TVA
-                - montant_ttc: Montant TTC
-                - document_base64: (si include_document=True) Document encodé
-                - document_content_type: (si include_document=True) Type MIME
-                - document_filename: (si include_document=True) Nom de fichier
+            Dict with invoice metadata:
+                - flow_id: Flow identifier
+                - source_format: Detected format (Factur-X, CII, UBL)
+                - supplier_reference: Supplier invoice number
+                - document_type: Type code (380=invoice, 381=credit note, etc.)
+                - supplier: Dict with name, siret, vat_number
+                - billing_site_name: Recipient name
+                - billing_site_siret: Recipient SIRET
+                - document_date: Invoice date (YYYY-MM-DD)
+                - due_date: Due date (YYYY-MM-DD)
+                - currency: Currency code (EUR, USD, etc.)
+                - total_excl_tax: Total excl. tax
+                - total_vat: VAT amount
+                - total_incl_tax: Total incl. tax
+                - document_base64: (if include_document=True) Encoded document
+                - document_content_type: (if include_document=True) MIME type
+                - document_filename: (if include_document=True) Filename
 
         Raises:
-            FactPulseNotFoundError: Si le flux n'existe pas
-            FactPulseValidationError: Si le format n'est pas supporté
+            FactPulseNotFoundError: If flow doesn't exist
+            FactPulseValidationError: If format is not supported
 
         Example:
-            >>> # Récupérer les métadonnées d'une facture entrante
-            >>> facture = client.obtenir_facture_entrante_afnor("550e8400-e29b-41d4-a716-446655440000")
-            >>> print(f"Fournisseur: {facture['fournisseur']['nom']}")
-            >>> print(f"Montant TTC: {facture['montant_ttc']} {facture['devise']}")
-
-            >>> # Avec le document original
-            >>> facture = client.obtenir_facture_entrante_afnor(flow_id, include_document=True)
-            >>> if facture.get('document_base64'):
+            >>> # Retrieve incoming invoice metadata
+            >>> invoice = client.get_incoming_invoice_afnor("550e8400-e29b-41d4-a716-446655440000")
+            >>> print(f"Supplier: {invoice['supplier']['name']}")
+            >>> print(f"Total incl. tax: {invoice['total_incl_tax']} {invoice['currency']}")
+
+            >>> # With original document
+            >>> invoice = client.get_incoming_invoice_afnor(flow_id, include_document=True)
+            >>> if invoice.get('document_base64'):
             ...     import base64
-            ...     pdf_bytes = base64.b64decode(facture['document_base64'])
-            ...     with open(facture['document_filename'], 'wb') as f:
+            ...     pdf_bytes = base64.b64decode(invoice['document_base64'])
+            ...     with open(invoice['document_filename'], 'wb') as f:
             ...         f.write(pdf_bytes)
         """
         from .exceptions import FactPulseNotFoundError, FactPulseServiceUnavailableError, parse_api_error
 
         self.ensure_authenticated()
 
-        url = f"{self.api_url}/api/v1/afnor/flux-entrants/{flow_id}"
+        url = f"{self.api_url}/api/v1/afnor/incoming-flows/{flow_id}"
         params = {}
         if include_document:
             params["include_document"] = "true"
@@ -1250,22 +1445,23 @@ class FactPulseClient:
         try:
             response = requests.get(url, headers=headers, params=params if params else None, timeout=60)
         except requests.RequestException as e:
-            raise FactPulseServiceUnavailableError("FactPulse AFNOR flux-entrants", e)
+            raise FactPulseServiceUnavailableError("FactPulse AFNOR incoming flows", e)
 
         if response.status_code >= 400:
             try:
                 error_json = response.json()
             except Exception:
-                error_json = {"detail": response.text or f"Erreur HTTP {response.status_code}"}
+                error_json = {"detail": response.text or f"HTTP error {response.status_code}"}
             raise parse_api_error(error_json, response.status_code)
 
         return response.json()
 
+
     def healthcheck_afnor(self) -> Dict[str, Any]:
-        """Vérifie la disponibilité du Flow Service AFNOR.
+        """Check AFNOR Flow Service availability.
 
         Returns:
-            Dict avec status et service
+            Dict with status and service
 
         Example:
             >>> status = client.healthcheck_afnor()
@@ -1285,16 +1481,16 @@ class FactPulseClient:
         json_data: Optional[Dict] = None,
         params: Optional[Dict] = None,
     ) -> requests.Response:
-        """Effectue une requête vers l'API Chorus Pro avec gestion d'auth et d'erreurs.
+        """Perform a request to the Chorus Pro API with auth and error handling.
 
         Args:
-            method: Méthode HTTP (GET, POST, etc.)
-            endpoint: Endpoint relatif (ex: /structures/rechercher)
-            json_data: Données JSON (optionnel)
-            params: Query params (optionnel)
+            method: HTTP method (GET, POST, etc.)
+            endpoint: Relative endpoint (e.g., /structures/rechercher)
+            json_data: JSON data (optional)
+            params: Query params (optional)
 
         Returns:
-            Response de l'API
+            API response
         """
         from .exceptions import (
             parse_api_error,
@@ -1306,7 +1502,7 @@ class FactPulseClient:
 
         headers = {"Authorization": f"Bearer {self._access_token}"}
 
-        # Ajouter credentials dans le body si mode zero-trust
+        # Add credentials to body if zero-trust mode
         if json_data is None:
             json_data = {}
         if self.chorus_credentials:
@@ -1323,371 +1519,398 @@ class FactPulseClient:
             try:
                 error_json = response.json()
             except Exception:
-                error_json = {"errorMessage": response.text or f"Erreur HTTP {response.status_code}"}
+                error_json = {"errorMessage": response.text or f"HTTP error {response.status_code}"}
             raise parse_api_error(error_json, response.status_code)
 
         return response
 
-    def rechercher_structure_chorus(
+    def search_structure_chorus(
         self,
-        identifiant_structure: Optional[str] = None,
-        raison_sociale: Optional[str] = None,
-        type_identifiant: str = "SIRET",
-        restreindre_privees: bool = True,
+        structure_identifier: Optional[str] = None,
+        company_name: Optional[str] = None,
+        identifier_type: str = "SIRET",
+        restrict_to_private: bool = True,
     ) -> Dict[str, Any]:
-        """Recherche des structures sur Chorus Pro.
+        """Search structures on Chorus Pro.
 
         Args:
-            identifiant_structure: SIRET ou SIREN de la structure
-            raison_sociale: Raison sociale (recherche partielle)
-            type_identifiant: Type d'identifiant (SIRET, SIREN, etc.)
-            restreindre_privees: Si True, limite aux structures privées
+            structure_identifier: Structure SIRET or SIREN
+            company_name: Company name (partial search)
+            identifier_type: Identifier type (SIRET, SIREN, etc.)
+            restrict_to_private: If True, limit to private structures
 
         Returns:
-            Dict avec liste_structures, total, code_retour, libelle
+            Dict with liste_structures, total, code_retour, libelle
 
         Example:
-            >>> result = client.rechercher_structure_chorus(identifiant_structure="12345678901234")
+            >>> result = client.search_structure_chorus(structure_identifier="12345678901234")
             >>> for struct in result["liste_structures"]:
             ...     print(struct["id_structure_cpp"], struct["designation_structure"])
         """
         body = {
-            "restreindre_structures_privees": restreindre_privees,
+            "restreindre_structures_privees": restrict_to_private,
         }
-        if identifiant_structure:
-            body["identifiant_structure"] = identifiant_structure
-        if raison_sociale:
-            body["raison_sociale_structure"] = raison_sociale
-        if type_identifiant:
-            body["type_identifiant_structure"] = type_identifiant
+        if structure_identifier:
+            body["identifiant_structure"] = structure_identifier
+        if company_name:
+            body["raison_sociale_structure"] = company_name
+        if identifier_type:
+            body["type_identifiant_structure"] = identifier_type
 
         response = self._make_chorus_request("POST", "/structures/rechercher", json_data=body)
         return response.json()
 
-    def consulter_structure_chorus(self, id_structure_cpp: int) -> Dict[str, Any]:
-        """Consulte les détails d'une structure Chorus Pro.
 
-        Retourne notamment les paramètres obligatoires pour soumettre une facture :
+    def get_structure_details_chorus(self, structure_cpp_id: int) -> Dict[str, Any]:
+        """Get details of a Chorus Pro structure.
+
+        Returns mandatory parameters for submitting an invoice:
         - code_service_doit_etre_renseigne
         - numero_ej_doit_etre_renseigne
 
         Args:
-            id_structure_cpp: ID Chorus Pro de la structure
+            structure_cpp_id: Chorus Pro structure ID
 
         Returns:
-            Dict avec les détails de la structure et ses paramètres
+            Dict with structure details and parameters
 
         Example:
-            >>> details = client.consulter_structure_chorus(12345)
+            >>> details = client.get_structure_details_chorus(12345)
             >>> if details["parametres"]["code_service_doit_etre_renseigne"]:
-            ...     print("Code service obligatoire")
+            ...     print("Service code required")
         """
-        body = {"id_structure_cpp": id_structure_cpp}
+        body = {"id_structure_cpp": structure_cpp_id}
         response = self._make_chorus_request("POST", "/structures/consulter", json_data=body)
         return response.json()
 
-    def obtenir_id_chorus_depuis_siret(
+    def get_chorus_id_from_siret(
         self,
         siret: str,
-        type_identifiant: str = "SIRET",
+        identifier_type: str = "SIRET",
     ) -> Dict[str, Any]:
-        """Obtient l'ID Chorus Pro d'une structure depuis son SIRET.
+        """Get Chorus Pro ID from SIRET.
 
-        Raccourci pratique pour obtenir l'id_structure_cpp avant de soumettre une facture.
+        Convenient shortcut to get id_structure_cpp before submitting an invoice.
 
         Args:
-            siret: Numéro SIRET ou SIREN
-            type_identifiant: Type d'identifiant (SIRET ou SIREN)
+            siret: SIRET or SIREN number
+            identifier_type: Identifier type (SIRET or SIREN)
 
         Returns:
-            Dict avec id_structure_cpp, designation_structure, message
+            Dict with id_structure_cpp, designation_structure, message
 
         Example:
-            >>> result = client.obtenir_id_chorus_depuis_siret("12345678901234")
+            >>> result = client.get_chorus_id_from_siret("12345678901234")
             >>> id_cpp = result["id_structure_cpp"]
             >>> if id_cpp > 0:
-            ...     print(f"Structure trouvée: {result['designation_structure']}")
+            ...     print(f"Structure found: {result['designation_structure']}")
         """
         body = {
             "siret": siret,
-            "type_identifiant": type_identifiant,
+            "type_identifiant": identifier_type,
         }
         response = self._make_chorus_request("POST", "/structures/obtenir-id-depuis-siret", json_data=body)
         return response.json()
 
-    def lister_services_structure_chorus(self, id_structure_cpp: int) -> Dict[str, Any]:
-        """Liste les services d'une structure Chorus Pro.
+    def list_structure_services_chorus(self, structure_cpp_id: int) -> Dict[str, Any]:
+        """List services of a Chorus Pro structure.
 
         Args:
-            id_structure_cpp: ID Chorus Pro de la structure
+            structure_cpp_id: Chorus Pro structure ID
 
         Returns:
-            Dict avec liste_services, total, code_retour, libelle
+            Dict with liste_services, total, code_retour, libelle
 
         Example:
-            >>> services = client.lister_services_structure_chorus(12345)
+            >>> services = client.list_structure_services_chorus(12345)
             >>> for svc in services["liste_services"]:
             ...     if svc["est_actif"]:
             ...         print(svc["code_service"], svc["libelle_service"])
         """
-        response = self._make_chorus_request("GET", f"/structures/{id_structure_cpp}/services")
+        response = self._make_chorus_request("GET", f"/structures/{structure_cpp_id}/services")
         return response.json()
 
-    def soumettre_facture_chorus(
+    def submit_invoice_chorus(
         self,
-        numero_facture: str,
-        date_facture: str,
-        date_echeance_paiement: str,
-        id_structure_cpp: int,
-        montant_ht_total: str,
-        montant_tva: str,
-        montant_ttc_total: str,
-        piece_jointe_principale_id: Optional[int] = None,
-        piece_jointe_principale_designation: str = "Facture",
-        code_service: Optional[str] = None,
-        numero_engagement: Optional[str] = None,
-        numero_bon_commande: Optional[str] = None,
-        numero_marche: Optional[str] = None,
-        commentaire: Optional[str] = None,
+        invoice_number: str,
+        invoice_date: str,
+        due_date: str,
+        structure_cpp_id: int,
+        total_excl_tax: str,
+        total_vat: str,
+        total_incl_tax: str,
+        main_attachment_id: Optional[int] = None,
+        main_attachment_name: str = "Invoice",
+        service_code: Optional[str] = None,
+        commitment_number: Optional[str] = None,
+        purchase_order_number: Optional[str] = None,
+        contract_number: Optional[str] = None,
+        comment: Optional[str] = None,
     ) -> Dict[str, Any]:
-        """Soumet une facture à Chorus Pro.
+        """Submit an invoice to Chorus Pro.
 
-        **Workflow complet** :
-        1. Obtenir l'id_structure_cpp via rechercher_structure_chorus()
-        2. Vérifier les paramètres obligatoires via consulter_structure_chorus()
-        3. Uploader le PDF via l'API /transverses/ajouter-fichier
-        4. Soumettre la facture avec cette méthode
+        **Complete workflow**:
+        1. Get id_structure_cpp via search_structure_chorus()
+        2. Check mandatory parameters via get_structure_details_chorus()
+        3. Upload PDF via /transverses/ajouter-fichier API
+        4. Submit invoice with this method
 
         Args:
-            numero_facture: Numéro de la facture
-            date_facture: Date de la facture (YYYY-MM-DD)
-            date_echeance_paiement: Date d'échéance (YYYY-MM-DD)
-            id_structure_cpp: ID Chorus Pro du destinataire
-            montant_ht_total: Montant HT total (ex: "1000.00")
-            montant_tva: Montant TVA (ex: "200.00")
-            montant_ttc_total: Montant TTC total (ex: "1200.00")
-            piece_jointe_principale_id: ID de la pièce jointe (optionnel)
-            piece_jointe_principale_designation: Désignation (défaut: "Facture")
-            code_service: Code service (si requis par la structure)
-            numero_engagement: Numéro d'engagement (si requis)
-            numero_bon_commande: Numéro de bon de commande
-            numero_marche: Numéro de marché
-            commentaire: Commentaire libre
+            invoice_number: Invoice number
+            invoice_date: Invoice date (YYYY-MM-DD)
+            due_date: Due date (YYYY-MM-DD)
+            structure_cpp_id: Chorus Pro recipient ID
+            total_excl_tax: Total excl. tax (e.g., "1000.00")
+            total_vat: VAT amount (e.g., "200.00")
+            total_incl_tax: Total incl. tax (e.g., "1200.00")
+            main_attachment_id: Attachment ID (optional)
+            main_attachment_name: Attachment name (default: "Invoice")
+            service_code: Service code (if required by structure)
+            commitment_number: Commitment number (if required)
+            purchase_order_number: Purchase order number
+            contract_number: Contract number
+            comment: Free comment
 
         Returns:
-            Dict avec identifiant_facture_cpp, numero_flux_depot, code_retour, libelle
+            Dict with identifiant_facture_cpp, numero_flux_depot, code_retour, libelle
 
         Example:
-            >>> result = client.soumettre_facture_chorus(
-            ...     numero_facture="FAC-2025-001",
-            ...     date_facture="2025-01-15",
-            ...     date_echeance_paiement="2025-02-15",
-            ...     id_structure_cpp=12345,
-            ...     montant_ht_total="1000.00",
-            ...     montant_tva="200.00",
-            ...     montant_ttc_total="1200.00",
+            >>> result = client.submit_invoice_chorus(
+            ...     invoice_number="INV-2025-001",
+            ...     invoice_date="2025-01-15",
+            ...     due_date="2025-02-15",
+            ...     structure_cpp_id=12345,
+            ...     total_excl_tax="1000.00",
+            ...     total_vat="200.00",
+            ...     total_incl_tax="1200.00",
             ... )
-            >>> print(f"Facture soumise: {result['identifiant_facture_cpp']}")
+            >>> print(f"Invoice submitted: {result['identifiant_facture_cpp']}")
         """
         body = {
-            "numero_facture": numero_facture,
-            "date_facture": date_facture,
-            "date_echeance_paiement": date_echeance_paiement,
-            "id_structure_cpp": id_structure_cpp,
-            "montant_ht_total": montant_ht_total,
-            "montant_tva": montant_tva,
-            "montant_ttc_total": montant_ttc_total,
+            "numero_facture": invoice_number,
+            "date_facture": invoice_date,
+            "date_echeance_paiement": due_date,
+            "id_structure_cpp": structure_cpp_id,
+            "montant_ht_total": total_excl_tax,
+            "montant_tva": total_vat,
+            "montant_ttc_total": total_incl_tax,
         }
-        if piece_jointe_principale_id:
-            body["piece_jointe_principale_id"] = piece_jointe_principale_id
-            body["piece_jointe_principale_designation"] = piece_jointe_principale_designation
-        if code_service:
-            body["code_service"] = code_service
-        if numero_engagement:
-            body["numero_engagement"] = numero_engagement
-        if numero_bon_commande:
-            body["numero_bon_commande"] = numero_bon_commande
-        if numero_marche:
-            body["numero_marche"] = numero_marche
-        if commentaire:
-            body["commentaire"] = commentaire
+        if main_attachment_id:
+            body["piece_jointe_principale_id"] = main_attachment_id
+            body["piece_jointe_principale_designation"] = main_attachment_name
+        if service_code:
+            body["code_service"] = service_code
+        if commitment_number:
+            body["numero_engagement"] = commitment_number
+        if purchase_order_number:
+            body["numero_bon_commande"] = purchase_order_number
+        if contract_number:
+            body["numero_marche"] = contract_number
+        if comment:
+            body["commentaire"] = comment
 
         response = self._make_chorus_request("POST", "/factures/soumettre", json_data=body)
         return response.json()
 
-    def consulter_facture_chorus(self, identifiant_facture_cpp: int) -> Dict[str, Any]:
-        """Consulte le statut d'une facture Chorus Pro.
+    def get_invoice_status_chorus(self, invoice_cpp_id: int) -> Dict[str, Any]:
+        """Get status of a Chorus Pro invoice.
 
         Args:
-            identifiant_facture_cpp: ID Chorus Pro de la facture
+            invoice_cpp_id: Chorus Pro invoice ID
 
         Returns:
-            Dict avec statut_courant, numero_facture, date_facture, montant_ttc_total, etc.
+            Dict with statut_courant, numero_facture, date_facture, montant_ttc_total, etc.
 
         Example:
-            >>> status = client.consulter_facture_chorus(12345)
-            >>> print(f"Statut: {status['statut_courant']['code']}")
+            >>> status = client.get_invoice_status_chorus(12345)
+            >>> print(f"Status: {status['statut_courant']['code']}")
         """
-        body = {"identifiant_facture_cpp": identifiant_facture_cpp}
+        body = {"identifiant_facture_cpp": invoice_cpp_id}
         response = self._make_chorus_request("POST", "/factures/consulter", json_data=body)
         return response.json()
 
     # ==================== AFNOR Directory ====================
 
-    def rechercher_siret_afnor(self, siret: str) -> Dict[str, Any]:
-        """Recherche une entreprise par SIRET dans l'annuaire AFNOR.
+    def search_siret_afnor(self, siret: str) -> Dict[str, Any]:
+        """Search a company by SIRET in the AFNOR directory.
 
         Args:
-            siret: Numéro SIRET (14 chiffres)
+            siret: SIRET number (14 digits)
 
         Returns:
-            Dict avec informations entreprise: raison_sociale, adresse, etc.
+            Dict with company info: company_name, address, etc.
 
         Example:
-            >>> result = client.rechercher_siret_afnor("12345678901234")
-            >>> print(f"Entreprise: {result['raison_sociale']}")
+            >>> result = client.search_siret_afnor("12345678901234")
+            >>> print(f"Company: {result['raison_sociale']}")
         """
         response = self._make_afnor_request("GET", f"/directory/siret/{siret}")
         return response.json()
 
-    def rechercher_siren_afnor(self, siren: str) -> Dict[str, Any]:
-        """Recherche une entreprise par SIREN dans l'annuaire AFNOR.
+
+    def search_siren_afnor(self, siren: str) -> Dict[str, Any]:
+        """Search a company by SIREN in the AFNOR directory.
 
         Args:
-            siren: Numéro SIREN (9 chiffres)
+            siren: SIREN number (9 digits)
 
         Returns:
-            Dict avec informations entreprise et liste des établissements
+            Dict with company info and list of establishments
 
         Example:
-            >>> result = client.rechercher_siren_afnor("123456789")
-            >>> for etab in result.get('etablissements', []):
-            ...     print(f"SIRET: {etab['siret']}")
+            >>> result = client.search_siren_afnor("123456789")
+            >>> for estab in result.get('etablissements', []):
+            ...     print(f"SIRET: {estab['siret']}")
         """
         response = self._make_afnor_request("GET", f"/directory/siren/{siren}")
         return response.json()
 
-    def lister_codes_routage_afnor(self, siren: str) -> List[Dict[str, Any]]:
-        """Liste les codes de routage disponibles pour un SIREN.
+
+    def list_routing_codes_afnor(self, siren: str) -> List[Dict[str, Any]]:
+        """List available routing codes for a SIREN.
 
         Args:
-            siren: Numéro SIREN (9 chiffres)
+            siren: SIREN number (9 digits)
 
         Returns:
-            Liste des codes de routage avec leurs paramètres
+            List of routing codes with their parameters
 
         Example:
-            >>> codes = client.lister_codes_routage_afnor("123456789")
+            >>> codes = client.list_routing_codes_afnor("123456789")
             >>> for code in codes:
             ...     print(f"Code: {code['code_routage']}")
         """
         response = self._make_afnor_request("GET", f"/directory/siren/{siren}/routing-codes")
         return response.json()
 
+
     # ==================== Validation ====================
 
-    def valider_pdf_facturx(
+    def validate_facturx_pdf(
         self,
         pdf_path: Optional[str] = None,
         pdf_bytes: Optional[bytes] = None,
-        profil: str = "EN16931"
+        profile: Optional[str] = None,
+        use_verapdf: bool = False,
     ) -> Dict[str, Any]:
-        """Valide un PDF Factur-X.
+        """Validate a Factur-X PDF.
 
         Args:
-            pdf_path: Chemin vers le fichier PDF (exclusif avec pdf_bytes)
-            pdf_bytes: Contenu PDF en bytes (exclusif avec pdf_path)
-            profil: Profil Factur-X attendu (MINIMUM, BASIC, EN16931, EXTENDED)
+            pdf_path: Path to PDF file (exclusive with pdf_bytes)
+            pdf_bytes: PDF content as bytes (exclusive with pdf_path)
+            profile: Expected Factur-X profile (MINIMUM, BASIC, EN16931, EXTENDED).
+                If None, profile is auto-detected from embedded XML.
+            use_verapdf: Enable strict PDF/A validation with VeraPDF (default: False).
+                - False: Fast metadata validation (~100ms)
+                - True: Strict ISO 19005 validation with 146+ rules (2-10s, recommended in production)
 
         Returns:
-            Dict avec: est_conforme (bool), erreurs (list), avertissements (list), profil_detecte
+            Dict with:
+                - is_compliant (bool): True if PDF is compliant
+                - xml_present (bool): True if Factur-X XML is embedded
+                - xml_compliant (bool): True if XML is valid according to Schematron
+                - detected_profile (str): Detected profile (MINIMUM, BASIC, EN16931, EXTENDED)
+                - xml_errors (list): XML validation errors
+                - pdfa_compliant (bool): True if PDF/A compliant
+                - pdfa_version (str): Detected PDF/A version (e.g., "PDF/A-3B")
+                - pdfa_validation_method (str): "metadata" or "verapdf"
+                - pdfa_errors (list): PDF/A compliance errors
 
         Example:
-            >>> result = client.valider_pdf_facturx("facture.pdf")
-            >>> if result['est_conforme']:
-            ...     print("PDF Factur-X valide!")
+            >>> # Validation with auto-detected profile
+            >>> result = client.validate_facturx_pdf("invoice.pdf")
+            >>> print(f"Detected profile: {result['detected_profile']}")
+
+            >>> # Strict validation with VeraPDF (recommended in production)
+            >>> result = client.validate_facturx_pdf("invoice.pdf", use_verapdf=True)
+            >>> if result['is_compliant']:
+            ...     print("Valid Factur-X PDF!")
             >>> else:
-            ...     for err in result['erreurs']:
-            ...         print(f"Erreur: {err}")
+            ...     for err in result.get('pdfa_errors', []):
+            ...         print(f"PDF/A error: {err}")
         """
         if pdf_path:
             with open(pdf_path, "rb") as f:
                 pdf_bytes = f.read()
         if not pdf_bytes:
-            raise ValueError("pdf_path ou pdf_bytes requis")
+            raise ValueError("pdf_path or pdf_bytes required")
 
-        files = {"fichier_pdf": ("facture.pdf", pdf_bytes, "application/pdf")}
-        data = {"profil": profil}
-        response = self._request("POST", "/traitement/valider-pdf-facturx", files=files, data=data)
+        files = {"pdf_file": ("invoice.pdf", pdf_bytes, "application/pdf")}
+        data: Dict[str, Any] = {"use_verapdf": str(use_verapdf).lower()}
+        if profile:
+            data["profile"] = profile
+        response = self._request("POST", "/processing/validate-facturx-pdf", files=files, data=data)
         return response.json()
 
-    def valider_signature_pdf(
+
+    def validate_pdf_signature(
         self,
         pdf_path: Optional[str] = None,
         pdf_bytes: Optional[bytes] = None
     ) -> Dict[str, Any]:
-        """Valide la signature d'un PDF signé.
+        """Validate the signature of a signed PDF.
 
         Args:
-            pdf_path: Chemin vers le fichier PDF signé
-            pdf_bytes: Contenu PDF en bytes
+            pdf_path: Path to signed PDF file
+            pdf_bytes: PDF content as bytes
 
         Returns:
-            Dict avec: is_signed (bool), signatures (list), etc.
+            Dict with: is_signed (bool), signatures (list), etc.
 
         Example:
-            >>> result = client.valider_signature_pdf("facture_signee.pdf")
+            >>> result = client.validate_pdf_signature("signed_invoice.pdf")
             >>> if result['is_signed']:
-            ...     print("PDF signé!")
+            ...     print("PDF is signed!")
             ...     for sig in result.get('signatures', []):
-            ...         print(f"Signé par: {sig.get('signer_cn')}")
+            ...         print(f"Signed by: {sig.get('signer_cn')}")
         """
         if pdf_path:
             with open(pdf_path, "rb") as f:
                 pdf_bytes = f.read()
         if not pdf_bytes:
-            raise ValueError("pdf_path ou pdf_bytes requis")
+            raise ValueError("pdf_path or pdf_bytes required")
 
-        files = {"fichier_pdf": ("document.pdf", pdf_bytes, "application/pdf")}
-        response = self._request("POST", "/traitement/valider-signature-pdf", files=files)
+        files = {"pdf_file": ("document.pdf", pdf_bytes, "application/pdf")}
+        response = self._request("POST", "/processing/validate-pdf-signature", files=files)
         return response.json()
 
+
     # ==================== Signature ====================
 
-    def signer_pdf(
+    def sign_pdf(
         self,
         pdf_path: Optional[str] = None,
         pdf_bytes: Optional[bytes] = None,
-        raison: Optional[str] = None,
-        localisation: Optional[str] = None,
+        reason: Optional[str] = None,
+        location: Optional[str] = None,
         contact: Optional[str] = None,
         use_pades_lt: bool = False,
         use_timestamp: bool = True,
         output_path: Optional[str] = None
     ) -> Union[bytes, str]:
-        """Signe un PDF avec le certificat configuré côté serveur.
+        """Sign a PDF with the server-side configured certificate.
 
-        Le certificat doit être préalablement configuré dans Django Admin
-        pour le client identifié par le client_uid du JWT.
+        The certificate must be pre-configured in Django Admin
+        for the client identified by the JWT client_uid.
 
         Args:
-            pdf_path: Chemin vers le PDF à signer
-            pdf_bytes: Contenu PDF en bytes
-            raison: Raison de la signature (optionnel)
-            localisation: Lieu de signature (optionnel)
-            contact: Email de contact (optionnel)
-            use_pades_lt: Activer PAdES-B-LT archivage long terme (défaut: False)
-            use_timestamp: Activer l'horodatage RFC 3161 (défaut: True)
-            output_path: Si fourni, sauvegarde le PDF signé à ce chemin
+            pdf_path: Path to PDF to sign
+            pdf_bytes: PDF content as bytes
+            reason: Signature reason (optional)
+            location: Signature location (optional)
+            contact: Contact email (optional)
+            use_pades_lt: Enable PAdES-B-LT for long-term archiving (default: False)
+            use_timestamp: Enable RFC 3161 timestamping (default: True)
+            output_path: If provided, save signed PDF to this path
 
         Returns:
-            bytes du PDF signé, ou chemin si output_path fourni
+            Signed PDF bytes, or path if output_path provided
 
         Example:
-            >>> pdf_signe = client.signer_pdf(
-            ...     pdf_path="facture.pdf",
-            ...     raison="Conformité Factur-X",
-            ...     output_path="facture_signee.pdf"
+            >>> signed_pdf = client.sign_pdf(
+            ...     pdf_path="invoice.pdf",
+            ...     reason="Factur-X Compliance",
+            ...     output_path="signed_invoice.pdf"
             ... )
         """
         if pdf_path:
@@ -1695,67 +1918,68 @@ class FactPulseClient:
                 pdf_bytes = f.read()
 
         if not pdf_bytes:
-            raise ValueError("pdf_path ou pdf_bytes requis")
+            raise ValueError("pdf_path or pdf_bytes required")
 
         files = {
-            "fichier_pdf": ("document.pdf", pdf_bytes, "application/pdf"),
+            "pdf_file": ("document.pdf", pdf_bytes, "application/pdf"),
         }
         data: Dict[str, Any] = {
             "use_pades_lt": str(use_pades_lt).lower(),
             "use_timestamp": str(use_timestamp).lower(),
         }
-        if raison:
-            data["raison"] = raison
-        if localisation:
-            data["localisation"] = localisation
+        if reason:
+            data["reason"] = reason
+        if location:
+            data["location"] = location
         if contact:
             data["contact"] = contact
 
-        response = self._request("POST", "/traitement/signer-pdf", files=files, data=data)
+        response = self._request("POST", "/processing/sign-pdf", files=files, data=data)
         result = response.json()
 
-        # L'API retourne du JSON avec pdf_signe_base64
-        pdf_signe_b64 = result.get("pdf_signe_base64")
-        if not pdf_signe_b64:
-            raise FactPulseValidationError("Réponse de signature invalide")
+        # API returns JSON with signed_pdf_base64
+        pdf_signed_b64 = result.get("signed_pdf_base64")
+        if not pdf_signed_b64:
+            raise FactPulseValidationError("Invalid signature response")
 
         import base64
-        pdf_signe = base64.b64decode(pdf_signe_b64)
+        pdf_signed = base64.b64decode(pdf_signed_b64)
 
         if output_path:
             with open(output_path, "wb") as f:
-                f.write(pdf_signe)
+                f.write(pdf_signed)
             return output_path
 
-        return pdf_signe
+        return pdf_signed
 
-    def generer_certificat_test(
+
+    def generate_test_certificate(
         self,
         cn: str = "Test Organisation",
         organisation: str = "Test Organisation",
         email: str = "test@example.com",
-        duree_jours: int = 365,
-        taille_cle: int = 2048,
+        validity_days: int = 365,
+        key_size: int = 2048,
     ) -> Dict[str, Any]:
-        """Génère un certificat de test pour la signature (NON PRODUCTION).
+        """Generate a test certificate for signing (NOT FOR PRODUCTION).
 
-        Le certificat généré doit ensuite être configuré dans Django Admin.
+        The generated certificate must then be configured in Django Admin.
 
         Args:
-            cn: Common Name du certificat
-            organisation: Nom de l'organisation
-            email: Email associé au certificat
-            duree_jours: Durée de validité en jours (défaut: 365)
-            taille_cle: Taille de la clé RSA (2048 ou 4096)
+            cn: Certificate Common Name
+            organisation: Organisation name
+            email: Email associated with certificate
+            validity_days: Validity duration in days (default: 365)
+            key_size: RSA key size (2048 or 4096)
 
         Returns:
-            Dict avec certificat_pem, cle_privee_pem, pkcs12_base64, etc.
+            Dict with certificat_pem, cle_privee_pem, pkcs12_base64, etc.
 
         Example:
-            >>> result = client.generer_certificat_test(
-            ...     cn="Ma Société - Cachet",
-            ...     organisation="Ma Société SAS",
-            ...     email="contact@masociete.fr",
+            >>> result = client.generate_test_certificate(
+            ...     cn="My Company - Seal",
+            ...     organisation="My Company SAS",
+            ...     email="contact@mycompany.com",
             ... )
             >>> print(result["certificat_pem"])
         """
@@ -1763,122 +1987,123 @@ class FactPulseClient:
             "cn": cn,
             "organisation": organisation,
             "email": email,
-            "duree_jours": duree_jours,
-            "taille_cle": taille_cle,
+            "validity_days": validity_days,
+            "key_size": key_size,
         }
-        response = self._request("POST", "/traitement/generer-certificat-test", json_data=data)
+        response = self._request("POST", "/processing/generate-test-certificate", json_data=data)
         return response.json()
 
-    # ==================== Workflow complet ====================
 
-    def generer_facturx_complet(
+    # ==================== Complete workflow ====================
+
+    def generate_complete_facturx(
         self,
-        facture: Dict[str, Any],
+        invoice: Dict[str, Any],
         pdf_source_path: Optional[str] = None,
         pdf_source_bytes: Optional[bytes] = None,
-        profil: str = "EN16931",
-        valider: bool = True,
-        signer: bool = False,
-        soumettre_afnor: bool = False,
+        profile: str = "EN16931",
+        validate: bool = True,
+        sign: bool = False,
+        submit_afnor: bool = False,
         afnor_flow_name: Optional[str] = None,
         afnor_tracking_id: Optional[str] = None,
         output_path: Optional[str] = None,
         timeout: int = 120000
     ) -> Dict[str, Any]:
-        """Génère un PDF Factur-X complet avec validation, signature et soumission optionnelles.
+        """Generate a complete Factur-X PDF with optional validation, signing and submission.
 
-        Cette méthode enchaîne automatiquement:
-        1. Génération du PDF Factur-X
-        2. Validation (optionnelle)
-        3. Signature (optionnelle, utilise le certificat côté serveur)
-        4. Soumission à la PDP AFNOR (optionnelle)
+        This method automatically chains:
+        1. Factur-X PDF generation
+        2. Validation (optional)
+        3. Signing (optional, uses server-side certificate)
+        4. AFNOR PDP submission (optional)
 
-        Note: La signature utilise le certificat configuré dans Django Admin
-        pour le client identifié par le client_uid du JWT.
+        Note: Signing uses the certificate configured in Django Admin
+        for the client identified by the JWT client_uid.
 
         Args:
-            facture: Données de la facture (format FactureFacturX)
-            pdf_source_path: Chemin vers le PDF source
-            pdf_source_bytes: PDF source en bytes
-            profil: Profil Factur-X (MINIMUM, BASIC, EN16931, EXTENDED)
-            valider: Si True, valide le PDF généré
-            signer: Si True, signe le PDF (certificat côté serveur)
-            soumettre_afnor: Si True, soumet le PDF à la PDP AFNOR
-            afnor_flow_name: Nom du flux AFNOR (défaut: "Facture {numero_facture}")
-            afnor_tracking_id: Tracking ID AFNOR (défaut: numero_facture)
-            output_path: Chemin de sortie pour le PDF final
-            timeout: Timeout en ms pour le polling
+            invoice: Invoice data (FactureFacturX format)
+            pdf_source_path: Path to source PDF
+            pdf_source_bytes: Source PDF as bytes
+            profile: Factur-X profile (MINIMUM, BASIC, EN16931, EXTENDED)
+            validate: If True, validate generated PDF
+            sign: If True, sign PDF (server-side certificate)
+            submit_afnor: If True, submit PDF to AFNOR PDP
+            afnor_flow_name: AFNOR flow name (default: "Invoice {invoice_number}")
+            afnor_tracking_id: AFNOR tracking ID (default: invoice_number)
+            output_path: Output path for final PDF
+            timeout: Polling timeout in ms
 
         Returns:
-            Dict avec:
-                - pdf_bytes: bytes du PDF final
-                - pdf_path: chemin si output_path fourni
-                - validation: résultat de validation si valider=True
-                - signature: infos signature si signer=True
-                - afnor: résultat soumission AFNOR si soumettre_afnor=True
+            Dict with:
+                - pdf_bytes: Final PDF bytes
+                - pdf_path: Path if output_path provided
+                - validation: Validation result if validate=True
+                - signature: Signature info if sign=True
+                - afnor: AFNOR submission result if submit_afnor=True
 
         Example:
-            >>> result = client.generer_facturx_complet(
-            ...     facture=ma_facture,
-            ...     pdf_source_path="devis.pdf",
-            ...     profil="EN16931",
-            ...     valider=True,
-            ...     signer=True,
-            ...     soumettre_afnor=True,
-            ...     output_path="facture_finale.pdf"
+            >>> result = client.generate_complete_facturx(
+            ...     invoice=my_invoice,
+            ...     pdf_source_path="quote.pdf",
+            ...     profile="EN16931",
+            ...     validate=True,
+            ...     sign=True,
+            ...     submit_afnor=True,
+            ...     output_path="final_invoice.pdf"
             ... )
-            >>> if result['validation']['valide']:
-            ...     print(f"Facture soumise! Flow ID: {result['afnor']['flowId']}")
+            >>> if result['validation']['is_compliant']:
+            ...     print(f"Invoice submitted! Flow ID: {result['afnor']['flowId']}")
         """
         result: Dict[str, Any] = {}
 
-        # 1. Génération
+        # 1. Generation
         if pdf_source_path:
             with open(pdf_source_path, "rb") as f:
                 pdf_source_bytes = f.read()
 
-        pdf_bytes = self.generer_facturx(
-            facture_data=facture,
+        pdf_bytes = self.generate_facturx(
+            invoice_data=invoice,
             pdf_source=pdf_source_bytes,
-            profil=profil,
+            profile=profile,
             timeout=timeout
         )
         result["pdf_bytes"] = pdf_bytes
 
         # 2. Validation
-        if valider:
-            validation = self.valider_pdf_facturx(pdf_bytes=pdf_bytes, profil=profil)
+        if validate:
+            validation = self.validate_facturx_pdf(pdf_bytes=pdf_bytes, profile=profile)
             result["validation"] = validation
-            if not validation.get("est_conforme", False):
-                # Retourne quand même le résultat mais avec les erreurs
+            if not validation.get("est_conforme", False) and not validation.get("is_compliant", False):
+                # Return result with errors
                 if output_path:
                     with open(output_path, "wb") as f:
                         f.write(pdf_bytes)
                     result["pdf_path"] = output_path
                 return result
 
-        # 3. Signature (utilise le certificat côté serveur)
-        if signer:
-            pdf_bytes = self.signer_pdf(pdf_bytes=pdf_bytes)
+        # 3. Signing (uses server-side certificate)
+        if sign:
+            pdf_bytes = self.sign_pdf(pdf_bytes=pdf_bytes)
             result["pdf_bytes"] = pdf_bytes
-            result["signature"] = {"signe": True}
+            result["signature"] = {"signed": True}
 
-        # 4. Soumission AFNOR
-        if soumettre_afnor:
-            numero_facture = facture.get("numeroFacture", facture.get("numero_facture", "FACTURE"))
-            flow_name = afnor_flow_name or f"Facture {numero_facture}"
-            tracking_id = afnor_tracking_id or numero_facture
+        # 4. AFNOR submission
+        if submit_afnor:
+            invoice_number = invoice.get("invoiceNumber", invoice.get("numeroFacture", invoice.get("numero_facture", "INVOICE")))
+            flow_name = afnor_flow_name or f"Invoice {invoice_number}"
+            tracking_id = afnor_tracking_id or invoice_number
 
-            # Soumission directe avec bytes (plus de fichier temporaire nécessaire)
-            afnor_result = self.soumettre_facture_afnor(
+            # Direct submission with bytes (no temp file needed)
+            afnor_result = self.submit_invoice_afnor(
                 flow_name=flow_name,
                 pdf_bytes=pdf_bytes,
-                pdf_filename=f"{numero_facture}.pdf",
+                pdf_filename=f"{invoice_number}.pdf",
                 tracking_id=tracking_id,
             )
             result["afnor"] = afnor_result
 
-        # Sauvegarde finale
+        # Final save
         if output_path:
             with open(output_path, "wb") as f:
                 f.write(pdf_bytes)