Passer au contenu principal
Lorsque vous migrez vers Hyperline depuis un autre système de facturation, vous pouvez importer vos données historiques à l’aide de points de terminaison d’API en lot. Cela vous permet de maintenir la continuité de vos enregistrements de facturation, de votre reporting et de l’historique de vos clients.
Service d’import dédié disponibleCe guide explique comment importer des données historiques de manière autonome à l’aide de notre API. Toutefois, nous proposons également un service dédié pour vous aider à migrer les données depuis votre système de facturation existant. Si vous préférez bénéficier d’une assistance pour votre migration, contactez-nous via le chat dans l’application ou discutez de cette option avec votre contact commercial.

​
Ce qui peut être importé

Vous pouvez importer les types de données suivants :
  • Clients : fiches clients avec toutes les métadonnées associées
  • Abonnements : abonnements actifs et historiques avec leur configuration
  • Factures : enregistrements de factures incluant les documents PDF

​
Prérequis

Avant d’importer des abonnements et des factures, vous devez configurer votre catalogue de produits dans Hyperline. Les produits référencés dans les imports d’abonnements et de factures doivent déjà exister dans votre compte Hyperline.
Configurez les produits d’abordLes abonnements et factures peuvent nécessiter des identifiants de produit Hyperline valides dans leurs charges utiles d’import. Créez tous les produits nécessaires dans Hyperline avant de commencer votre import de données, sinon l’API rejettera les requêtes avec des références de produit inconnues.
Vous pouvez créer des produits via :

​
Vue d’ensemble du processus d’import

L’ordre d’import recommandé est :
  1. Configurer votre catalogue de produits (requis pour les abonnements et factures)
  2. Importer les clients (requis pour les abonnements et factures)
  3. Importer les abonnements avec leurs dates de début historiques
  4. Importer les factures avec leurs documents PDF
Tester d’abord dans le sandboxTestez toujours votre processus d’import dans l’environnement sandbox avant d’importer des données de production. Cela vous permet de valider votre mappage de données et d’identifier d’éventuels problèmes sans impacter les opérations en direct. Notez que le sandbox n’est pas un clone de la production — vous devrez l’alimenter avec un échantillon représentatif de clients et de produits pour rendre le test à blanc significatif.

​
Importer des clients

Utilisez le point de terminaison de création de clients par lot pour importer plusieurs clients à la fois (jusqu’à 50 par requête). 
curl -X POST https://api.hyperline.co/v1/customers/batch \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "batch_customer_id": "batch_001",
        "name": "Acme Corporation",
        "billing_email": "billing@acme.com",
        "external_id": "cust_123_from_old_system"
      }
    ]
  }'
Le batch_customer_id est requis pour les opérations par lot afin de suivre chaque client dans le lot.
Retrouver les clients via vos anciens identifiantsRenseignez le champ external_id avec l’identifiant client de votre ancien système, et vous pourrez ensuite résoudre les clients via l’API sans maintenir de table de correspondance séparée :
GET /v1/customers?external_id=cust_123_from_old_system
Pour les paramètres détaillés et le format de réponse, consultez la documentation du point de terminaison Create customers batch.

​
Importer des abonnements

Les abonnements peuvent être créés avec des dates de début dans le passé, ce qui vous permet de préserver les données historiques d’abonnement.

​
Points clés pour les imports d’abonnements

  • Date de début : définissez starts_at sur la date de début initiale de l’abonnement dans votre ancien système
  • Date initiale de facturation : définissez initial_billing_at sur la première ou la prochaine date à laquelle Hyperline doit commencer à facturer. Il s’agit généralement de la prochaine date de renouvellement ou de la date à laquelle vous souhaitez que Hyperline prenne en charge les opérations de facturation
  • Stratégie d’activation : utilisez start_date pour activer l’abonnement en fonction de la date starts_at
  • Conditions contractuelles : définissez la durée du contrat et les paramètres de renouvellement
  • Abonnements inactifs : importez les abonnements déjà terminés uniquement si vous en avez besoin pour du reporting historique ; sinon, ignorez-les car ils ne seront pas facturés
curl -X POST https://api.hyperline.co/v2/subscriptions \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_hyperline_id",
    "activation_strategy": "start_date",
    "starts_at": "2023-01-15T00:00:00Z",
    "initial_billing_at": "2026-02-15T00:00:00Z",
    "contract_terms": {
      "activation_strategy": "start_date",
      "end_strategy": "duration",
      "duration": {
        "period": "years",
        "count": 1
      },
      "renew_automatically": true
    },
    "products": [
      {
        "id": "prod_hyperline_id",
        "payment_interval": {
          "period": "years",
          "count": 1
        },
        "payment_schedule": "start"
      }
    ]
  }'
Le id du produit doit référencer un produit qui existe déjà dans votre catalogue de produits Hyperline. Mappez les produits de votre ancien système aux identifiants produits Hyperline avant d’importer les abonnements.

Exemple 💡

Un client a souscrit à votre service le 15 janvier 2023, avec une facturation annuelle. Vous migrez vers Hyperline en janvier 2026. Définissez starts_at à 2023-01-15 (en préservant la date de début initiale) et initial_billing_at à 2026-02-15 (la prochaine date de renouvellement à laquelle Hyperline doit générer la facture).
Pour les paramètres détaillés, consultez la documentation du point de terminaison Create subscription.

