# Référence legacy : `public/trans/action_trans_bl.php`

Comportement de l'ancien endpoint d'intégration des BL envoyés par BHP, à comparer avec la partie BL de l'API `/transfert/{fiche}` (voir [api_transfert_bhp.md](api_transfert_bhp.md)).

Analyse faite sur la version du commit `3683f3df` (2026-11-17, « Action transBL pour bigbag »), 4021 lignes.

## 0. Changement récent

Le commit `3683f3df` a désactivé le calcul spécial des quantités pour la carrière (lignes 399-446, mises en commentaire). Avant ce commit, pour un granulat avec `produit_utiliser_masse_volumique_calcul_contribution=1` (bigbag), les quantités étaient multipliées par 10 (soit /100 puis ×1000). Désormais, **toutes les quantités sont divisées par 100**, quelle que soit l'activité.

## A. Entrée / sortie
- **A1.** L'appel est un GET avec `action=integration` ou `action=suppression`. La réponse est un JSON `{action, message, message_demat, message_pdf}`. Toute autre action renvoie `pas d'information`.
- **A2.** Le payload est plat : il contient des codes, pas des ids. Les valeurs passent par `_deserialize()`.
- **A3.** Le BL est stocké sous `bl_code = code_centrale (3 caractères, complété par des zéros) + numero_bl`.
- **A4.** Les flags booléens arrivent en `'O'`/autre, sauf `bl_prefa` et `bl_negoce`, qui arrivent en `'1'`.
- **A5.** Les quantités (`qte_livree`, `qte_origine`, `qte_acceptee`, `qte_reste`, `qte_jetee`, `qte_retour_beton`, `qte_serviceN`, `qte_adjN`) arrivent en centièmes et sont **toujours divisées par 100** (voir §0).
- **A6.** Une heure vide vaut `00:00`. `h_fab` n'est considérée vide que si elle vaut exactement 4 espaces.

## B. Résolution des codes
- **B1.** **Centrale** : si `ventilation=1`, on prend la centrale de substitution V2 (`centrale_substitution_v2_id`) quand elle existe. Le champ `activite_type` décide du mode : 0 = béton (BPE), 1 = carrière.
- **B2.** **Client**, puis **chantier** filtré sur le client, puis **adresse de facturation** du chantier, puis **zone**, **véhicule**, **chauffeur**, **spécificité**.
- **B3.** **Article principal** :
  - BPE → `t_formule` : type 0, unité M3, masse volumique = 1.
  - Carrière → `t_produit` : type 5, unité T. Si `produit_utiliser_masse_volumique_calcul_contribution=1`, l'unité devient U et la masse volumique vaut `produit_masse_volumique / 1000`. Cette masse volumique ne sert plus qu'au calcul des taxes (D7).
- **B4.** **Mode de transport** : lu dans le chantier, en version béton (`chantier_mode_transport`, `chantier_facture_transport_imcomplet`) ou granulat (`*_granulat`) selon l'activité.
- **B5.** **Commande** : avec `cmd_of` vide ou `N`, `code_commande` est un `commande_code`. Sinon, c'est un `id_planning` (OF existant), et la commande est lue au travers du planning.
- **B6.** `bl_utilisateur_creation` est lu dans `t_tracabilite` (action Création, feuille BL, même numéro sans préfixe centrale, même date).
- **B7.** **BL préfa** : client et chantier sont remplacés par `parametre_client_prefa` et `parametre_chantier_prefa`.
- **B8.** Valeurs fixes : `tva_id=0`, `classe_consisatnce_id=79`, `designation_beton_id=0`, `bl_civilite=''`. Le nom et l'adresse du BL viennent de l'adresse de facturation du chantier. Les champs `bl_client_*` et `bl_chantier_*` viennent du payload.

## C. Création ou modification
- **C1.** Le BL est absent → INSERT `t_bl`. Côté planning : INSERT `t_planning` si `cmd_of=N`, sinon UPDATE du planning `id_planning`.
- **C2.** Le BL existe → UPDATE `t_bl` et UPDATE `t_planning` (recherché par `numero_bl`), mais l'intégration est refusée dans les cas suivants (contrôles faits **avant** toute écriture) :
  - `parametre_integration_bl_modifie ≠ 1` ;
  - l'écart en jours dépasse `parametre_integration_bl_modifie_nb_jour` (quand ce paramètre est différent de 0) ;
  - le BL est en ventilation V2 alors que `parametre_ventilation_2 ≠ 1` ;
  - le BL est facturé ou porte `bl_non_modif_prod=1`.
- **C3.** **En modification :** une heure saisie manuellement (`bl_heure_*_type ≠ 0`) est conservée. Les champs `bl_mail_demat_envoye` et `bl_demat_mail_receptionniste` sont conservés aussi.
- **C4.** **En création seulement :** `commande_qte_restant` diminue de la quantité livrée et `commande_accepte` augmente d'autant. Si le reste est ≤ 0 et que la commande n'est pas un complément, la commande est soldée. Si en plus `parametre_cmd_envoyer_ordre=1`, une suppression `T_Commande` est envoyée vers BHP via `t_tracabilite_envoi`.

## D. Lignes du BL
- **D1.** On supprime toutes les lignes `ligne_bl_demat=0`, puis on les recrée. Les lignes démat sont conservées.
- **D2.** **Tarification de chaque ligne :**
  - calcul d'un niveau : 6 = commande (si `commande_utiliser_prix_commande`), 5 = chantier, 4 = client, 3 = sous-famille, 2 = groupe centrale, 1 = société ;
  - appel de `definir_prix()` ;
  - si le tarif est introuvable, on prend le prix de base. Sinon on applique la remise en %, ou le tarif différentiel (`type_tarif=1` : prix de base − valeur). Avec `type_tarif=0`, aucune remise n'est appliquée ;
  - `ligne_bl_origine` reçoit Commande, Chantier, client, /S f.client, g.centrale, Sociéte ou p.base. On a `ligne_bl_prix_commande=1` si l'origine est la commande ;
  - le prix n'est jamais forcé (`prix_force=0`) ;
  - **exceptions** : le transport incomplet et les taxes automatiques n'utilisent jamais le niveau 6 (ni le code commande). Voir aussi H7.
- **D3.** **Ligne formule ou granulat** (type 0 ou 5) : quantité livrée, facturable si `beton_facturable`. C'est la seule insertion dont l'erreur est vérifiée (arrêt avec le message SQL).
- **D4.** **Ligne zone (type 4)** :
  - mode au m³ → prix `zone_prix_m3` et quantité livrée ;
  - mode au voyage → prix `zone_prix_m3_voyage` (ou `prix_voyage` du tarif) et quantité 1 ;
  - exception : avec `parametre_facturation_forcer_sous_centrale_m3` et une zone sous-centrale, la quantité reste la quantité livrée, mais le prix suit toujours le mode voyage ;
  - la ligne est facturable si `transport_facturable`.
- **D5.** **Transport incomplet** : il ne s'applique qu'en mode m³, pour une zone qui n'est pas sous-centrale, avec `transport_incomplet=O`, quand le seuil (du véhicule, ou du chantier si `parametre_utiliser_seuil_ti_chantier`) moins la quantité livrée est > 0, et quand le chantier est en mode 0 ou 2.
  - La ligne utilise l'article `parametre_article_ti_id` et l'unité de `t_parametre`, au prix `zone_prix_m3_incomplet` (ou `prix_ti` / `remise_ti` du tarif, niveau 5 fixe). Elle est toujours facturable (=1), même en mode 2.
- **D6.** **Services 1 à 6 (type 1)** : les 6 blocs sont identiques. Quantité ÷100, facturable=1, unité = `unite_libelle`. Si une ligne démat existe déjà pour ce service, on met seulement sa quantité à jour.
- **D7.** **Taxes automatiques (type 1)** : chacune s'ajoute selon une case du chantier et un article défini dans `t_parametre`. Elle est ignorée si une ligne de service avec le même article existe déjà (ligne démat ou service 1 à 6). La quantité vaut quantité livrée × masse volumique. Facturable=1, niveau de prix 5 au maximum.

  | Taxe | Activité | Case chantier | Article |
  |---|---|---|---|
  | TGAP / contribution environnementale | BPE | `chantier_tgap_beton_facturable` | `parametre_article_contribution_environ_id` |
  | TGAP | Carrière, si `produit_assujeti_tgap=1` | `chantier_tgap_granulat_facturable` | `parametre_article_tgap_id` |
  | Taxe carbone | Les deux | `chantier_taxe_carbone_facturable` | `parametre_article_taxe_carbone_id` |
  | Taxe énergétique | BPE | `chantier_taxe_energetique_facturable` | `parametre_article_taxe_energetique_id` |
  | Écotaxe | BPE | `chantier_ecotaxe_facturable` | `parametre_article_ecotaxe_id` |
  | Contribution exceptionnelle | BPE | `chantier_contribution_exeptionnelle_facturable` | `parametre_contribution_exeptionnelle_id` |
  | REP granulat 1 | Carrière | `chantier_rep_granulat_1_facturable` | article du produit (`produit_rep_granulat_1_article_id`), sinon `parametre_rep_granulat_1_article_id` |
  | Contribution env. granulat | Carrière | `chantier_contrib_env_granulat_facturable` | `parametre_contrib_env_granulat_article_id` |

- **D8.** **Adjuvants et ajouts 1 à 6** :
  - `adjN_ajout=N` → `t_produit`, type 3, sans unité, prix de base `produit_prix_vent_ht` ;
  - sinon → `t_ajout`, type 2, unité = `unite_libelle`, prix de base `ajout_prix`.
  - Quantité ÷100. Facturable sauf si `fac_adjN=N`.
  - Type 3 avec `parametre_qte_adj_qte_beton=1` → la quantité devient la quantité livrée.
  - Type 2 avec `parametre_qte_ajout_qte_beton=1` et `ajout_type_unite` 1 ou 3 → la quantité devient quantité × quantité livrée.
  - `ligne_bl_qte_dosage` reçoit la quantité brute (÷100).
  - Les 6 blocs donnent le même prix (le bloc 1 lie `$prix`, les blocs 2 à 6 lient `$prix_adj = $prix`), à l'exception notée en H7.

## E. Planning / OF
- **E1.** Une heure absente est calculée :
  - départ centrale = heure de fabrication + `centrale_tps_fab_1m3` × m³ ;
  - arrivée chantier = départ centrale + `commande_tps_acces` ;
  - début de vidange = arrivée chantier ;
  - fin de vidange = début de vidange + `commande_tps_dechargement` × m³ ;
  - départ chantier = fin de vidange ;
  - retour centrale = départ chantier + `commande_tps_acces`.
  - Quand `cmd_of` vaut autre chose que N, on reprend les heures de l'OF.
- **E2.** `planning_debut` = heure de livraison, `planning_fin` = heure de livraison + déchargement × m³, `planning_reel=1`.

## F. Après l'enregistrement
- **F1.** Si l'enregistrement réussit, on écrit la traçabilité réelle : `integrer_traca_date_heure_reelle('BL', …)`.
- **F2.** Si `parametre_tester_presence_precedent=1` et que le BL N−1 est absent, on demande son renvoi via `T_BLMQ` dans `t_tracabilite_envoi`.
- **F3.** **Démat immédiate** : on prend l'email démat du chantier, sinon celui du client. Si `chantier_demat_bl_immediat=1`, on pose `bl_mail_demat_envoye=1`, à la création seulement.
- **F4.** Appels HTTP internes, selon les paramètres :
  - XML démat (`parametre_demat_auto_via_web`) ;
  - export FTP (`parametre_envoi_fichier_ftp_automatique`) ;
  - à la création : envoi GPS (`parametre_gps_auto_via_web`), puis génération du PDF dans tous les cas ;
  - à chaque fois : recalcul de l'encours client.

## G. Suppression
- **G1.** Un DELETE `t_bl` est fait seulement si le BL n'est pas facturé et que `bl_non_modif_prod=0`. Sinon, la réponse est le message « BL facturé ».
- **G2.** Les lignes et le planning ne sont pas supprimés explicitement par ce fichier. La commande n'est pas recréditée.

## H. Défauts du legacy à ne pas reproduire dans l'API
- **H1.** Il n'y a pas de transaction : la commande et le planning sont écrits avant le BL.
- **H2.** Seule l'insertion de la ligne formule vérifie les erreurs.
- **H3.** Ligne 3954 : `json_decode` est lu comme un tableau, ce qui provoque une erreur fatale quand le GPS automatique est activé.
- **H4.** Ligne 395 : l'attente chantier teste `bl_heure_dep_centrale_type` au lieu de son propre champ. Les noms `bl_heure_deb_chantier_type` (l. 379) et `bl__heure_arr_centrale_type` (l. 387) sont aussi à vérifier.
- **H5.** Le transport incomplet du cas 2 (« non facturé ») est inséré avec facturable=1.
- **H6.** Toutes les requêtes sont exposées à l'injection SQL.
- **H7.** `definir_prix()` est appelé **sans** `$code_commande` pour l'ajout du bloc 2 (l. 2731) et pour les deux branches du bloc 6 (l. 3440 et 3521). Le prix commande (niveau 6) ne peut donc pas y être retrouvé, contrairement aux autres blocs.
- **H8.** `sleep(0.5)` est converti en `sleep(0)` : aucune pause réelle.

## Points à vérifier en premier

Les points **A5, C2, C4, D1, D2 et D7** sont ceux qui risquent le plus de diverger dans la version API.
