Cette fonctionnalité (les “Transformers”) génère la représentation API des objets (factures, devis, personnes, organisations, paiements, coordonnées bancaires, soldes, etc.). Elle vous permet d’obtenir un JSON standardisé, d’inclure uniquement les relations dont vous avez besoin et de garantir que les champs sensibles restent masqués. Pour les documents commerciaux, le contrat de transformation (SalesDocumentContract) expose désormais available_recipients_emails : ce champ est inclus dans le payload SalesDocument et contient la liste des adresses e‑mail autorisées à recevoir le document. Notez également que les valeurs énumérées pour le type de document et le régime TVA sont désormais définies dans app/Enums/SalesDocumentBillingType et app/Enums/SalesDocumentVatRegime ; le trait HasTypeAndRegimeAttributes a été ajusté pour exposer les attributs billing_type et vat_regime dans le payload des documents. Le modèle SalesDocumentModel a par ailleurs été enrichi : des attributs optionnels supplémentaires et des inclusions complémentaires peuvent maintenant être exposés par les transformers — consultez le schéma Swagger pour la liste exacte et à jour des champs disponibles.

Important : le TransformController des contacts (personnes/contacts) a été modifié récemment. La structure des payloads Contact/Person a été réorganisée et de nouveaux includes dédiés sont maintenant disponibles (ex. primary_contact, contact_methods, emails, phones, addresses, tags, relationships). Certains anciens includes ont été consolidés ou renommés — vérifiez le schéma Swagger (resources/swagger.yaml) pour la liste exacte et les chemins d’inclusion à utiliser dans vos requêtes.

De plus, le modèle SalesLine a été modifié : les lignes de document peuvent maintenant exposer des montants en devise étrangère via de nouveaux champs (par exemple unit_price_currency, net_amount_currency, vat_amount_currency, gross_amount_currency), ainsi que des métadonnées currency_code et exchange_rate. Selon le transformer, un groupe dédié currency_amounts peut également être fourni. Pour obtenir ces champs, incluez la relation content (ou content.currency_amounts lorsque le transformer le propose).

How to use it #

Exemple de payload : SalesDocument #

Voici un exemple simplifié d’un payload SalesDocument tel qu’il peut être renvoyé par les transformers. Selon la version du modèle et les includes demandés, des attributs optionnels supplémentaires peuvent apparaître (métadonnées, liens, compteurs, etc.) — pour le schéma complet et à jour, consultez resources/swagger.yaml.

{ “id”: 123, “number”: “INV-2026-0001”, “title”: “Facture client”, “status”: “issued”, “date”: “2026-04-01”, “due_date”: “2026-04-30”, “totals”: { “net”: 1000.00, “vat”: 200.00, “gross”: 1200.00 }, “billing_type”: “invoice”, // valeur normalisée via SalesDocumentBillingType “vat_regime”: “standard”, // valeur normalisée via SalesDocumentVatRegime “available_recipients_emails”: [ “[email protected]”, “[email protected]” ], “author”: { “id”: 5, “name”: “Alice Dupont”, “email”: “[email protected]” }, “customer”: { “id”: 42, “name”: “Acme SA”, “primary_contact”: { “id”: 7, “first_name”: “Jean”, “last_name”: “Martin”, “email”: “[email protected]” }, “contact_methods”: { “emails”: [ “[email protected]”, “[email protected]” ], “phones”: [ “+33123456789” ] }, “addresses”: { “billing”: { “line1”: “1 Rue Exemple”, “postal_code”: “75001”, “city”: “Paris”, “country”: “FR” } } }, “bank_detail”: { “iban”: “FR76XXXXXXXXXXXX”, “bic”: “AGRIFRPP” }, “content”: [ { “description”: “Service A”, “quantity”: 1, “unit_price”: 1000.00, “unit_price_currency”: 1200.00, // montant en devise étrangère (si demandé) “total_currency”: 1200.00, // total ligne en devise étrangère “currency_code”: “USD”, // code devise de la ligne “exchange_rate”: 1.20 // taux de conversion appliqué } ], “extras”: { “internal_note”: “Préférer envoi par e‑mail”, “attachments_count”: 2 } }

(Le bloc “extras” illustre des attributs additionnels optionnels — leur présence et leur structure sont dépendantes du transformer et du schéma courant.)

FAQ #