Aller au contenu

API Reference

Les 6 services Djinn exposent des APIs REST (FastAPI) avec documentation Swagger auto-générée sur chaque service (/docs).

Convention

Toutes les routes sont préfixées /v1/ (ADR-005). Authentification via header X-API-Key.

Local vs Production

Les exemples de cette documentation utilisent des URLs NodePort (localhost:3000X) pour le développement local Docker Desktop K8s — accès direct aux services pour debug.

En production, toutes les requêtes passent par Kong APIM (https://api.djinn.solyntek.io) qui gère l'authentification par API key, le rate limiting et le routing vers les services internes. Les services ne sont jamais exposés directement en production (ClusterIP uniquement). Voir la documentation interne (Kong APIM, ADR-013).

Kong AI Gateway (Phase 3)

À partir de la Phase 3, le routing LLM sera géré par les plugins Kong AI Gateway (ai-proxy, ai-prompt-template, etc.) pour centraliser les prompts et le fallback multi-provider. Voir ADR-014 (documentation interne).

Premiers pas

1. Base URL

Toutes les requêtes passent par le gateway Kong :

https://api.djinn.solyntek.io

Kong route chaque préfixe /v1/... vers le service interne correspondant : vous n'avez qu'une seule URL et qu'une seule clé à gérer, quel que soit le service appelé.

2. Authentification

Chaque tenant reçoit une API key (associée à un consumer Kong), à passer dans le header X-API-Key de chaque requête :

curl https://api.djinn.solyntek.io/v1/schemas \
  -H "X-API-Key: your-api-key"

Sans clé valide, Kong répond 401 Unauthorized avant même d'atteindre le service. Le rate limiting est également appliqué par clé (429 Too Many Requests au-delà du quota). Voir le guide Authentification.

3. Premier appel : extraire une facture bout-en-bout

L'extraction est synchrone : un seul appel suffit pour envoyer le fichier et récupérer les données structurées.

curl -X POST https://api.djinn.solyntek.io/v1/extract \
  -H "X-API-Key: your-api-key" \
  -F "file=@facture.pdf" \
  -F "document_type=invoice"

{
  "document_type": "invoice",
  "data": {
    "vendor_name": "Acme SARL",
    "invoice_number": "FA-2026-0042",
    "invoice_date": "2026-06-30",
    "total_ht": 1250.00,
    "total_ttc": 1500.00,
    "vat_amount": 250.00,
    "iban": "FR7630001007941234567890185"
  },
  "confidence": 0.93
}

De là, le même JSON peut alimenter les autres services avec la même clé : générer un export comptable (POST /v1/export/fec), vérifier le fournisseur (GET /v1/companies/{siren}/compliance) — chaque appel étant journalisé dans l'audit trail (GET /v1/events).

4. Explorer les APIs

Chaque page service ci-dessous combine un aperçu des routes, des exemples curl et une référence interactive générée depuis la spec OpenAPI versionnée du service.

Services

  • Doc Extract

    POST /v1/extract — Factures, CV, pièces d'identité

    Port 8000 · NodePort 30002

  • Candidate Analyzer

    POST /v1/analyze — Scoring candidats vs postes

    Port 8003 · NodePort 30003

  • AI Assistant

    POST /v1/knowledge-bases/{id}/query — Chat RAG

    Port 8004 · NodePort 30004

  • Export Hub

    POST /v1/export/fec — FEC, Sage, Pennylane, paie

    Port 8005 · NodePort 30005

  • Audit Trail

    POST /v1/events — Journal d'audit RGPD

    Port 8006 · NodePort 30006

  • Company Verifier

    GET /v1/companies/{siren}/compliance

    Port 8007 · NodePort 30007

Specs OpenAPI

Conformément à l'ADR-011, les specs OpenAPI de chaque service sont exportées depuis le code (app.openapi(), sans démarrer de serveur) et committées dans ce repo — source de vérité unique pour les clients tiers, sans besoin d'accès aux repos services.

Service Spec OpenAPI
Doc Extract openapi/doc-extract-v1.json
Candidate Analyzer openapi/candidate-analyzer-v1.json
AI Assistant openapi/ai-assistant-v1.json
Export Hub openapi/export-hub-v1.json
Audit Trail openapi/audit-trail-v1.json
Company Verifier openapi/company-verifier-v1.json

MCP Gateway

Le service mcp-gateway est un cas à part : il expose les capacités des 6 services via le protocole MCP (Model Context Protocol) sur l'endpoint /mcp, à destination des agents et clients MCP (et non d'intégrations REST). Basé sur FastMCP, il n'expose pas d'objet FastAPI et n'a donc pas de spec OpenAPI — c'est pourquoi il n'apparaît pas dans la liste ci-dessus. Voir le catalogue d'outils MCP dans la documentation interne (architecture/mcp-gateway.md).

Régénération : documentation/scripts/export_openapi.py (un run par service, depuis le venv de ce service — voir le docstring du script).