Aller au contenu

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

{
    "status": "string",
    "service": "string",
    "version": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

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

[
    {
        "format": "string",
        "description": "string",
        "category": "string"
    }
]
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/FormatInfo"
    },
    "title": "Response Formats V1 Formats Get"
}

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

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

Schema of the response body

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body
{
    "properties": {
        "entries": {
            "items": {
                "$ref": "#/components/schemas/JournalEntry"
            },
            "type": "array",
            "minItems": 1,
            "title": "Entries"
        }
    },
    "type": "object",
    "required": [
        "entries"
    ],
    "title": "SageExportRequest",
    "description": "Requête d'export Sage 100."
}

Responses

Schema of the response body

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body
{
    "properties": {
        "entries": {
            "items": {
                "$ref": "#/components/schemas/JournalEntry"
            },
            "type": "array",
            "minItems": 1,
            "title": "Entries"
        }
    },
    "type": "object",
    "required": [
        "entries"
    ],
    "title": "PennylaneExportRequest",
    "description": "Requête d'export Pennylane."
}

Responses

Schema of the response body

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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

{
    "data": [
        {}
    ],
    "delimiter": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

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

Schema of the response body

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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

{
    "data": [
        {
            "employee_id": "string",
            "period": "string",
            "gross_salary": null,
            "net_salary": null,
            "employer_charges": null,
            "employee_charges": null
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body
{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/PayrollEntry"
            },
            "type": "array",
            "minItems": 1,
            "title": "Data"
        }
    },
    "type": "object",
    "required": [
        "data"
    ],
    "title": "PayrollEntryExportRequest",
    "description": "Requête d'export paie standardisé."
}

Responses

Schema of the response body

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

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

Schema of the response body

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

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

Schema of the response body

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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

{
    "content": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body
{
    "properties": {
        "content": {
            "type": "string",
            "minLength": 1,
            "title": "Content"
        }
    },
    "type": "object",
    "required": [
        "content"
    ],
    "title": "FECValidateRequest",
    "description": "Requête de validation FEC."
}

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
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

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."
}

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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

{
    "content": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body
{
    "properties": {
        "content": {
            "type": "string",
            "minLength": 1,
            "title": "Content"
        }
    },
    "type": "object",
    "required": [
        "content"
    ],
    "title": "FECValidateRequest",
    "description": "Requête de validation FEC."
}

Responses

"string"
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "string"
}

"string"
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "string"
}

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

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