Facturer avec d'autres systèmes

Ce guide explore comment configurer la facturation dans des systèmes non couverts par les intégrations natives de Metronome. Pour prendre en charge ces workflows, vous pouvez collaborer avec Metronome afin de créer des exports de données ou de construire une intégration managée qui se connecte au système de facturation de votre choix. Les intégrations managées sont construites en utilisant la fonctionnalité d’export de données ou les API Metronome.

Approche d’intégration

Souvent, les intégrations prêtes à l’emploi vers des plateformes de facturation ne répondent pas aux exigences fondamentales des clients et nécessitent une personnalisation importante. Cela tient au fait qu’elles se concentrent sur la synchronisation des données sans tenir compte du cas d’usage de bout en bout et du modèle d’affaires. À l’inverse, les intégrations managées avec Metronome adoptent une approche fondée sur les principes premiers pour répondre aux exigences de facturation des clients. À mesure que Metronome investit davantage dans différents modèles d’affaires, nous évaluons en permanence l’opportunité de construire de nouvelles intégrations natives vers d’autres plateformes de facturation, comme nos solutions Facturation avec Stripe, Facturation avec NetSuite et Facturation avec les marketplaces. Pour en savoir plus sur la configuration d’une intégration managée, contactez votre représentant Metronome.

Configuration d’un fournisseur de facturation externe

Cette configuration décrit comment envoyer des données de facture à des fournisseurs de facturation externes en aval à l’aide de l’API Metronome. Bien que cet exemple soit spécifique à QuickBooks, le schéma et les choix de conception s’appliquent à d’autres cas d’usage. Avant de configurer dans Metronome, vérifiez si votre plateforme de facturation nécessite une configuration supplémentaire, par exemple des prérequis organisationnels ou des permissions pour créer des factures. Par exemple, QuickBooks nécessite une application Developer pour synchroniser les factures :

Créez une application Intuit Developer. Rendez-vous sur developer.intuit.com, créez une application et sélectionnez le scope Accounting.
Notez vos Client ID et Client Secret depuis la page Keys & Credentials de l’application.
Définissez un Redirect URI pour votre endpoint de callback OAuth.
Réalisez le flow OAuth 2.0 pour obtenir un access token et un refresh token.
Notez votre Realm ID (Company ID) — il identifie l’entreprise QBO dans laquelle vous écrivez.

Une fois cette configuration terminée, passez aux étapes suivantes.

Configurer les objets requis

Pour prendre en charge ce cas d’usage, commencez par construire vos objets client et item dans votre système de facturation sélectionné et stockez-les dans des champs personnalisés dans Metronome. Apprenez-en plus sur l’utilisation des champs personnalisés. Champs personnalisés recommandés dans Metronome :

Entité Metronome	Clé du champ personnalisé	Valeur
Product	`qbo_item_id`	L’ID d’Item QBO pour ce produit Metronome
Customer	`qbo_customer_id`	L’ID de Customer QBO pour ce client Metronome
Contract	`qbo_memo_ref`	Optionnel — référence pour aider à lier les contrats aux factures dans QBO

Mapping des clients

Pour chaque client Metronome, trouvez ou créez un Customer QBO correspondant. L’approche recommandée est de stocker l’ID de Customer QBO en tant que champ personnalisé sur l’objet client Metronome (par exemple, qbo_customer_id). Si aucune correspondance n’est trouvée, créez le client dans QBO et stockez l’ID de Customer QBO obtenu dans Metronome en tant que champ personnalisé.

Mapping des items

Vous avez deux stratégies pour mapper les lignes de facture Metronome aux Items QBO :

Stratégie	Comment ça marche	Compromis
Item par produit	Créez un item QBO pour chaque produit Metronome (par exemple, « Warehouse Compute », « API Calls »). Mappez via `product_id`.	Les rapports QBO ventilent le revenu par produit. Nécessite une gouvernance des items et des conventions de nommage.
Item unique	Créez un seul item QBO générique (par exemple, « Metronome Usage »). Toutes les lignes référencent ce seul item.	Moins de détails dans les rapports QBO (tout le revenu apparaît sous une seule catégorie). Configuration simple et rapide.

Intégrer via l’API

Suivez cette approche recommandée pour pousser les factures vers votre fournisseur de facturation en aval en construisant une intégration au-dessus des API Metronome :

Configurez un endpoint webhook et écoutez l’événement invoice.finalized. Cet événement est créé lorsqu’une facture est finalisée dans Metronome à la fin de la période de grâce.

{
  "id": "f4988a54-effe-49a2-9a07-8adfedb7541c",
  "type": "invoice.finalized",
  "properties": {
    "invoice_id": "d23458e0-c9a0-5538-8e81-251835b9f57a",
    "customer_id": "e0ac4251-74f7-4040-a1bd-9d0ef0fbc5bc",
    "invoice_finalized_date": "2024-10-09T17:52:27.371Z"
  }
}

