{"openapi":"3.0.3","info":{"title":"Naiwenn API Retraite B2B","version":"1.2.0","description":"Gateway additive autour du moteur retraite. Auth: Bearer nai_<prefix>_<secret> OU OAuth2 client_credentials → JWT. Headers: X-Request-Id (echo), X-RateLimit-*, Idempotency-Key sur runs. IP allowlist CIDR optionnelle par org. Self-service: /api/org/retraite-api. CERTIFIE seulement avec grant restitution.certified + restitutionLevel ≥ 2 ; jamais sur A2A libre. Doc: /docs/api — status: /status/api — guide: docs/API_RETRAITE_B2B.md","contact":{"name":"Naiwenn Support client (API Retraite)","email":"turpinji@gmail.com"},"x-naiwenn-docs":"docs/API_RETRAITE_B2B.md","x-naiwenn-docs-html":"/docs/api","x-naiwenn-status":"/status/api","x-naiwenn-sla":"docs/API_RETRAITE_SLA.md","x-naiwenn-support-ticket-fields":["org_id","key_prefix","X-Request-Id","endpoint","capability","http_status","error_json","runId","utc_timestamp"]},"servers":[{"url":"/api/v1/retraite","description":"Relative (même host app)"},{"url":"https://naiwenn.fr/api/v1/retraite","description":"Production publique"}],"tags":[{"name":"discover","description":"Sans auth — catalogue & spec"},{"name":"auth","description":"OAuth2 client_credentials"},{"name":"runs","description":"Moteur retraite (grants restitution.*)"},{"name":"career","description":"Lacunes / carrière"},{"name":"hooks","description":"Contrepartie employeur / organisme"},{"name":"a2a","description":"Indicatif agents — non opposable"},{"name":"ops","description":"Usage & extensions"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"nai|JWT","description":"Clé nai_… (console ou self-service org) ou access_token OAuth. Ne jamais coller le secret dans un ticket Support — préfixe seul."},"oauth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/api/v1/retraite/oauth/token","scopes":{}}}}},"schemas":{"ErrorBody":{"type":"object","properties":{"error":{"type":"string","examples":["UNAUTHORIZED","CAPABILITY_DENIED","QUOTA_EXCEEDED"]},"message":{"type":"string"},"capabilityId":{"type":"string"},"quota":{"$ref":"#/components/schemas/Quota"}},"required":["error"]},"Quota":{"type":"object","properties":{"periodYm":{"type":"string","example":"2026-07"},"callsUsed":{"type":"integer"},"callsCap":{"type":"integer"},"runsUsed":{"type":"integer"},"runsCap":{"type":"integer"},"callsOk":{"type":"boolean"},"runsOk":{"type":"boolean"}}},"RunRequest":{"type":"object","properties":{"serviceId":{"type":"string","default":"retraite"},"data":{"type":"object","additionalProperties":true},"dossierId":{"type":"string","format":"uuid"},"liquidationDate":{"type":"string","format":"date"},"trigger":{"type":"string","enum":["initial","corpus_rerun"]},"gamme":{"type":"string"},"commerceLevel":{"type":"string"}}},"LacuneOverrideRequest":{"type":"object","required":["lacuneId","typeDonnee"],"properties":{"lacuneId":{"type":"string"},"typeDonnee":{"type":"string"},"valeurEur":{"type":"number"},"valeurEntier":{"type":"integer"},"valeurDecimal":{"type":"number"},"valeurFactor":{"type":"number"},"valeurDate":{"type":"string"},"civilAge":{"type":"object","properties":{"years":{"type":"integer"},"months":{"type":"integer"}}},"pieceJointeRef":{"type":"string"},"data":{"type":"object","additionalProperties":true}}},"SampleItem":{"type":"object","properties":{"id":{"type":"string"},"zone":{"type":"string"},"declared":{"type":"number","nullable":true},"caisseReport":{"type":"number","nullable":true},"tolerance":{"type":"number","nullable":true}}},"HookRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":5000,"items":{"$ref":"#/components/schemas/SampleItem"}}}},"EstimateRequest":{"type":"object","required":["birthYear"],"properties":{"birthYear":{"type":"integer","minimum":1940,"maximum":2010,"example":1975},"revenuAnnuelBrutApproxEur":{"type":"number","example":42000},"anneesCotiseesApprox":{"type":"number","example":28},"carriereComplexeSignalee":{"type":"boolean","default":false},"approxAnnualIncomeEur":{"type":"number","description":"Alias"},"careerYearsApprox":{"type":"number","description":"Alias"}}},"ExtensionTestRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["nexus_event","nexus_webhook"],"default":"nexus_event"}}}}},"security":[{"bearerAuth":[]}],"paths":{"/health":{"get":{"tags":["discover"],"summary":"Health API v1 (public)","security":[],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Corrélation incident — echo sur la réponse."}],"responses":{"200":{"description":"{ ok, enabled, version }"}}}},"/status":{"get":{"tags":["discover"],"summary":"Status / SLA soft (public)","security":[],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Corrélation incident — echo sur la réponse."}],"responses":{"200":{"description":"operational | degraded"},"503":{"description":"major_outage"}}}},"/oauth/token":{"post":{"tags":["auth"],"summary":"OAuth2 client_credentials → access_token JWT","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string"},"client_secret":{"type":"string"}}}}}},"responses":{"200":{"description":"{ access_token, token_type, expires_in }"},"400":{"description":"unsupported_grant_type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"invalid_client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/me":{"get":{"tags":["ops"],"summary":"Introspection clé / grants / quota","parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Corrélation incident — echo sur la réponse."}],"responses":{"200":{"description":"orgId, keyPrefix, grants, quota, expiresAt…"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/manifest":{"get":{"tags":["discover"],"summary":"Catalogue + packs + flag enabled","security":[],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Corrélation incident — echo sur la réponse."}],"responses":{"200":{"description":"Manifest runtime (source de vérité catalogue)"}}}},"/openapi.json":{"get":{"tags":["discover"],"summary":"Cette spécification OpenAPI","security":[],"responses":{"200":{"description":"OpenAPI 3.0 JSON"}}}},"/runs":{"post":{"tags":["runs"],"summary":"Lancer un run moteur","description":"Grant restitution.run. Quota call+run. CERTIFIE gated. Idempotency-Key recommandé.","parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Corrélation incident — echo sur la réponse."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Recommandé sur POST /runs et /lacunes/override (TTL 24h)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"},"example":{"serviceId":"retraite","liquidationDate":"2024-06-01","data":{}}}}},"responses":{"200":{"description":"Run créé (state filtré)"},"401":{"description":"Bearer manquant / invalide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Grant manquant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"IDEMPOTENCY_CONFLICT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Quota dépassé","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Flag RETRAITE_API_V1_ENABLED off","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/runs/{id}":{"get":{"tags":["runs"],"summary":"Rapport filtré","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"proofToken","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Report"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Grant restitution.report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"RUN_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/runs/{id}/proof":{"get":{"tags":["runs"],"summary":"Empreinte / preuve","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"proofToken","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Proof metadata"},"403":{"description":"Grant restitution.proof","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/lacunes/override":{"post":{"tags":["career"],"summary":"Override lacune + rejeu","parameters":[{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Corrélation incident — echo sur la réponse."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Recommandé sur POST /runs et /lacunes/override (TTL 24h)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LacuneOverrideRequest"}}}},"responses":{"200":{"description":"Run rejoué"},"400":{"description":"INVALID_OVERRIDE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Grant career.lacune_override","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"IDEMPOTENCY_CONFLICT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/hooks/exposure":{"post":{"tags":["hooks"],"summary":"Diagnostic exposition employeur","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookRequest"},"example":{"items":[{"id":"1","zone":"T1","declared":4,"caisseReport":3}]}}}},"responses":{"200":{"description":"Diagnostic"},"403":{"description":"Grant hook.exposure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/hooks/precontentieux":{"post":{"tags":["hooks"],"summary":"Pré-contentieux organisme","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookRequest"}}}},"responses":{"200":{"description":"Diagnostic"},"403":{"description":"Grant hook.precontentieux","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/a2a/estimate":{"post":{"tags":["a2a"],"summary":"Fourchette NON_OPPOSABLE_INDICATIVE","description":"Jamais CERTIFIE. Reprendre citationHint / statementForLlm.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateRequest"}}}},"responses":{"200":{"description":"band + imprecision + citation"},"400":{"description":"BIRTH_YEAR_*","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Grant a2a.estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/usage":{"get":{"tags":["ops"],"summary":"Usage + quota org (clé valide)","responses":{"200":{"description":"events + quota"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/extensions/test":{"post":{"tags":["ops"],"summary":"Ping extension Nexus","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtensionTestRequest"}}}},"responses":{"200":{"description":"ok / noop_disabled"}}}}},"x-naiwenn-capabilities":[{"id":"career.ingest","family":"career","label":"Ingestion carrière / OCR","description":"Déposer et ingérer documents / RIS.","moduleIds":["nexusIngestion","validerSource"],"requiresCertifiedGrant":false},{"id":"career.repartition","family":"career","label":"Répartition carrière","description":"Timeline, trimestres, PASS, assimilés.","moduleIds":["repartiteurCarriere","trimestresSalaires","pointsCotises"],"requiresCertifiedGrant":false},{"id":"career.employeur","family":"career","label":"Réconciliation employeur","description":"Écarts trimestres / SMIC sur périodes.","moduleIds":["reconcilierEmployeur"],"requiresCertifiedGrant":false},{"id":"career.lacune_override","family":"career","label":"Override lacunes","description":"Injecter un substitut et rejouer.","moduleIds":[],"requiresCertifiedGrant":false},{"id":"calc.lura","family":"calc","label":"LURA / liquidation unique","description":"Polypension LURA.","moduleIds":["evaluateurLura","liquidationUnique"],"requiresCertifiedGrant":false},{"id":"calc.base","family":"calc","label":"Régimes de base","description":"CNAV / MSA / SSI / annuités.","moduleIds":["montantAnnuites","dispatchRegimesNonAlignes"],"requiresCertifiedGrant":false},{"id":"calc.fp","family":"calc","label":"Fonction publique","description":"Montant indiciaire FP.","moduleIds":["montantIndiciaire"],"requiresCertifiedGrant":false},{"id":"calc.speciaux","family":"calc","label":"Régimes spéciaux","description":"SNCF, RATP, ENIM, CNAVPL, IEG, ITR…","moduleIds":["regimeSpecialFerme","regimeEnim","regimeCnavpl","regimeSpeciauxAutres","regimeUltramarin"],"requiresCertifiedGrant":false},{"id":"calc.agirc","family":"calc","label":"Complémentaire points","description":"AGIRC-ARRCO / valorisation points.","moduleIds":["montantPoints","pointsForfaits","pointsAchat"],"requiresCertifiedGrant":false},{"id":"calc.depart","family":"calc","label":"Départ / modulateurs","description":"Surcote, décote, anticipé, progressive, cumul, C2P, MDA.","moduleIds":["surcoteDecote","departAnticipe","retraiteProgressive","cumulEmploiRetraite","penibiliteC2p","majEducationEnfant","minimumGaranti"],"requiresCertifiedGrant":false},{"id":"control.ecarts","family":"control","label":"Écarts notification","description":"Comparateur + qualification d’écarts.","moduleIds":["comparateurLiquidation","qualificateurEcart"],"requiresCertifiedGrant":false},{"id":"control.supervision","family":"control","label":"Supervision / gate","description":"Superviseur système et isDeliveryReady.","moduleIds":["superviseurSysteme"],"requiresCertifiedGrant":false},{"id":"minima.aspa","family":"minima","label":"ASPA / minima","description":"ASPA et minima de pension.","moduleIds":["aspaEtMinima","aspaEtMinimaFp"],"requiresCertifiedGrant":false},{"id":"minima.reversion","family":"minima","label":"Réversion","description":"Retraite de réversion.","moduleIds":["retraiteDeReversion"],"requiresCertifiedGrant":false},{"id":"minima.sante","family":"minima","label":"Santé / RATH / invalidité","description":"AAH, handicap, conversion invalidité.","moduleIds":["applicateurSante","priseEnChargeHandicap","conversionInvalideRetraite","pensionInvalideConversionForcee"],"requiresCertifiedGrant":false},{"id":"intl.totalisation","family":"intl","label":"Coordination internationale","description":"UE / bilatéral / hors convention.","moduleIds":["droitsEtrangers"],"requiresCertifiedGrant":false},{"id":"restitution.run","family":"restitution","label":"Lancer un run moteur","description":"POST run blueprint retraite (filtrée).","moduleIds":["genererRapport"],"requiresCertifiedGrant":false},{"id":"restitution.report","family":"restitution","label":"Lire un rapport","description":"GET report filtré.","moduleIds":["genererRapport"],"requiresCertifiedGrant":false},{"id":"restitution.proof","family":"restitution","label":"Accès preuve","description":"Proof token / archive.","moduleIds":["superviseurSysteme"],"requiresCertifiedGrant":false},{"id":"restitution.certified","family":"restitution","label":"Livraison CERTIFIE","description":"Autorise restitution opposable si isDeliveryReady.","moduleIds":["superviseurSysteme"],"requiresCertifiedGrant":true},{"id":"hook.exposure","family":"hook","label":"Exposition employeur","description":"Diagnostic échantillon déclarations.","moduleIds":[],"requiresCertifiedGrant":false},{"id":"hook.precontentieux","family":"hook","label":"Pré-contentieux organisme","description":"Détection erreurs avant réclamation.","moduleIds":[],"requiresCertifiedGrant":false},{"id":"a2a.estimate","family":"a2a","label":"Estimation indicative","description":"Fourchette NON_OPPOSABLE_INDICATIVE.","moduleIds":[],"requiresCertifiedGrant":false},{"id":"a2a.ontology","family":"a2a","label":"Ontologie publique","description":"Lecture concepts corpus public.","moduleIds":[],"requiresCertifiedGrant":false},{"id":"ext.nexus_event","family":"ext","label":"Bridge Nexus events","description":"Publier run_completed vers Relation.","moduleIds":[],"requiresCertifiedGrant":false},{"id":"ext.nexus_webhook","family":"ext","label":"Webhook org","description":"POST signé vers URL configurée.","moduleIds":[],"requiresCertifiedGrant":false},{"id":"ext.tool_slot","family":"ext","label":"Slot outils futurs","description":"Buffy / connecteurs — invoke pluggable.","moduleIds":[],"requiresCertifiedGrant":false}],"x-naiwenn-packs":[{"id":"mandataire","label":"Pack mandataire","capabilityIds":["career.ingest","career.repartition","career.lacune_override","calc.lura","calc.base","calc.fp","calc.speciaux","calc.agirc","calc.depart","control.ecarts","control.supervision","minima.aspa","minima.reversion","intl.totalisation","restitution.run","restitution.report","restitution.proof","a2a.estimate"]},{"id":"employeur","label":"Pack employeur","capabilityIds":["hook.exposure","career.employeur","control.ecarts","restitution.report","a2a.estimate"]},{"id":"organisme","label":"Pack organisme / G2B","capabilityIds":["hook.precontentieux","control.ecarts","control.supervision","restitution.report","restitution.proof","a2a.estimate"]},{"id":"a2a","label":"Pack A2A agents","capabilityIds":["a2a.estimate","a2a.ontology"]},{"id":"full","label":"Tout ouvert","capabilityIds":["career.ingest","career.repartition","career.lacune_override","calc.lura","calc.base","calc.fp","calc.speciaux","calc.agirc","calc.depart","control.ecarts","control.supervision","minima.aspa","minima.reversion","intl.totalisation","restitution.run","restitution.report","restitution.proof","a2a.estimate","hook.exposure","career.employeur","hook.precontentieux","a2a.ontology","restitution.certified","minima.sante","ext.nexus_event","ext.nexus_webhook","ext.tool_slot"]}],"x-naiwenn-intents":[{"id":"first_call","label":"Premier appel qui marche","path":"/a2a/estimate"},{"id":"run_dossier","label":"Run moteur dossier","path":"/runs"},{"id":"employer_exposure","label":"Exposition employeur","path":"/hooks/exposure"},{"id":"organism_precontentieux","label":"Pré-contentieux","path":"/hooks/precontentieux"},{"id":"agent_band","label":"Fourchette agent","path":"/a2a/estimate"},{"id":"support_diag","label":"Diagnostiquer un ticket","path":"/usage"}]}