> ## Documentation Index > Fetch the complete documentation index at: https://docs.metronome.com/llms.txt > Use this file to discover all available pages before exploring further. # Intégrer NetSuite **Bêta publique** L'intégration NetSuite de Metronome est actuellement en bêta publique. Des changements non rétrocompatibles peuvent survenir d'ici la GA. Toutes les fonctionnalités de Metronome ne sont pas prises en charge pendant la bêta publique. Veuillez contacter votre représentant Metronome si vous avez des questions. Fonctionnalités connues comme non prises en charge : * Devises personnalisées * Hiérarchie de comptes L'intégration NetSuite de Metronome permet aux clients de synchroniser les factures et paiements vers NetSuite pour deux cas d'usage principaux : * **Facturation :** envoyer les factures à NetSuite pour la distribution et l'encaissement. * **Reconnaissance des revenus :** si un système différent (par exemple, Stripe) est utilisé pour la facturation, synchroniser les factures et le statut de paiement vers NetSuite pour alimenter les opérations de revenu. ## Exigences de compatibilité NetSuite L'intégration NetSuite est disponible pour tous les clients Metronome, mais elle est conçue pour fonctionner avec des configurations NetSuite standard. NetSuite est hautement personnalisable, et votre instance peut nécessiter quelques mises à jour de configuration de base avant que l'intégration ne fonctionne immédiatement. Avant de configurer l'intégration, confirmez que votre instance NetSuite répond aux exigences suivantes : * **Champs de ligne :** les champs `amount`, `quantity` et `total` de la ligne doivent être modifiables. * **Articles d'inventaire :** les articles d'inventaire qui nécessitent un emplacement ne sont pas pris en charge. **VALIDATION EN SANDBOX** Avant d'activer l'intégration en production, validez le flow complet de synchronisation des factures dans votre environnement sandbox NetSuite. Cela permet de faire émerger tout problème de configuration avant qu'il n'affecte les factures en production. **DÉBIT** Cette intégration prend en charge jusqu'à 25 000 factures à terme échu par mois. Si votre volume de factures dépasse ce montant, les données peuvent prendre plus longtemps que prévu à se synchroniser vers NetSuite. **PERSONNALISATIONS SPÉCIFIQUES À L'INSTANCE** Metronome ne modifie pas l'intégration pour s'adapter à des configurations d'instance NetSuite personnalisées. Si votre instance nécessite des changements pour être compatible, ces mises à jour devront être effectuées de votre côté. ## Connecter Metronome à NetSuite Pour connecter Metronome à NetSuite, accédez à l'interface Metronome et allez dans l'onglet *Connections -> Integrations*. Sélectionnez NetSuite parmi les options dans *Available Integrations*. Une pop-up s'ouvrira avec des instructions sur la manière de connecter Metronome à NetSuite. Vous devrez : * Fournir à Metronome votre account ID NetSuite * Télécharger un bundle de permissions (fourni dans la pop-up) dans votre compte NetSuite, ce qui garantira à Metronome les permissions appropriées pour écrire et lire les objets nécessaires dans NetSuite * Fournir à Metronome les identifiants générés pour accéder à votre compte NetSuite Une fois terminé, vous devriez voir NetSuite listé dans la table *Active Integrations*. **SYNCHRONISATION INITIALE DES OBJETS** Après avoir créé la connexion, Metronome peut prendre jusqu'à une heure pour indexer les objets dans NetSuite. Cela peut provoquer un délai dans la synchronisation des factures après la configuration initiale. ## Mapper vos produits Metronome aux items NetSuite Les produits Metronome se mappent aux items NetSuite, où l'identifiant de produit sur la ligne Metronome se mappe à un identifiant d'item sur la ligne de facture NetSuite. Commencez par créer vos items dans NetSuite. Vous pouvez mapper plusieurs produits Metronome à un seul item NetSuite. Une fois vos items NetSuite configurés, suivez les étapes suivantes : * Créez un champ personnalisé sur l'objet produit. Nommez-le par exemple `netsuite_item_internal_id`. * Pour chaque produit dans Metronome, renseignez le champ avec l'identifiant interne d'item correspondant dans NetSuite. * Utilisez la fonctionnalité d'édition de mapping pour définir la relation entre le champ personnalisé du produit Metronome et l'ID d'item NetSuite. Cliquez sur la ligne NetSuite dans la table **Active Integrations** et sélectionnez **Edit Mapping**. * Le mapping doit ressembler à `Invoice.Items: internal_id -> ContractProduct: your key` ### Application d'engagement pour les factures à \$0 Si vous exploitez un modèle de crédits prépayés et souhaitez envoyer des factures à $0 à NetSuite pour reconnaître le revenu en regard de la consommation, vous devrez créer un item « Commit Application » dans NS. Pour les factures à $0, les lignes négatives, qui représentent le décompte d'engagement, seront comptabilisées sur l'item commit application. Pour configurer : * Créez l'item dans NetSuite. * Créez un nouveau champ personnalisé sur le produit Metronome. Nommez-le par exemple `netsuite_commit_application_internal_id`. * Sur le(s) produit(s) d'engagement prépayé, renseignez la valeur du champ personnalisé avec l'identifiant interne du produit commit application. * À l'aide de la fonctionnalité de mapping d'entité sur la table des intégrations, créez un nouveau mapping pour : `Invoice.items: commit_application_item_id -> ContractProduct: your key` Cette configuration vous permet d'avoir différents traitements de revenu pour l'engagement prépayé selon que le produit Metronome est utilisé pour un achat d'engagement (c'est-à-dire revenu différé) ou pour l'application d'engagement (c'est-à-dire reconnaître le revenu). **VÉRIFIEZ LA CONFIGURATION DE REVENU** Dans NetSuite, tous les items d'une facture doivent avoir le même traitement de revenu. Autrement dit, ils doivent tous soit différer, soit pointer vers du revenu. Si votre item commit application est configuré pour différer le revenu mais que les items d'usage pointent vers un compte de revenu, la facture échouera à être envoyée à NetSuite. ## Configurer votre client Metronome Créez des configurations de système de facturation ou de système de revenu sur l'objet client Metronome. Une fois créées, elles peuvent ensuite être référencées sur le contrat du client pour router les factures du contrat vers NetSuite : * **Customer billing configuration :** pour les cas d'usage de facturation, Metronome synchronise la facture vers NetSuite une fois qu'elle est finalisée. NetSuite gère ensuite la distribution de la facture, le calcul des taxes et l'encaissement du paiement. * **Revenue system configuration :** Metronome synchronise les factures vers NetSuite après qu'un paiement a été tenté dans un autre système (par exemple, Stripe). Si le paiement a réussi, Metronome synchronisera les informations de paiement associées vers NetSuite sous forme d'objet payment. Si le paiement échoue à la première tentative mais réussit plus tard, Metronome créera l'objet payment une fois réussi. ### Définir la customer billing configuration Si un client doit être facturé depuis NetSuite, définissez la `customer_billing_configuration` à `netsuite`. Cela peut être fait dans l'appel de création du client ou après la création du client à l'aide de l'endpoint `/setCustomerBillingProviderConfigurations` ou de l'interface. Voir l'exemple ci-dessous : ```bash theme={null} curl https://api.metronome.com/v1/setCustomerBillingProviderConfigurations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "data": [ { "customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491", "billing_provider": "netsuite", "configuration": { "netsuite_customer_id": "58877111" }, "delivery_method_id": "5b95d955-b705-41c8-9d2e-34ccbdee5193" } ] }' ``` **DÉFINIR LA CONFIGURATION SUR LE CONTRAT** Metronome vous permet de définir plusieurs `customer_billing_configuration` par client. Pour cette raison, une fois qu'une `customer_billing_configuration` a été définie, vous devez l'affecter au contrat concerné afin que Metronome envoie les factures du contrat à NetSuite. ### Définir la revenue system configuration Si le client est facturé en dehors de NetSuite, mais que NetSuite a besoin des informations de facture pour la reconnaissance des revenus, configurez une `revenue_system_configuration` pour le client via l'API ou l'interface. Metronome synchronise à la fois les factures et les paiements (si disponibles) pour les contrats ayant une configuration de système de revenu. Si le paiement échoue pour la facture après la première tentative, Metronome synchronisera tout de même la facture vers NetSuite avec le statut `OPEN`. Si le paiement est retenté plus tard et réussit, Metronome mettra rétroactivement à jour la facture associée dans NetSuite en `PAID`. Voir un exemple ci-dessous pour définir la `revenue_system_configuration` via l'endpoint `setCustomerRevenueSystemConfigurations` : ```bash theme={null} curl https://api.metronome.com/v1/setCustomerRevenueSystemConfigurations \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "data": [ { "customer_id": "7b8864ad-5238-4ec2-8b89-bee635e1876b", "provider": "netsuite", "configuration": { "netsuite_customer_id": "58771" }, "delivery_method_id": "6fe89b5a-41d0-413b-bb44-5f90522db8a2" } ] }' ``` **DÉFINIR LA CONFIGURATION SUR LE CONTRAT** Metronome vous permet de définir plusieurs `revenue_system_configuration` par client. Pour cette raison, une fois qu'une `revenue_system_configuration` a été définie, vous devez l'affecter au contrat concerné afin que Metronome envoie les factures du contrat et les paiements associés à NetSuite. ### Provisionner le contrat du client Soit la `customer_billing_configuration`, soit la `revenue_system_configuration` doit être définie sur un contrat pour que Metronome synchronise les factures vers NetSuite. Cela vous offre la flexibilité de router les factures vers différents endroits sur une base contrat par contrat. Examinons un exemple d'entreprise : * Tous les clients PLG sont facturés depuis Stripe. Ce sont des clients en self-serve auxquels un abonnement mensuel de \$10 est facturé en échange de 5 crédits IA. * Tous les clients SLG sont facturés depuis NetSuite. Ces clients paient en versements trimestriels pour des engagements d'usage annuels. Pour les clients PLG, je veux que Metronome collecte le paiement dans Stripe puis synchronise la facture vers NetSuite. Pour activer cela, deux appels d'API doivent être effectués vers Metronome lorsqu'un nouveau client PLG s'inscrit : créer un client et créer un contrat. Voir l'exemple ci-dessous pour créer l'objet client. Cet appel d'API inclut la création de la `customer_billing_configuration` et de la `revenue_system_configuration` : ```bash theme={null} curl https://api.metronome.com/v1/customers \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "ingest_aliases": [ "plgcustomer1@example.com" ], "name": "Customer 01", "customer_billing_provider_configurations": [ { "billing_provider": "stripe", "delivery_method": "direct_to_billing_provider",, "configuration": { "stripe_customer_id": "cus_123", "stripe_collection_method": "charge_automatically" } } ], "revenue_system_configuration": [ { "provider": "netsuite", "configuration": { "netsuite_customer_id": "58771" }, "delivery_method_id": "6fe89b5a-41d0-413b-bb44-5f90522db8a2" } ] }' ``` Ensuite, voir l'exemple ci-dessous pour créer le contrat PLG du client avec les `customer_billing_configuration` et `revenue_system_configuration` qui y sont définies. Pour obtenir les `revenue_system_configuration_id` et `billing_provider_configuration_id`, vous devrez appeler les endpoints fetch billing provider et revenue system configuration : ```bash theme={null} curl https://api.metronome.com/v1/customers \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "customer_id": "4c09936b-455d-4c72-a120-d71b600a7546", "rate_card_id": "740a2ca1-64f6-417d-807a-05f154b3b1fe", "starting_at": "2025-06-01T00:00:00.000Z", "billing_provider_configuration": { "billing_provider_configuration_id": "e045c62b-65e7-4e84-a924-3f06f8b621d0" // UUID of previously created customer billing configuration }, "revenue_system_configuration": { "revenue_system_configuration_id": "d455j33b-12f7-4b76-a924-3f06f8b687q9" // UUID of previously created revenue system configuration }, "overrides": [ { "starting_at": "2025-04-01T00:00:00.000Z", "override_specifiers": [ { "billing_frequency": "annual", "product_id": "ed518bcb-acc1-4cd8-85dd-880c2eb38994" } ], "entitled": true } ], "subscriptions": [ { "collection_schedule": "advance", "initial_quantity": 1, "proration": { "invoice_behavior": "bill_on_next_collection_date", "is_prorated": true }, "subscription_rate": { "billing_frequency": "monthly", "product_id": "ed518bcb-acc1-4cd8-85dd-880c2eb38994" }, "description": "Basic tier", "name": "Basic Plan", "custom_fields": { "plan_tier": "basic" }, "temporary_id": "basic_plan_monthly" } ], "recurring_credits": [ { "access_amount": { "credit_type_id": "d3cb2827-dcb5-44af-9354-947a7197b9a6", "unit_price": 5 }, "commit_duration": { "value": 1, "unit": "periods" }, "priority": 1, "product_id": "652e1298-7638-45a8-b691-cdf47e46cbc8", "starting_at": "2025-06-01T00:00:00Z", "subscription_config": { "subscription_id": "basic_plan_monthly", "apply_seat_increase_config": { "is_prorated": true } } } ] }' ``` Pour les clients SLG, je veux que Metronome synchronise la facture vers NetSuite où elle peut être facturée. Pour activer cela, les mêmes appels d'API que pour créer un client PLG sont requis, mais NetSuite doit être créé en tant que `customer_billing_configuration` sur le client et utilisé comme configuration de facturation sur le contrat. ## Taxe Pour calculer la taxe sur les factures dans NetSuite, vous devez intégrer NetSuite à votre fournisseur de taxe préféré. Metronome ne calcule pas et ne synchronise pas les montants de taxe vers NetSuite. Le flow de taxe se déroulera comme suit : * Metronome crée une facture dans NetSuite. * L'intégration de taxe dans NetSuite ajoute la taxe à la facture. Cette configuration est requise que vous utilisiez NetSuite pour la facturation ou uniquement pour la reconnaissance des revenus. À noter : la taxe **n'est pas** resynchronisée vers Metronome. ## Gérer l'intégration Lorsque Metronome envoie des factures à NetSuite, il enregistre des informations à travers quatre surfaces pour vous aider à gérer l'état de chaque objet et garantir que toutes les données sont synchronisées correctement : l'interface, l'API, l'export de données et les notifications webhook. Tirez parti de ces informations pour arbitrer les éventuels problèmes de synchronisation et garantir que toutes les données sont bien envoyées à NetSuite. ### État de la facture Metronome enregistre des informations à des endroits distincts sur l'objet facture selon que NetSuite est configuré comme `customer_billing_configuration` ou comme `revenue_system_configuration`. #### Synchronisations réussies Lorsque NetSuite est défini comme `customer_billing_configuration`, les détails de synchronisation seront stockés dans l'objet `external_invoice`. Le statut de la facture sera reflété dans la propriété `external_status` et l'ID de facture NetSuite créé est stocké dans la propriété `external_invoice.invoice_id`. Voir un exemple /getInvoice ci-dessous : ```bash theme={null} curl https://api.metronome.com/v1/customers \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "id": "8f653259-640d-5a10-9636-2c7682a355fe", "start_timestamp": "2026-02-11T00:00:00+00:00", "end_timestamp": "2026-02-11T00:00:00+00:00", "issued_at": "2026-02-11T00:00:00+00:00", "customer_id": "43536714-7f62-4e27-abcd-492d231ab7a0", // ... "external_invoice": { "billing_provider_type": "netsuite", "invoice_id": "61112", // NetSuite invoice id "issued_at_timestamp": "2026-02-11T00:00:00+00:00", "external_status": "FINALIZED" // ... }' ``` Lors du succès initial, Metronome émet une notification webhook `invoice.invoice_sync_status` fournissant les détails de la facture : ```json theme={null} { "id": "65472d2c-c51f-46b2-95b3-0eaeb5c3dc5a", "invoice_id": "a43c2489-3d2f-40a2-a469-16411c535406", "customer_id": "faeff926-0a94-45da-9048-5b9d381b608b", "contract_id": "dfaa1fd8-d4d7-42c0-b2ab-9cc532793ca7", "sync_type": "billing_provider, "external_invoice": { "billing_provider_type": "netsuite", "invoice_id": "9ae574fb-9d56-51c2-9077-b78971e9fe5b", // NetSuite invoice id "issued_at_timestamp": "2026-02-11T00:00:00+00:00", "external_status": "FINALIZED" // ... } } ``` Si le statut de la facture change dans NetSuite, Metronome mettra à jour `external_status` pour refléter le nouvel état de la facture. Attendez-vous à environ une heure de latence pour ces mises à jour de statut. Lorsque NetSuite est défini comme `revenue_system_configuration`, les détails de synchronisation sont stockés dans l'objet `revenue_system_invoices` sur l'API invoice. Voir l'exemple ci-dessous : ```bash theme={null} curl https://api.metronome.com/v1/customers \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "id": "8f653259-640d-5a10-9636-2c7682a355fe", "start_timestamp": "2026-02-11T00:00:00+00:00", "end_timestamp": "2026-02-11T00:00:00+00:00", "issued_at": "2026-02-11T00:00:00+00:00", "customer_id": "43536714-7f62-4e27-abcd-492d231ab7a0", // ... "revenue_system_invoices": [ { "revenue_system_provider": "NETSUITE", "revenue_system_external_entity_id": "458886", "sync_status": "SUCCEEDED", "revenue_system_external_entity_type": "NETSUITE_INVOICE" } ] }' ``` De manière similaire, Metronome émet une notification webhook `invoice.invoice_sync_status` avec `sync_type` défini à `revenue_system`. #### Échecs de synchronisation Lorsque NetSuite est défini comme `customer_billing_configuration`, `external_status` sera mis à jour à `INVALID_REQUEST_ERROR` en cas d'échec. Le message d'erreur sera stocké dans la propriété `billing_provider_error`. Voir un exemple d'API /getInvoice ci-dessous : ```bash theme={null} curl https://api.metronome.com/v1/customers \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "id": "8f653259-640d-5a10-9636-2c7682a355fe", "start_timestamp": "2026-02-11T00:00:00+00:00", "end_timestamp": "2026-02-11T00:00:00+00:00", "issued_at": "2026-02-11T00:00:00+00:00", "customer_id": "43536714-7f62-4e27-abcd-492d231ab7a0", // ... "external_invoice": { "billing_provider_type": "netsuite", "external_status": "INVALID_REQUEST_ERROR", "billing_provider_error": "We've encountered the following error when trying to access the NetSuite API: Failed to create Netsuite Invoice object. No item id found 5551." }, // ... }' ``` Lorsque l'erreur survient, Metronome émet une notification webhook `invoice.invoice_sync_status` fournissant les détails de la facture avec les informations d'erreur associées. Les clients doivent consommer ces webhooks pour identifier quand une facture échoue à se synchroniser vers NetSuite et arbitrer en fonction des détails d'erreur. Dans l'exemple ci-dessus, le message d'erreur identifie que l'item id pour l'un des produits Metronome est incorrect. Pour résoudre ce problème, mettez à jour le champ personnalisé correspondant avec l'item id NetSuite correct. Une fois corrigé, vous pouvez retenter la synchronisation vers NetSuite via l'interface en cliquant sur le bouton **Send to NetSuite** sur la page de la facture dans l'interface. Lorsque NetSuite est défini comme `revenue_system_configuration`, `sync_status` sera mis à jour à `FAILED` en cas d'échec. L'erreur associée expliquant pourquoi la facture a échoué sera stockée dans la propriété `error_message`. Voir l'exemple ci-dessous : ```bash theme={null} curl https://api.metronome.com/v1/customers \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "id": "8f653259-640d-5a10-9636-2c7682a355fe", "start_timestamp": "2026-02-11T00:00:00+00:00", "end_timestamp": "2026-02-11T00:00:00+00:00", "issued_at": "2026-02-11T00:00:00+00:00", "customer_id": "43536714-7f62-4e27-abcd-492d231ab7a0", // ... "revenue_system_invoices": [ { "revenue_system_provider": "NETSUITE", "sync_status": "FAILED", "revenue_system_external_entity_type": "NETSUITE_INVOICE", "error_message": "We've encountered the following error when trying to access the NetSuite API: Failed to create Netsuite Invoice object. No item id found 5551." } ] }' ``` ### État du paiement Si Stripe est utilisé pour la facturation et NetSuite est configuré comme système de revenu, Metronome crée d'abord un objet facture dans Stripe. Si le paiement est réussi : * Metronome stockera l'ID du payment intent et le montant du paiement à l'intérieur de l'objet `external_invoice` dans les champs `external_payment_id` et `invoiced_total` respectivement. * En synchronisant ensuite la facture vers NetSuite, Metronome marquera la facture comme `PAID` et créera un objet payment lié. De manière similaire à la synchronisation de facture, Metronome émettra une notification webhook `payment.payment_status_sync` pour indiquer le succès ou l'échec de l'envoi de l'objet payment vers NetSuite. Si NetSuite est utilisé pour la facturation, Metronome créera une facture dans NetSuite. Lorsque cette facture est payée dans NetSuite, Metronome marquera la facture comme `PAID` une fois les données re-synchronisées depuis NetSuite. ## Configurations supplémentaires ### Synchronisation des champs personnalisés Metronome synchronise également des métadonnées supplémentaires vers l'objet facture NetSuite pour aider aux workflows de rapprochement. Pour activer, créez les champs personnalisés suivants sur votre objet facture NetSuite avec les `id` suivants (tous sensibles à la casse) : * `metronome_invoice_id` : Metronome stockera l'`invoice_id` Metronome associé dans ce champ. * `metronome_contract_id` : Metronome stockera le `contract_id` Metronome associé dans ce champ. * `metronome_customer_id` : Metronome stockera le `customer_id` Metronome associé dans ce champ. Si ces champs personnalisés ne sont pas configurés, Metronome ne pourra pas synchroniser les métadonnées associées. ### Factures à \$0 Par défaut, Metronome envoie les factures à 0 USD à NetSuite. Ces factures peuvent être utilisées pour suivre la consommation par rapport à un engagement ou un crédit aux fins de reconnaissance des revenus. Assurez-vous de configurer l'item commit application comme décrit ci-dessus si vous envoyez des factures à 0 USD à NetSuite. Les utilisateurs peuvent choisir de ne pas envoyer ces factures en naviguant vers l'onglet *Connections -> Integrations* et en cliquant sur l'icône d'engrenage de la connexion NetSuite.