Insurance
At a glance
Insurance ties mandatory liability cover to every issued license through an auto-created InsurancePolicy, supports optional add-ons (equipment, travel, accident) with one-active-per-season constraint, generates per-player insurance certificates with policy and group references, runs a full claim-submission workflow with documents and audit trail, and manages GroupInsurancePolicy at club, district, and federation level with batch CSV/XML/JSON export and acknowledgement to insurance providers.
How it works
Every issued license automatically creates an InsurancePolicy with an auto-generated policy number, the tenant's configured provider, coverage amount, and an optional link to a group policy. The tenant InsuranceConfig defines coverage_type, default_coverage_amount, provider contact email, and provider API endpoint — so each federation can plug in its own insurer (MAIF in France, Folksam in Sweden, ARAG in Germany, etc.) without code changes. When the license is issued, the policy is created in the same transaction so liability cover is never lost between license activation and policy creation.
Optional add-ons are modelled as InsuranceAddonSubscription records linked to an addon_code that must exist in the tenant's InsuranceConfig.optional_addons catalogue. Premium amounts are pulled from the InsuranceAddon definition and a constraint enforces one active subscription per player per addon per season; subscribe and cancel endpoints handle the lifecycle. Insurance certificates — used by players when traveling abroad or by clubs when submitting documentation — are generated via a single endpoint that returns policy number, addon coverages, group policy number, and coverage amount (from the policy or the tenant default), giving the PDF renderer everything it needs.
Claims run through a proper workflow: submitted → under_review → approved or rejected → paid. Claims are gated per tenant (claims_enabled flag); each claim carries ClaimDocument attachments and a ClaimStatusChange audit trail. Invalid status transitions return HTTP 409. The review endpoint records approved_amount, paid_amount, and the provider_claim_reference so the trail is complete from initial submission to insurance-company settlement.
Group insurance is modelled by GroupInsurancePolicy at club, district, or federation level: when individual policies link to a group policy, the group's member count is auto-incremented; coverage per member, renewal management, and member listing endpoints round out the model. Provider integration uses InsuranceProviderExport to track batch exports of policies, claims, renewals, and cancellations in CSV, XML, or JSON, with provider acknowledgement workflow, file URL generation, and provider_reference tracking — so the integration to the insurer is auditable end to end.
Key capabilities
- Mandatory liability InsurancePolicy auto-created with every license
- Optional add-ons (equipment, travel, accident) with one-active-per-player-per-season constraint
- Insurance certificate generation with policy number, addons, group reference, and coverage amount
- Full claim workflow with documents, status audit trail, and provider reference
- GroupInsurancePolicy at club, district, and federation level with auto member count
- Provider export batches in CSV, XML, or JSON with acknowledgement workflow
- Per-tenant InsuranceConfig for provider, coverage type, and amounts
In practice
A French player slips at a tournament and breaks a wrist. The club opens an InsuranceClaim against the player's MAIF policy, attaches a medical report and incident description as ClaimDocuments, and submits. The federation insurance officer moves the claim from submitted to under_review, requests a missing document via the same workflow, and once received marks it approved with an approved_amount of 850 EUR.
The export job picks up the claim in the next nightly InsuranceProviderExport batch as XML and pushes it to MAIF; MAIF acknowledges with a provider_claim_reference. When MAIF settles, the federation marks the claim paid with the final paid_amount. The player downloads an updated insurance certificate showing the active policy, the equipment add-on subscription, and the group-policy reference — all from a single endpoint.
Features in this subsystem
6| ID | Status | Features |
|---|---|---|
| F03.05.01 | Shipped | Insurance integration with license (mandatory liability) — InsurancePolicy model tied to License with auto-generated policy numbers, per-tenant provider config, coverage amounts, group policy linkage. Tenant InsuranceConfig extended with coverage_type, default_coverage_amount, provider_contact_email, provider_api_endpoint — PL-F0305 ✅ PL-F0305 |
| F03.05.02 | Shipped | Optional insurance add-ons (equipment, travel, accident) — InsuranceAddonSubscription model with addon_code validated against tenant's InsuranceConfig.optional_addons, premium tracking from InsuranceAddon.premium_amount, subscribe/cancel workflow, one active subscription per player/addon/season — PL-F0305 ✅ PL-F0305 |
| F03.05.03 | Shipped | Insurance certificate generation — Enhanced /insurance/certificate/{player_id}/{season_id} with policy_number, addon_coverages list, group_policy_number, coverage_amount from policy or tenant default. Comprehensive certificate data for PDF rendering — PL-F0305 ✅ PL-F0305 |
| F03.05.04 | Shipped | Claim submission workflow — InsuranceClaim model with full status workflow (submitted→under_review→approved/rejected→paid), ClaimDocument attachments, ClaimStatusChange audit trail, per-tenant claims_enabled gating, valid transition enforcement (409 on invalid), review endpoint with approved_amount/paid_amount/provider_claim_reference — PL-F0305 ✅ PL-F0305 |
| F03.05.05 | Shipped | Insurance provider integration (API/file exchange) — InsuranceProviderExport model tracking batch exports (policies/claims/renewals/cancellations) in csv/xml/json, export generation with record counting, provider acknowledgement workflow, file_url generation, provider_reference tracking — PL-F0305 ✅ PL-F0305 |
| F03.05.06 | Shipped | Group insurance management for clubs/federations — GroupInsurancePolicy model for club/district/federation-level policies, member count tracking (auto-incremented when individual policies linked), coverage per member, renewal management, member listing endpoint, per-tenant group_policies_enabled gating — PL-F0305 ✅ PL-F0305 |
Stakeholders who need this subsystem
Surfaces in 2 stakeholder analyses