Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.korint.io/llms.txt

Use this file to discover all available pages before exploring further.

FVA (Fichier des Véhicules Assurés) is the French regulatory file that centrally tracks all insured vehicles in France. This integration ensures that every vehicle insured on our platform is declared to this official file, so it is legally recognized as insured.

​
How It Works

The FVA integration works in three steps:

​
1. Automated Report Generation

Every day at midnight, an automated job generates a report listing all vehicles whose insurance coverage changed during the previous 3 days (started, stopped, suspended, reactivated, or first payment received). The report includes:
  • Vehicle registration number
  • Insurer code
  • Broker code
  • Asset id (internal reference)
  • Coverage start and end dates
  • Operation type (see below)
The system produces two files:
  • A CSV file for internal review
  • An XML file in a ZIP ready for submission to the FVA
Why a 3-day rolling window? Each eligible vehicle is re-declared on 3 consecutive daily runs. AGIRA dedups via the “garantie existe déjà” rejection (silent and cheap), so the overlap is harmless. The window acts as a built-in retry for transient DNS/network errors, late-arriving payment webhooks, and any single missed cron run — without needing a separate sweeper job.

​
2. Automatic Submission

Once generated, the report is automatically uploaded to the FVA API via the upload-to-connector mechanism using the FVA connector (ConnectorType.FVA in tenant configuration). The submission uses the tenant’s secure certificate. The upload job is configured with maxAttempts: 3, so transient failures (DNS errors like EAI_AGAIN, ECONNRESET, etc.) are retried up to 3 times before the job is marked as failed. If the AGIRA API accepts the upload but returns no refInterneEmetteur (operation code), the job throws a FAILED_TO_UPLOAD_REPORT error rather than silently succeeding — this avoids “ghost” successes where the file was sent but the retrieval was never scheduled. If the file is accepted, a scheduled job is automatically created to retrieve the integration report one hour later.

​
3. Report Retrieval

One hour after the file is accepted, a scheduled job automatically retrieves the integration report from the FVA API. This report lists:
  • Accepted vehicles: Successfully registered in the FVA file. For each accepted vehicle, the system marks the corresponding asset as declared to FVA.
  • Rejections: Vehicles that were rejected, with error codes and reasons.
This allows to track which declarations were successful and identify any data issues that need correction.

​
Operation Types

Each line in the FVA report indicates what happened to the vehicle’s coverage:

​
C - Coverage Creation

When: A vehicle’s coverage is declared as active. This happens in two cases:
  1. Standard: The asset started during the reporting period and at least one invoice has been paid.
  2. Deferred (first payment): The asset started in a previous period but its first invoice was paid during the current reporting period (see First Payment Gating below).
Example: An asset coverage starts on January 15th and the first invoice is paid → One line with operation type C, start date = 15/01, end date = empty.

​
M - Coverage Modification

When: A policy is suspended or reactivated during the reporting period. Suspension: The policy is suspended → One M line with end date = suspension date (coverage is paused). Reactivation: The policy is reactivated → One M line with end date = empty (coverage is active again). Example: A policy is suspended on January 18th → One line with operation type M, start date = original start date, end date = 18/01. Then reactivated on January 25th → One line with operation type M, start date = original start date, end date = empty.

​
R - Coverage Termination

When: A vehicle’s coverage was stopped during the reporting period. Example: An asset coverage stops on January 20th → One line with operation type R, end date = 20/01.

​
Multiple Operations in the Same Period

A single vehicle can generate multiple lines in the same report if several events occur in the same period. For example:
  • Started and stopped → C line + R line
  • Suspended and reactivated → Two M lines

​
First Payment Gating

The FVA declaration of a new coverage (C line) is not sent when the asset starts. Instead, it is deferred until the first invoice is paid. Why: A vehicle should only be declared as insured in the FVA once the policyholder has actually paid. This avoids declaring vehicles where the coverage was never effectively activated. How it works:
  1. An asset starts on January 10th but no invoice has been paid yet → No C line is generated.
  2. The first invoice is paid on January 20th → A C line is generated in the January 20th report, with start date = January 10th (the original start date).
Edge case: If the asset starts and an invoice is already paid during the same reporting period, the C line is generated immediately in that period’s report.

​
Late-arriving Payment Events

Stripe webhooks can arrive significantly later than the actual payment (e.g., SEPA settlement delays, retries, or transient handler failures). When that happens, the INVOICE_PAID event is created days after the original paidAt (the Stripe payment date is backdated onto the projection). To avoid losing these late events, the FVA report does not filter on the invoice’s paidAt field. Instead it filters on paidEventCreatedAt — the timestamp at which our system actually persisted the INVOICE_PAID event. Combined with the 3-day rolling window, a late event arriving on day N is automatically picked up by the cron runs on days N+1, N+2, and N+3.
paidEventCreatedAt is set on every new INVOICE_PAID event. Invoices marked paid before this field was introduced are not yet backfilled — they are caught by the FVA cron only via their asset’s start/stop date (branches 1-2), not via the late-payment branch.