Dernière mise à jour : 15 octobre 2026
Export Hub API¶
Port local (Docker Compose) : 30005 | Repo : solyntek/djinn/services/djinn-export-hub
Exports de données financières vers des formats comptables et paie standards français.
Endpoints¶
| Méthode | Route | Description |
|---|---|---|
GET |
/health |
Health check |
GET |
/v1/formats |
Formats d'export disponibles |
POST |
/v1/export/fec |
Export FEC (norme DGFiP) |
POST |
/v1/export/sage |
Export Sage 100 |
POST |
/v1/export/pennylane |
Export Pennylane |
POST |
/v1/export/csv |
Export CSV générique |
POST |
/v1/export/payroll |
CSV paie standardisé (data : salarié, période AAAA-MM, brut, net, charges patronales et salariales) |
POST |
/v1/export/payroll/silae |
Éléments variables Silae |
POST |
/v1/export/payroll/payfit |
Éléments variables PayFit |
POST |
/v1/validate/fec |
Valider un FEC existant (content) : anomalies structurées |
POST |
/v1/validate/fec/report |
Même contrôle, rendu en rapport Markdown pour le cabinet |
Toutes les routes sauf /health exigent X-API-Key. Les routes d'export renvoient le fichier lui-même (Content-Disposition: attachment), pas du JSON. /v1/export/sage et /pennylane prennent entries (écritures, au moins 1) ; /v1/export/csv prend data (1 à 100 000 lignes) et delimiter (défaut ;) ; /v1/export/payroll/silae et /payfit prennent variables (éléments variables de paie, période AAAA-MM).
Format FEC¶
18 colonnes obligatoires (norme DGFiP) : JournalCode, JournalLib, EcritureNum, EcritureDate, CompteNum, CompteLib, CompAuxNum, CompAuxLib, PieceRef, PieceDate, EcritureLib, Debit, Credit, EcritureLet, DateLet, ValidDate, Montantdevise, Idevise.
POST /v1/export/fec prend siren (9 chiffres), fiscal_year_start, fiscal_year_end et entries (lignes FEC). Le fichier est séparé par des barres verticales (|), en UTF-8 avec BOM, dates AAAAMMJJ, montants avec virgule décimale. Nom normalisé : {SIREN}FEC{YYYYMMDD}.txt (fin d'exercice).
Validation FEC¶
POST /v1/validate/fec renvoie valid, line_count, total_debit, total_credit, balance_ok, le separator détecté, blocking_count, warning_count et anomalies : chacune porte un code de règle (ex. FEC-COL-001), une severity (blocking ou warning), la line et la column concernées, un message, une reference et une remediation. Les messages ne contiennent jamais de donnée comptable. errors et warnings (chaînes simples) sont conservés pour compatibilité. Chaque contrôle est consigné dans l'audit trail (compteurs et codes de règle uniquement).
Erreurs¶
Les erreurs suivent le format FastAPI, {"detail": ...} : 401 (clé API absente ou invalide), 422 (requête invalide, ex. entries vide, SIREN pas sur 9 chiffres, dates invalides), 500 (l'événement d'audit d'un contrôle FEC n'a pas pu être écrit).
Référence interactive¶
Générée à chaque build depuis la spec versionnée openapi/export-hub-v1.json (ADR-011) — aucune route documentée à la main.
Djinn Export Hub 0.1.0¶
Exports comptables FEC/Sage/Pennylane et éléments variables paie
Endpoints¶
GET /health¶
Health
Description
Health check endpoint.
Responses
Schema of the response body
{
"properties": {
"status": {
"type": "string",
"title": "Status",
"default": "ok"
},
"service": {
"type": "string",
"title": "Service",
"default": "export-hub"
},
"version": {
"type": "string",
"title": "Version",
"default": "0.1.0"
}
},
"type": "object",
"title": "HealthResponse",
"description": "Response for the health check endpoint."
}
GET /v1/formats¶
Formats
Description
List all supported export formats.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Responses
POST /v1/export/fec¶
Export Fec
Description
Generate a FEC file from journal entries.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
{
"siren": "string",
"fiscal_year_start": "2022-04-13",
"fiscal_year_end": "2022-04-13",
"entries": [
{
"journal_code": "string",
"journal_lib": "string",
"ecriture_num": "string",
"ecriture_date": "2022-04-13",
"compte_num": "string",
"compte_lib": "string",
"comp_aux_num": "string",
"comp_aux_lib": "string",
"piece_ref": "string",
"piece_date": "2022-04-13",
"ecriture_lib": "string",
"debit": null,
"credit": null,
"ecriture_let": "string",
"date_let": null,
"valid_date": null,
"montant_devise": null,
"idevise": "string"
}
]
}
Schema of the request body
{
"properties": {
"siren": {
"type": "string",
"maxLength": 9,
"minLength": 9,
"pattern": "^\\d{9}$",
"title": "Siren",
"description": "SIREN (9 chiffres)"
},
"fiscal_year_start": {
"type": "string",
"format": "date",
"title": "Fiscal Year Start",
"description": "Début exercice fiscal"
},
"fiscal_year_end": {
"type": "string",
"format": "date",
"title": "Fiscal Year End",
"description": "Fin exercice fiscal"
},
"entries": {
"items": {
"$ref": "#/components/schemas/FECLine"
},
"type": "array",
"minItems": 1,
"title": "Entries"
}
},
"type": "object",
"required": [
"siren",
"fiscal_year_start",
"fiscal_year_end",
"entries"
],
"title": "FECExportRequest",
"description": "Requête d'export FEC."
}
Responses
POST /v1/export/sage¶
Export Sage
Description
Generate a Sage 100 export file.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
{
"entries": [
{
"journal_code": "string",
"journal_label": "string",
"entry_number": "string",
"entry_date": "2022-04-13",
"account_number": "string",
"account_label": "string",
"aux_account": null,
"aux_label": null,
"piece_ref": "string",
"piece_date": "2022-04-13",
"label": "string",
"debit": null,
"credit": null,
"lettrage": null,
"lettrage_date": null,
"validation_date": null,
"currency_amount": null,
"currency_code": null
}
]
}
Responses
POST /v1/export/pennylane¶
Export Pennylane
Description
Generate a Pennylane export file.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
{
"entries": [
{
"journal_code": "string",
"journal_label": "string",
"entry_number": "string",
"entry_date": "2022-04-13",
"account_number": "string",
"account_label": "string",
"aux_account": null,
"aux_label": null,
"piece_ref": "string",
"piece_date": "2022-04-13",
"label": "string",
"debit": null,
"credit": null,
"lettrage": null,
"lettrage_date": null,
"validation_date": null,
"currency_amount": null,
"currency_code": null
}
]
}
Responses
POST /v1/export/csv¶
Export Csv
Description
Generate a generic CSV export.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
Schema of the request body
{
"properties": {
"data": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"maxItems": 100000,
"minItems": 1,
"title": "Data"
},
"delimiter": {
"type": "string",
"maxLength": 1,
"title": "Delimiter",
"default": ";"
}
},
"type": "object",
"required": [
"data"
],
"title": "CSVExportRequest",
"description": "Requête d'export CSV générique."
}
Responses
POST /v1/export/payroll¶
Export Payroll
Description
Generate a standardised payroll CSV export.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
Responses
POST /v1/export/payroll/silae¶
Export Silae
Description
Generate Silae payroll variable elements export.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
{
"variables": [
{
"employee_id": "string",
"employee_name": "string",
"period": "string",
"code": "string",
"label": "string",
"quantity": null,
"rate": null,
"amount": null,
"unit": "string",
"comment": null
}
]
}
Schema of the request body
{
"properties": {
"variables": {
"items": {
"$ref": "#/components/schemas/PayrollVariable"
},
"type": "array",
"minItems": 1,
"title": "Variables"
}
},
"type": "object",
"required": [
"variables"
],
"title": "PayrollExportRequest",
"description": "Requête d'export éléments variables paie (Silae/PayFit)."
}
Responses
POST /v1/export/payroll/payfit¶
Export Payfit
Description
Generate PayFit payroll variable elements export.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
{
"variables": [
{
"employee_id": "string",
"employee_name": "string",
"period": "string",
"code": "string",
"label": "string",
"quantity": null,
"rate": null,
"amount": null,
"unit": "string",
"comment": null
}
]
}
Schema of the request body
{
"properties": {
"variables": {
"items": {
"$ref": "#/components/schemas/PayrollVariable"
},
"type": "array",
"minItems": 1,
"title": "Variables"
}
},
"type": "object",
"required": [
"variables"
],
"title": "PayrollExportRequest",
"description": "Requête d'export éléments variables paie (Silae/PayFit)."
}
Responses
POST /v1/validate/fec¶
Validate Fec Endpoint
Description
Validate an existing FEC file content.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
Responses
{
"valid": true,
"errors": [
"string"
],
"warnings": [
"string"
],
"line_count": 0,
"total_debit": 10.12,
"total_credit": 10.12,
"balance_ok": true,
"anomalies": [
{
"code": "string",
"severity": "blocking",
"line": null,
"column": null,
"message": "string",
"reference": "string",
"remediation": "string"
}
],
"separator": null,
"blocking_count": 0,
"warning_count": 0,
"had_bom": true
}
Schema of the response body
{
"properties": {
"valid": {
"type": "boolean",
"title": "Valid",
"default": true
},
"errors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Errors"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array",
"title": "Warnings"
},
"line_count": {
"type": "integer",
"title": "Line Count",
"default": 0
},
"total_debit": {
"type": "number",
"title": "Total Debit",
"default": 0.0
},
"total_credit": {
"type": "number",
"title": "Total Credit",
"default": 0.0
},
"balance_ok": {
"type": "boolean",
"title": "Balance Ok",
"default": true
},
"anomalies": {
"items": {
"$ref": "#/components/schemas/FecAnomaly"
},
"type": "array",
"title": "Anomalies"
},
"separator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Separator"
},
"blocking_count": {
"type": "integer",
"title": "Blocking Count",
"default": 0
},
"warning_count": {
"type": "integer",
"title": "Warning Count",
"default": 0
},
"had_bom": {
"type": "boolean",
"title": "Had Bom",
"default": false
}
},
"type": "object",
"title": "FECValidationResult",
"description": "Résultat de validation FEC."
}
POST /v1/validate/fec/report¶
Validate Fec Report
Description
Validate a FEC file and return the accountant-facing Markdown report.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
X-API-Key |
header | No |
Request body
Responses
Schemas¶
CSVExportRequest¶
| Name | Type | Description |
|---|---|---|
data |
Array<> | |
delimiter |
string |
FecAnomaly¶
| Name | Type | Description |
|---|---|---|
code |
string | Code de règle, ex. FEC-COL-001 |
column |
Nom normé de la colonne visée, ex. PieceDate ; None si global | |
line |
Numéro de ligne dans le fichier (1 = en-tête) ; None si global | |
message |
string | Phrase complète en français, sans donnée comptable |
reference |
string | Texte de référence vérifié |
remediation |
string | Ce que le cabinet doit faire pour corriger |
severity |
FecSeverity |
FECExportRequest¶
| Name | Type | Description |
|---|---|---|
entries |
Array<FECLine> | |
fiscal_year_end |
string(date) | Fin exercice fiscal |
fiscal_year_start |
string(date) | Début exercice fiscal |
siren |
string | SIREN (9 chiffres) |
FECLine¶
| Name | Type | Description |
|---|---|---|
comp_aux_lib |
string | |
comp_aux_num |
string | |
compte_lib |
string | |
compte_num |
string | |
credit |
||
date_let |
||
debit |
||
ecriture_date |
string(date) | |
ecriture_let |
string | |
ecriture_lib |
string | |
ecriture_num |
string | |
idevise |
string | |
journal_code |
string | |
journal_lib |
string | |
montant_devise |
||
piece_date |
string(date) | |
piece_ref |
string | |
valid_date |
FecSeverity¶
Type: string
FECValidateRequest¶
| Name | Type | Description |
|---|---|---|
content |
string |
FECValidationResult¶
| Name | Type | Description |
|---|---|---|
anomalies |
Array<FecAnomaly> | |
balance_ok |
boolean | |
blocking_count |
integer | |
errors |
Array<string> | |
had_bom |
boolean | |
line_count |
integer | |
separator |
||
total_credit |
number | |
total_debit |
number | |
valid |
boolean | |
warning_count |
integer | |
warnings |
Array<string> |
FormatInfo¶
| Name | Type | Description |
|---|---|---|
category |
string | |
description |
string | |
format |
string |
HealthResponse¶
| Name | Type | Description |
|---|---|---|
service |
string | |
status |
string | |
version |
string |
HTTPValidationError¶
| Name | Type | Description |
|---|---|---|
detail |
Array<ValidationError> |
JournalEntry¶
| Name | Type | Description |
|---|---|---|
account_label |
string | Libellé du compte |
account_number |
string | Numéro de compte (PCG) |
aux_account |
Compte auxiliaire | |
aux_label |
Libellé auxiliaire | |
credit |
||
currency_amount |
||
currency_code |
ISO 4217 | |
debit |
||
entry_date |
string(date) | Date de l'écriture |
entry_number |
string | Numéro d'écriture |
journal_code |
string | Code journal (VE, HA, BQ, OD, ...) |
journal_label |
string | Libellé du journal |
label |
string | Libellé de l'écriture |
lettrage |
Code de lettrage | |
lettrage_date |
||
piece_date |
string(date) | Date de la pièce |
piece_ref |
string | Référence de la pièce |
validation_date |
PayrollEntry¶
| Name | Type | Description |
|---|---|---|
employee_charges |
Charges salariales | |
employee_id |
string | Identifiant salarié |
employer_charges |
Charges patronales | |
gross_salary |
Salaire brut | |
net_salary |
Salaire net | |
period |
string | Periode YYYY-MM |
PayrollEntryExportRequest¶
| Name | Type | Description |
|---|---|---|
data |
Array<PayrollEntry> |
PayrollExportRequest¶
| Name | Type | Description |
|---|---|---|
variables |
Array<PayrollVariable> |
PayrollVariable¶
| Name | Type | Description |
|---|---|---|
amount |
Montant calculé | |
code |
string | Code rubrique paie |
comment |
||
employee_id |
string | Identifiant salarié |
employee_name |
string | Nom complet |
label |
string | Libellé de l'élément |
period |
string | Periode YYYY-MM |
quantity |
Quantité (jours, heures) | |
rate |
Taux (TJM, taux horaire) | |
unit |
string | Unité (jours, heures, forfait) |
PennylaneExportRequest¶
| Name | Type | Description |
|---|---|---|
entries |
Array<JournalEntry> |
SageExportRequest¶
| Name | Type | Description |
|---|---|---|
entries |
Array<JournalEntry> |
ValidationError¶
| Name | Type | Description |
|---|---|---|
ctx |
||
input |
||
loc |
Array<> | |
msg |
string | |
type |
string |