​
Importer des factures

Importez les factures historiques pour conserver des enregistrements de facturation complets et permettre un reporting précis.

​
Création de factures en lot

Créez plusieurs factures à la fois (jusqu’à 50 par requête) : 
curl -X POST https://api.hyperline.co/v2/invoices/batch \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_id": "import_batch_2025_01",
    "invoices": [
      {
        "batch_invoice_id": "inv_123_from_old_system",
        "customer_id": "cust_hyperline_id",
        "status": "paid",
        "emitted_at": "2025-01-15T00:00:00Z",
        "due_at": "2025-02-15T00:00:00Z",
        "settled_at": "2025-01-20T00:00:00Z",
        "line_items": [
          {
            "product_id": "prod_hyperline_id",
            "name": "Annual subscription",
            "unit_amount": 12000,
            "units_count": 1
          }
        ]
      }
    ]
  }'
Le point de terminaison renvoie une réponse 202 Accepted avec un batch_id que vous pouvez utiliser pour suivre le traitement du lot : 
{
  "batch_id": "import_batch_2025_01"
}
Le point de terminaison de création de factures par lot traite les factures de manière asynchrone — consultez la section Suivi de la création de factures par lot ci-dessous pour les événements webhook que vous pouvez écouter. Le batch_invoice_id est requis pour suivre chaque facture dans le lot. Chaque ligne doit référencer un product_id de votre catalogue de produits. Pour les factures payées, incluez la date settled_at pour enregistrer quand le paiement a été reçu.
Pour les paramètres détaillés, consultez la documentation du point de terminaison Create invoices.

​
Suivi de la création de factures par lot

Étant donné que la création de factures par lot est asynchrone, vous devriez configurer des écouteurs de webhook pour suivre le succès ou l’échec de chaque facture :
  • invoice.batch.creation_succeeded : déclenché lorsqu’une facture du lot est créée avec succès
  • invoice.batch.creation_failed : déclenché lorsqu’une facture du lot échoue à être créée
Chaque événement webhook inclut le batch_id et le batch_invoice_id pour vous aider à suivre quelles factures ont été traitées avec succès. Consultez la documentation des Webhooks pour plus de détails sur la configuration des points de terminaison webhook.

​
Importer les PDF de factures

Après avoir créé un enregistrement de facture, vous pouvez téléverser le document PDF d’origine de votre ancien système : 
curl -X POST https://api.hyperline.co/v1/invoices/{invoice_id}/upload \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/invoice.pdf"
Cela préserve la mise en forme et l’identité visuelle d’origine de votre ancien système, ce qui peut être important pour les enregistrements clients et la conformité. Pour les paramètres détaillés, consultez la documentation du point de terminaison Upload PDF to invoice.

​
Bonnes pratiques

​
Validation des données

  • Validez toutes les données avant l’import pour vous assurer qu’elles répondent aux exigences de Hyperline
  • Vérifiez les champs requis et la conformité du format des données
  • Testez d’abord avec un petit lot pour identifier les problèmes de mappage

​
Gestion de la taille des lots

  • Traitez les imports par lots de 50 éléments ou moins (limite de l’API)
  • Mettez en place une logique de nouvelle tentative pour les lots en échec
  • Surveillez les limites de débit de l’API pour éviter la limitation

​
Mappage des données

  • Créez un document de mappage entre la structure de données de votre ancien système et celle de Hyperline
  • Mappez d’abord les produits : créez un mappage entre les identifiants produits de votre ancien système et les valeurs product_id Hyperline avant d’importer les abonnements ou les factures
  • Utilisez les champs external_id et metadata pour conserver les références aux identifiants du système d’origine
  • Documentez toute transformation de données ou logique métier appliquée lors de l’import

​
Considérations de calendrier

  • Planifiez les imports pendant les périodes de faible trafic pour minimiser l’impact
  • Importez les clients avant les abonnements et factures (ordre des dépendances)
  • Prévoyez du temps pour la validation et la réconciliation des données après l’import

​
Gestion des dates et fuseaux horaires

  • Tous les horodatages sont interprétés en UTC — passez les dates au format ISO 8601 avec un décalage explicite (par exemple 2026-02-15T00:00:00Z)
  • Une date brute ou une chaîne en heure locale peut décaler le jour de facturation de ±1 sur les factures visibles par le client lorsque votre fuseau horaire diffère de l’UTC
  • Cela importe particulièrement pour starts_at, initial_billing_at, et les champs de facture emitted_at / due_at / settled_at — choisissez le même jour calendaire que celui utilisé par votre ancien système et ajoutez T00:00:00Z

​
Réconciliation

Après l’import :
  • Vérifiez que le nombre de clients correspond entre les systèmes
  • Réconciliez les statuts d’abonnement et les dates de facturation
  • Confirmez les totaux des factures et les statuts de paiement
  • Examinez les données de reporting pour vous assurer de leur exactitude
Opération irréversibleLes imports de données ne peuvent pas être automatiquement annulés. Testez toujours minutieusement dans l’environnement sandbox avant d’importer des données de production. Pensez à conserver des sauvegardes de vos données d’origine jusqu’à ce que vous ayez entièrement validé l’import.