API interne Bricks — guide d'intégration

Les routes /internal/* exposent les données Bricks aux applications consommatrices internes hébergées hors monorepo (ticketing/care, support, IA WhatsApp, gestion des défauts, projet-analyse, ai-agent, middleware facturation Axonaut, espace financement Bubble) — en remplacement des requêtes SQL directes sur la base Postgres. Ce guide s'adresse aux devs de ces apps.

Authentification

Une seule clé API par header, propre à chaque app consommatrice :

x-api-key: <clé de l'app>

App	Type (dans la doc OpenAPI)	Variable d'env (côté Bricks)
Ticketing / care	ticketing	TICKETING_API_KEY_INTERNAL
IA WhatsApp	ia-whatsapp	IA_WHATSAPP_API_KEY_INTERNAL
Gestion des défauts	gestion-defauts	GESTION_DEFAUTS_API_KEY_INTERNAL
Projet-analyse	projet-analyse	PROJET_ANALYSE_API_KEY_INTERNAL
AI Agent	ai-agent	AI_AGENT_API_KEY_INTERNAL
Facturation frais de gestion (middleware Axonaut + Bubble)	project-owner-invoicing	PROJECT_OWNER_INVOICING_API_KEY_INTERNAL

• Une route peut accepter plusieurs apps : les apps autorisées figurent dans la description de chaque opération de la doc OpenAPI (ex. Apps autorisées : ticketing, ia-whatsapp).
• Clé absente ou invalide → 401. La clé est obligatoire en production.
• Vérifier rapidement une clé : curl -H "x-api-key: $TA_CLE" https://api.bricks.co/internal/docs/json → 200 (401 si la clé est invalide).
• Pour obtenir une clé, demande à l'équipe Bricks (la valeur n'est jamais dans le code ni dans la doc).

Endpoints disponibles

Routes regroupées par domaine ci-dessous. Le contrat OpenAPI fait foi (params, schémas, apps autorisées).

Investisseurs — /internal/investors

Route	Objet
POST /lookup	Recherche un lot d'emails / téléphones / UUIDs → investisseurs
GET /search	Recherche par nom, ou derniers investisseurs créés
GET /{investorId}/identity	Identité, coordonnées, statut KYC
GET /{investorId}/balances	Soldes (compte, retirable, cadeau), en cents
GET /{investorId}/payment-methods	Moyens de paiement / IBAN
GET /{investorId}/tax-rates	Taux d'imposition par année
GET /{investorId}/portfolio	Portefeuille : totaux + ventilation par type de contrat
GET /{investorId}/projects	Projets investis (position, statut)
GET /{investorId}/wallet-transactions	Mouvements de portefeuille
GET /{investorId}/revenue-transactions	Revenus (imposables / non imposables)
GET /{investorId}/referral	Parrainage : code propre, code utilisé, parrain
GET /{investorId}/auto-invest-plan	Dernier plan d'investissement automatique

Projets — /internal/projects

Route	Objet
GET /	Liste des projets (référentiel 24 colonnes)
GET /search	Recherche projet par nom / référence
GET /{projectId}	Détail d'un projet
GET /repayment-status	État de remboursement consolidé pour un lot de projets
GET /{projectId}/owner	Porteur du projet (personne morale / physique)
GET /{projectId}/spv	Société véhicule (SPV) liée au projet

Porteur de projet / facturation — /internal/project-owner

Route	Objet
GET /management-fees-invoicing/{period}	Frais de gestion du mois (montants HT/TVA/TTC) + axonautId de la société porteuse à facturer
GET /{projectId}/invoicing-ids	siren + axonautId + invoiceNinjaId de la société porteuse d'un projet (404 si pas de correspondance)

Segments — /internal/segments

SQL opérateur (équipe marketing) ; chaque endpoint exécute la même requête contre des outputs différents. Voir l'architecture (section Segments — SQL opérateur) pour les garde-fous.

Route	Objet
POST /recipients	Liste les investorId matchant un SQL
POST /count	Compte les destinataires sans renvoyer la liste
POST /preview	Échantillon (50 lignes) du SQL pour validation visuelle

Leaderboard vitrine — /internal/leaderboard

Authentifié par x-api-key (consommateur site-vitrine) — la data n'expose aucune donnée sensible (publicInvestorId opaque, jamais le customerId). Données précalculées (1 refresh / jour). Voir le module Leaderboard pour le flow, les limites et la roadmap.

Route	Objet
POST /top	Top investisseurs paginé (rank, revenus mois courant, all-time)
POST /statistics	Globals dérivés (investorCount, totalCouponRevenue, totalInvested, …)
POST /investor	Une ligne du leaderboard + time series 12 mois + investmentsByProject (lookup par publicInvestorId)

Projet Analyse — /internal/projet-analyse/project/{projectId}

Contrat machine-to-machine avec l'outil d'analyse : lecture de l'état d'un dossier de financement (phase 1) et actions d'instruction (questions, demandes de documents, refus, offre). Les mutations répondent sans corps — POST en 201, PUT en 200 ; l'état frais se relit toujours via le GET /.

Route	Objet
GET /	État complet phase 1 : statut, questions, demandes de documents, présentation, emprunteur, documents déposés (URLs presigned)
POST /questions	Pousser une question au porteur → passe le dossier en blocked
POST /document-requests	Réclamer un document nominatif → blocked
POST /comment	Commentaire analyste affiché sur la page bloquée → blocked
PUT /missing-documents	Synchroniser la liste des documents manquants (remplacement total)
PUT /document/{documentId}/refuse	Marquer un document déposé comme refusé
POST /offer	Pousser une offre de financement versionnée
POST /reject	Rejeter le dossier avec un commentaire

Récupérer le contrat OpenAPI

Le contrat est servi par l'API au format JSON, scopé au namespace /internal (pas de page HTML : c'est le JSON qui fait foi) :

Environnement	Spec JSON
Production	https://api.bricks.co/internal/docs/json
Staging	https://api.staging.bricks.co/internal/docs/json
Local	http://localhost:<port>/internal/docs/json

La spec est protégée

L'endpoint exige le même header x-api-key que les routes (n'importe quelle clé d'outil interne). Sans clé → 401. Le contrat n'est donc pas public.

Générer un client typé

La spec étant protégée, récupère-la une fois avec ta clé, puis génère depuis le fichier local — le plus simple est openapi-typescript + openapi-fetch (léger, zéro code runtime généré) :

curl -H "x-api-key: $BRICKS_API_KEY" https://api.bricks.co/internal/docs/json -o bricks-internal-openapi.json
npx openapi-typescript bricks-internal-openapi.json -o src/bricks-internal.d.ts

import createClient from 'openapi-fetch'
import type { paths } from './bricks-internal'

const client = createClient<paths>({
  baseUrl: 'https://api.bricks.co',
  headers: { 'x-api-key': process.env.BRICKS_API_KEY },
})

// Entièrement typé depuis la spec : path params, query et réponse
const { data, error } = await client.GET('/internal/investors/{investorId}/identity', {
  params: { path: { investorId } },
})

Besoin d'explorer la doc visuellement ? Pointe un viewer sur le même fichier local — npx @redocly/cli build-docs bricks-internal-openapi.json -o internal-api.html, ou ouvre le JSON dans Swagger Editor ou Scalar.

Côté Bricks ?

Comment ces routes sont construites (couches, contrat zod, validation, clés par app, doc auto, tests) → Architecture & décisions.