API publique — Spec OpenAPI

Fichier source : /openapi/vitakyc.yaml (30+ endpoints, OpenAPI 3.1).

À ouvrir dans Swagger UI, Redoc, Stoplight Studio ou Postman pour exploration interactive.

Vue d’ensemble

• Base URL production : https://api.vitakyc.io/v1
• Base URL sandbox : https://api.sandbox.vitakyc.io/v1
• Versioning : URL /v1/…, deprecation progressive avec header Deprecation: <date> 6 mois avant.
• Authentification duale :
  • Authorization: Bearer <jwt> — tokens OIDC (user back-office ou impersonation)
  • X-API-Key: <key> — intégrations machine à machine
• Multi-tenant implicite : le tenant est porté par le token, jamais dans le path.
• Idempotence : header Idempotency-Key: <uuid> obligatoire sur tous les POST mutatifs (TTL 24 h).
• Rate limiting : par défaut 100 rps burst, 20 rps sustained. Headers X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After.
• Pagination cursor-based : ?cursor=…&limit=50.
• Format d’erreur : RFC 9457 (application/problem+json).
• Webhooks signés : header X-VitaKYC-Signature: t=<ts>,v1=<hmac-sha256>.

Tags principaux

Tag	Endpoints clés
KYC	POST /kyc/cases, POST /kyc/cases/{id}/documents, POST /kyb/rne/lookup
AML	POST /aml/screen, POST /aml/batches, POST /aml/batches/csv, GET /aml/batches/{id}, POST /aml/transactions/ingest, GET /aml/alerts
TCR	POST /tcr/classifications, POST /tcr/forms, POST /tcr/declarations, POST /tcr/declarations/{id}/submit-ides
Forms	GET /forms/{id}/active, POST /forms/{id}/versions/{vid}/publish
Webhooks	POST /webhooks avec events catalogués

Événements webhooks

Événement	Déclencheur
kyc.case.created	Dossier créé
kyc.case.decided	Décision (auto ou manuelle) prise
aml.alert.created	Nouvelle alerte AML screening / monitoring
aml.batch.completed	Batch screening terminé, rapports disponibles
aml.transaction.alert	Alerte de transaction monitoring
tcr.declaration.generated	XML FATCA / CRS prêt à télécharger
tcr.declaration.submitted	Dépôt IDES confirmé (AD reçu)
form.submission.received	Soumission utilisateur reçue

Ingestion de transactions — formats acceptés

Endpoint POST /aml/transactions/ingest?format=… accepte quatre formats (détail dans AML · Transaction Monitoring) :

• json_vitakyc — modèle canonique VitaKYC (recommandé)
• iso20022_pacs008 — XML ISO 20022 SEPA / RTGS
• swift_mt103 — format flat SWIFT traditionnel
• csv_vitakyc — CSV structuré (batch nocturne)

Génération des SDKs

Le fichier OpenAPI permet de régénérer automatiquement :

• SDK TypeScript avec openapi-typescript + openapi-fetch
• SDK Kotlin avec openapi-generator-cli generate -g kotlin
• SDK Python avec openapi-generator-cli generate -g python
• SDK Java avec openapi-generator-cli generate -g java
• Postman collection (import direct)
• Insomnia workspace

Pipeline CI prévue : à chaque merge sur main, régénération + publication NPM / Maven Central / PyPI des SDKs officiels VitaKYC.

Exemples rapides

Créer un dossier KYC

curl -X POST https://api.vitakyc.io/v1/kyc/cases \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "CLIENT-2026-00123",
    "subject_type": "individual",
    "workflow_code": "default-tn-v1",
    "locale": "fr-TN"
  }'

Screening AML synchrone (avec translittération arabe)

curl -X POST https://api.vitakyc.io/v1/aml/screen \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "subject": {
      "full_name": "محمد بن علي",
      "full_name_transliterations": ["Mohamed Ben Ali","Muhammad Ibn Ali"],
      "dob": "1985-03-12",
      "nationality": "TN"
    },
    "lists": ["OFAC","UN","EU","HMT","BCT_LOCAL"]
  }'

Générer FATCA XML v2.0 conforme DGI Tunisie

curl -X POST https://api.vitakyc.io/v1/tcr/declarations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "reporting_fi_giin": "00Z148.00027.ME.788",
    "reporting_period": "2025",
    "type": "FATCA1",
    "filer_category": "FATCA601",
    "auto_submit_ides": false
  }'

Le webhook tcr.declaration.generated informe quand le XML est prêt et disponible via GET /tcr/declarations/{id}/xml.

---

Spec complète : /openapi/vitakyc.yaml. À importer dans votre outil préféré pour exploration et génération SDK.