Passer au contenu principal
Les champs personnalisés sont des propriétés que vous pouvez ajouter aux objets Metronome pour stocker des métadonnées telles que des clés étrangères ou d’autres descripteurs. Ces métadonnées peuvent être transférées vers d’autres systèmes ou accessibles par eux afin de contextualiser les données de Metronome et de soutenir les processus métier. Par exemple, pour prendre en charge des workflows tels que la reconnaissance des revenus, la réconciliation et la facturation dans Stripe, les champs personnalisés aident Metronome à comprendre la relation entre les entités de la plateforme et les systèmes tiers.

​
Comment fonctionnent les champs personnalisés

Vous pouvez ajouter des champs personnalisés à la plupart des entités Metronome : customer, product, contract, commit, credit, scheduled charge, rate card et alert. Ces champs sont conservés dans toute la plateforme et peuvent être récupérés dans l’interface utilisateur, l’API et l’export de données, partout où l’objet apparaît. Lorsque vous déterminez quand créer des champs personnalisés et où les placer, il est important de bien réfléchir à la relation entre les entités d’un système externe donné et Metronome. Par exemple, pour modéliser une intégration ERP NetSuite dans Metronome, vous devez identifier l’équivalent de chaque objet que vous souhaitez synchroniser. Souvent, les clients synchronisent les factures Metronome avec NetSuite et associent les factures à l’identifiant client NetSuite correspondant. Pour stocker la relation entre eux, créez un champ personnalisé nommé netsuite_customer_id sur l’objet client Metronome. Ce champ permet à un utilisateur d’interroger l’objet client et de déterminer le mappage de clé étrangère entre les deux systèmes. L’exemple suivant montre comment associer une ligne d’article à un identifiant de produit (ou SKU) dans Stripe en ajoutant un champ personnalisé nommé stripe_product_id au produit Metronome.

​
Créer un champ personnalisé

Vous pouvez créer un champ personnalisé via l’application Metronome ou l’API. Pour créer un champ personnalisé sur un produit dans l’application Metronome :
  1. Cliquez sur Connections.
  2. Dans Connections, cliquez sur l’onglet Custom fields.
  3. Dans les champs personnalisés, cliquez sur Add new field key.
  4. Dans le modal qui s’affiche, sélectionnez Product (Contracts) pour l’entité, saisissez stripe_product_id comme Key, et activez l’option Unique values required.
  5. Cliquez sur Save.
ATTENTIONImposer des valeurs uniques limite la possibilité de définir la même valeur sur plusieurs objets.Utilisez ceci pour mapper des entités externes qui ont une relation un-à-un avec un objet Metronome. L’unicité est appliquée même lorsqu’un objet est archivé. Pour résoudre un problème de doublon avec un objet archivé, réinitialisez la valeur du champ.
Pour créer un champ personnalisé via l’API, effectuez une requête POST vers /customFields/addKey. L’endpoint accepte trois paramètres, tous obligatoires :
  • entity
  • key
  • enforce_uniqueness
    curl https://api.metronome.com/v1/customFields/addKey \  
      -H "Authorization: Bearer <TOKEN>" \  
      -H "Content-Type: application/json" \  
      -d '{  
        "entity": "contract_product",  
        "key": "stripe_product_id",  
        "enforce_uniqueness": true  
      }'

​
Définir une valeur de champ personnalisé

Une fois que vous avez défini un champ personnalisé sur une entité, définissez des valeurs pour ce champ sur des instances individuelles de l’entité à l’aide de l’application Metronome ou de l’API. Pour définir la valeur d’un champ personnalisé dans l’application Metronome :
  1. Allez sur la page Contract Pricing et trouvez le produit dans la Product List.
  2. Cliquez sur l’enregistrement du produit pour ouvrir le panneau contenant les métadonnées du produit.
  3. Cliquez sur le bouton de menu en haut à droite du panneau et cliquez sur Manage custom fields.
  4. Dans les paramètres du client, cliquez sur Custom fields —> Manage.
  5. Sur la page des champs personnalisés, cliquez sur Set custom field.
  6. Dans le modal qui s’affiche, sélectionnez le nom du champ et fournissez la valeur du champ.
  7. Cliquez sur Save.
Pour définir la valeur d’un champ personnalisé via l’API, effectuez une requête POST vers /customFields/setValues. L’endpoint accepte trois paramètres, tous obligatoires :
  • entity
  • entity_id
  • custom_fields
Le paramètre custom_fields accepte un tableau de paires clé-valeur, ce qui vous permet de définir plusieurs valeurs de champs personnalisés — sur une seule instance d’entité — en un seul appel d’API. Cette requête met à jour un produit spécifique, en ajoutant la valeur stripe_product_id correspondante : 
    curl https://api.metronome.com/v1/customFields/setValues \  
      -H "Authorization: Bearer <TOKEN>" \  
      -H "Content-Type: application/json" \  
      -d '{  
        "entity": "contract_product",  
        "entity_id": "76e57c3a-064f-49ad-8740-2bff58f2f808",  
        "custom_fields": {  
          "stripe_product_id": "prod_KyVnHhSBWl7eY2bl"  
        }  
      }'
Vous pouvez également définir la valeur d’un champ personnalisé lors de la création d’un objet. Par exemple, pour définir la valeur d’un champ personnalisé sur l’objet contrat, vous pouvez le faire dans la requête POST vers l’endpoint /createContract.

​
Récupérer la valeur d’un champ personnalisé

Une fois que vous avez défini la valeur d’un champ personnalisé sur une instance d’objet (par exemple un produit), la valeur est renvoyée lorsque vous demandez cet objet, y compris dans l’application Metronome, les appels d’API et les exports de données. Par exemple, considérez la réponse de facture. Étant donné que les produits dans Metronome correspondent aux lignes d’articles sur les factures, le champ personnalisé stripe_product_id se propage à la ligne d’article associée. Ce mappage permet à Metronome de relier les lignes d’articles aux produits Stripe lors de la création de factures dans Stripe. Voici un exemple de charge utile de facture : 
    {  
      "data": {  
        "id": "09abf41e-2e68-622f-93bc-ce8ef21215de",  
        "issued_at": "2024-09-02T00:00:00+00:00",  
        "start_timestamp": "2024-08-01T00:00:00+00:00",  
        "end_timestamp": "2024-09-01T00:00:00+00:00",  
        "customer_id": "195826717-122e-5150-a96e-ab7ef9744e9c",  
        "customer_custom_fields": {},  
        "type": "USAGE",  
        "credit_type": {  
          "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",  
          "name": "USD (cents)"  
        },  
        "status": "DRAFT",  
        "total": 22000,  
        "external_invoice": null,  
        "contract_id": "ccffadcf-5e3b-407d-8c5e-3f678508bfd1",  
        "contract_custom_fields": {},  
        "line_items": [  
          {  
            "product_id": "d3d10cd4-e234-4265-91c1-a95f09e6a69c",  
            "product_type": "UsageProductListItem",  
            "product_custom_fields": {  
              "stripe_product_id": "prod_KyVnHhSBWl7eY2bl"  
            },  
            "name": "Usage Product",  
            "total": 22000,  
            "credit_type": {  
                "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",  
                "name": "USD (cents)"  
            },  
            "starting_at": "2024-08-01T00:00:00+00:00",  
            "ending_before": "2024-09-01T00:00:00+00:00",  
            "unit_price": 110,  
            "quantity": 200  
          },  
          ...  
        ]  
      }  
     }