API Billing Providers

Cette section documente la V1 de l’integration billing provider.

Choix produit actuels :

  • Billit est utilise pour creer la facture chez le provider

  • l’envoi client se fait via Vekteur par email

  • le PDF facture est recupere depuis Billit avant envoi

Voir aussi Collections billing providers / companies / invoices.

Vue d’ensemble

Le flux metier recommande est le suivant :

  1. lister les providers disponibles

  2. configurer un provider unique sur la company

  3. creer une facture Vekteur

  4. creer la facture chez le provider

  5. recuperer le PDF provider

  6. envoyer le PDF au client via Vekteur

Authentification

Tous les endpoints ci-dessous requierent authMiddleware.

Regles complementaires :

  • GET /api/billing-providers requiert une authentification simple

  • les endpoints company billing provider requierent requireMembership({ applications: ['distrib'], roles: ['admin'] })

  • les endpoints invoice provider requierent aussi requireMembership({ applications: ['distrib'], roles: ['admin'] })

GET /api/billing-providers

Retourne le catalogue des providers actifs.

Reponse

  • 200 - liste des providers actifs

Exemple de reponse

[
  {
    "_id": "6656c2d6c7d4d7b1fd8d7c11",
    "code": "billit",
    "name": "Billit",
    "auth_type": "api_key",
    "supported_features": {
      "issue_invoice": true,
      "sync_status": false,
      "cancel_invoice": false,
      "download_pdf": true
    },
    "is_active": true
  }
]

GET /api/companies/:id/billing-provider

Retourne la configuration billing provider de la company, sous forme sanitisee.

Les secrets ne sont jamais retournes. A la place, l’API expose des flags has_*.

Reponses

  • 200 - configuration retournee

  • 404 - company introuvable

Exemple de reponse

{
  "provider": {
    "_id": "6656c2d6c7d4d7b1fd8d7c11",
    "code": "billit",
    "name": "Billit",
    "auth_type": "api_key"
  },
  "enabled": true,
  "mode": "sandbox",
  "auth_type": "api_key",
  "settings": {
    "party_id": "123456"
  },
  "credentials": {
    "has_api_key": true,
    "has_access_token": false,
    "has_refresh_token": false,
    "has_client_id": false,
    "has_client_secret": false
  }
}

PUT /api/companies/:id/billing-provider

Configure ou remplace le provider unique de la company.

Corps de la requete

{
  provider_id: string;                // ObjectId du provider
  enabled: boolean;
  mode: "sandbox" | "production";
  auth_type: "api_key" | "oauth2";
  credentials?: {
    api_key?: string;
    access_token?: string;
    refresh_token?: string;
    client_id?: string;
    client_secret?: string;
    redirect_uri?: string;
    token_expires_at?: string;        // ISO datetime
  };
  settings?: {
    party_id?: string;
  };
}

Validation metier

  • provider_id doit exister dans billing_providers

  • le provider doit etre actif

  • auth_type doit correspondre au auth_type du provider

  • si enabled = true et auth_type = "api_key", credentials.api_key est requis

  • si enabled = true et provider = billit, settings.party_id est requis

Reponses

  • 200 - configuration sanitisee retournee

  • 400 - provider non configure, inactif, incoherent ou incomplet

  • 404 - company ou provider introuvable

Exemple Billit

{
  "provider_id": "6656c2d6c7d4d7b1fd8d7c11",
  "enabled": true,
  "mode": "sandbox",
  "auth_type": "api_key",
  "credentials": {
    "api_key": "billit_api_key_here"
  },
  "settings": {
    "party_id": "123456"
  }
}

PATCH /api/companies/:id/billing-provider/mode

Met a jour uniquement le mode du provider configure.

Corps de la requete

{
  "mode": "sandbox"
}

Reponses

  • 200 - configuration sanitisee retournee

  • 400 - aucun provider configure

DELETE /api/companies/:id/billing-provider

Supprime completement la configuration billing provider de la company.

Reponses

  • 200 - { "success": true }

  • 404 - company introuvable

POST /api/client/documents/:companyId/invoices/:id/create-on-provider

Cree la facture chez le billing provider configure pour la company.

Dans la V1 actuelle :

  • l’appel cree la facture chez Billit

  • il ne l’envoie pas au client

  • l’identifiant externe est stocke dans billing_sync.provider.invoice_id

Reponses

  • 200 - facture mise a jour

  • 400 - provider absent, desactive, configuration incomplete, ou facture deja creee chez le provider

  • 404 - facture introuvable

Effets sur billing_sync

  • succes :

  • billing_sync.provider.status = "created"

  • billing_sync.provider.invoice_id = <id provider>

  • echec :

  • billing_sync.provider.status = "failed"

  • billing_sync.provider.last_error = <message>

POST /api/client/documents/:companyId/invoices/:id/create-on-provider-and-email

Cree la facture chez le provider si necessaire, recupere le PDF provider, puis envoie ce PDF par email via Vekteur.

Corps de la requete

{
  from: string;               // email expediteur
  to: string | string[];      // un ou plusieurs destinataires
}

Comportement

  • si la facture existe deja chez le provider, elle n’est pas recreee

  • le backend recupere le PDF provider avant envoi

  • la recuperation PDF inclut un retry court pour laisser au provider le temps de generer le fichier

Reponses

  • 200 - { invoice, sent, failed }

  • 404 - facture introuvable ou PDF provider indisponible apres retries

  • 400 - provider non configure ou configuration incomplete

Effets sur billing_sync

  • partie provider :

  • status = "created" en cas de succes

  • partie email :

  • status = "sent" si tous les destinataires ont recu le mail

  • status = "partial" si seulement une partie a recu le mail

  • status = "failed" si aucun mail n’a pu partir

GET /api/client/documents/:companyId/invoices/:id/provider-pdf

Recupere le PDF de la facture depuis le billing provider et le renvoie inline.

Reponse

  • 200 - contenu binaire PDF

  • 400 - facture non creee chez le provider

  • 404 - facture introuvable ou fichier provider indisponible

Headers de reponse

  • Content-Type: application/pdf

  • Content-Disposition: inline; filename="<nom fichier>"

Notes d’implementation

  • seul Billit est seed et supporte dans la V1

  • party_id designe la societe emettrice chez Billit, pas le client destinataire

  • Customer dans le payload Billit est construit a partir de invoice.customer_snapshot

  • le flux d’envoi officiel est : creation chez Billit, puis email via Vekteur