REMARQUEL’événement invoice.finalized n’est pas activé par défaut pour les clients Metronome. Pour activer cet événement, contactez votre représentant Metronome.

Ce webhook fournit customer_id et invoice_id. Utilisez customer_id pour interroger l’endpoint /listInvoices pour les factures finalized de la période de facturation associée.

curl -X GET https://api.metronome.com/v1/customers/e0ac4251-74f7-4040-a1bd-9d0ef0fbc5bc/invoices \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d "status=FINALIZED" \
  -d "starting_on=2024-10-09T00:00:00.000Z" \
  -d "ending_before=2024-10-10T00:00:00.000Z"

La réponse comprend les objets de facture complets avec les champs d’en-tête (id, status, total, subtotal, issued_at, start_timestamp, end_timestamp, contract_id) ainsi que le tableau line_items avec les détails par ligne (name, type, quantity, unit_price, total, product_id, etc.).

Analysez et transformez la réponse au format approprié, puis upsertez la facture et les lignes.
REMARQUEPour QuickBooks, il vous faut un client et au moins un item existants.

Transformer et mapper les champs

C’est le cœur de l’intégration — convertir le schéma de facture de Metronome en formats attendus pour les factures. Voici un exemple de mapping vers les champs QuickBooks.

Mapping de l’en-tête de facture

Champ Metronome	Champ QBO	Notes
customer_id	CustomerRef.value	Utilisez votre mapping stocké de Customer QBO
issued_at	TxnDate	Partie date uniquement. Repli sur end_timestamp si null
invoice.id	DocNumber	QBO impose une limite de longueur stricte. Utilisez « MTR- » + les 8 premiers caractères de l’UUID
end_timestamp	DueDate	Ou définissez un terme de paiement (par exemple, Net30) à partir de TxnDate
(multiple)	PrivateNote	Stockez des champs tels que : Invoice ID complet, statut, période de facturation, contract ID, nom du contrat
(multiple)	CustomerMemo	Résumé lisible par un humain de la période de facturation et du plan

Mapping des lignes

Champ Metronome	Champ QBO	Notes
line.name	SalesItemLineDetail.ItemRef	Mappez vers votre Item QBO (unique ou par produit)
line.quantity	SalesItemLineDetail.Qty	Passez directement la valeur
line.unit_price	SalesItemLineDetail.UnitPrice	Passez directement la valeur
line.total	Line.Amount	Vérifiez si les montants sont en cents ou en dollars et convertissez en conséquence
(composite)	Line.Description	Incluez : nom de la ligne, type, fenêtre temporelle, valeurs du pricing group, product_id

Créer la facture

Une fois toutes les dépendances résolues et les champs mappés, assemblez et POSTez la facture. Dans QuickBooks, le format ressemble à :

POST /v3/company/{realmId}/invoice?minorversion=75
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "CustomerRef": { "value": "{qbo_customer_id}" },
  "TxnDate": "2026-03-01",
  "DocNumber": "MTR-EF9E4917",
  "PrivateNote": "Metronome invoice ef9e4917-... ",
  "Line": [
    {
      "Amount": 7599.42,
      "DetailType": "SalesItemLineDetail",
      "Description": "Warehouse Compute (usage)...",
      "SalesItemLineDetail": {
        "ItemRef": { "value": "{qbo_item_id}" },
        "Qty": 140.73,
        "UnitPrice": 54.00
      }
    }
  ]
}

Orchestration

Pour construire la couche d’orchestration nécessaire, vous pouvez choisir de tirer parti des environnements de développement existants ou d’un outil tiers. Si vous étudiez des outils tiers, Metronome recommande d’utiliser le système iPaaS Workato. Workato est un outil d’automatisation qui permet aux organisations de transformer et de transmettre des données à l’aide de fonctionnalités de construction de workflow en pointer-cliquer. Metronome a publié un connecteur dans la bibliothèque publique Workato, qui agit comme un wrapper de l’API Metronome similaire à un SDK. L’utilisation de ces connecteurs publics peut accélérer la vitesse de développement et apporter de la clarté sur la manière d’interagir avec les différents endpoints. Pour en savoir plus sur l’intégration à l’API ou l’utilisation des connecteurs publics, contactez votre représentant Metronome.

​Approche d’intégration

​Configuration d’un fournisseur de facturation externe

​Configurer les objets requis

​Mapping des clients

​Mapping des items

​Intégrer via l’API

​Transformer et mapper les champs

​Mapping de l’en-tête de facture

​Mapping des lignes

​Créer la facture

​Orchestration

Approche d’intégration

Configuration d’un fournisseur de facturation externe

Configurer les objets requis

Mapping des clients

Mapping des items

Intégrer via l’API

Transformer et mapper les champs

Mapping de l’en-tête de facture

Mapping des lignes

Créer la facture

Orchestration