Collections billing_providers / companies / invoices

Vue d’ensemble

La fonctionnalite billing provider repose sur trois zones de donnees :

  • la collection billing_providers pour le catalogue global des providers

  • le sous-document billing_provider dans companies pour la configuration d’une company

  • le sous-document billing_sync dans invoices pour suivre la creation provider et l’envoi email

Collection billing_providers

Catalogue global des providers integres par la plateforme.

Metadonnees

Service proprietaire

backend

Tenant scope

Non

Soft delete

Non

Index principaux

code (unique), is_active

Schema

interface BillingProvider {
  _id: ObjectId;
  code: "billit" | "cic";
  name: string;
  auth_type: "api_key" | "oauth2";
  supported_features: {
    issue_invoice: boolean;
    sync_status: boolean;
    cancel_invoice: boolean;
    download_pdf: boolean;
  };
  is_active: boolean;
  createdAt: Date;
  updatedAt: Date;
}

Notes

  • la V1 seed uniquement billit

  • supported_features decrit les capacites theoriques du provider

  • sync_status est reserve pour une future resynchronisation d’etat depuis le provider

Sous-document companies.billing_provider

Chaque company peut configurer un seul provider.

Schema

interface CompanyBillingProviderConfiguration {
  provider_id: ObjectId;                 // ref: BillingProvider
  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?: Date;
  };
  settings?: {
    party_id?: string;
  };
}

Regles d’integrite

  • un seul provider par company

  • provider_id doit pointer vers un provider existant et actif

  • auth_type doit correspondre au provider catalogue

  • les secrets sont stockes avec select: false et ne sont pas renvoyes par l’API de lecture

  • pour Billit, settings.party_id est requis si la configuration est active

Index

  • billing_provider.provider_id

Sous-document invoices.billing_sync

Trace l’etat de la facture chez le provider et l’etat d’envoi email via Vekteur.

Schema

interface InvoiceBillingSync {
  provider: {
    status: "not_created" | "pending" | "created" | "sent" | "failed";
    invoice_id?: string;
    last_error?: string;
    updated_at?: Date | null;
    sent_at?: Date | null;
  };
  email: {
    status: "not_sent" | "pending" | "sent" | "partial" | "failed";
    last_error?: string;
    recipients?: string[];
    updated_at?: Date | null;
    sent_at?: Date | null;
  };
}

Sens metier actuel

  • provider.status

  • not_created : aucune facture provider encore creee

  • pending : creation provider en cours

  • created : facture creee chez Billit

  • failed : creation provider echouee

  • email.status

  • not_sent : aucun email encore parti

  • sent : tous les destinataires ont recu le mail

  • partial : une partie seulement des destinataires a recu le mail

  • failed : aucun email n’a pu etre envoye

la valeur provider.status = "sent" existe encore dans le schema pour compatibilite, mais le flux V1 recommande n’utilise plus l’envoi Billit. L’envoi client se fait via Vekteur.

Champs importants

  • provider.invoice_id : identifiant externe Billit

  • provider.last_error : dernier message d’erreur provider

  • email.recipients : liste des destinataires effectivement envoyes

  • email.last_error : agregat des erreurs d’envoi

Endpoints qui manipulent ces donnees