Documentation API

Intégrez la vérification de documents d'identité dans vos applications avec l'API Ma CNI Perdue.

Introduction

L'API Ma CNI Perdue permet aux partenaires (banques, opérateurs télécom, administrations) de vérifier si un document d'identité a été déclaré perdu ou trouvé sur notre plateforme.

URL de base

https://www.macniperdue.ci/api/v1

Sécurisé

HTTPS + Auth API Key

Rapide

< 200ms en moyenne

REST JSON

Format standard

Authentification

Toutes les requêtes doivent inclure votre clé API. Trois méthodes sont supportées :

1. Header Authorization (recommandé)

bash

curl -X GET "https://www.macniperdue.ci/api/v1/check/CI001234567" \
  -H "Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxxx"

2. Header X-API-Key

bash

curl -X GET "https://www.macniperdue.ci/api/v1/check/CI001234567" \
  -H "X-API-Key: mcp_xxxxxxxxxxxxxxxxxxxxx"

3. Query Parameter (déconseillé)

bash

curl "https://www.macniperdue.ci/api/v1/check/CI001234567?api_key=mcp_xxxxx"

⚠️ Ne partagez jamais votre clé API. Elle donne accès à votre compte partenaire.

Vérifier un document

GET/api/v1/check/{numero}

Vérifie si un document a été déclaré perdu ou trouvé dans notre base de données.

Paramètres

Nom	Type	Description
`numero`	string	Numéro du document (requis, min 4 caractères)
`type`	string	Type de document (optionnel) : cni, passport, permis...
`name`	string	Nom sur le document (optionnel)

Exemple de requête

bash

curl -X GET "https://www.macniperdue.ci/api/v1/check/CI001234567?type=cni" \
  -H "Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxxx"

Réponse succès (200)

json

{
  "success": true,
  "data": {
    "document_number": "CI001234567",
    "is_declared_lost": true,
    "is_declared_found": false,
    "lost_declarations": [
      {
        "id": "uuid-xxx",
        "document_type": "cni",
        "document_name": "KOUASSI",
        "document_first_name": "Jean",
        "city": "Abidjan",
        "date": "2024-01-15",
        "declared_at": "2024-01-16T10:30:00Z"
      }
    ],
    "found_declarations": [],
    "recommendation": "Ce document a été déclaré perdu. Veuillez vérifier l'identité du porteur."
  },
  "meta": {
    "checked_at": "2024-01-20T14:30:00Z",
    "partner": "Votre Organisation"
  },
  "timestamp": "2024-01-20T14:30:00Z"
}

Statistiques

Stats publiques

GET/api/v1/stats/public

bash

curl -X GET "https://www.macniperdue.ci/api/v1/stats/public" \
  -H "Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxxx"

Stats partenaire

GET/api/v1/stats/partner

Retourne vos statistiques d'utilisation de l'API.

bash

curl -X GET "https://www.macniperdue.ci/api/v1/stats/partner?days=30" \
  -H "Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxxx"

Déclarer un document

ℹ️ Ces endpoints nécessitent les permissions declare_lost ou declare_found.

Déclarer un document perdu

POST/api/v1/documents/lost

json

{
  "document_type": "cni",
  "document_number": "CI001234567",
  "document_name": "KOUASSI",
  "document_first_name": "Jean",
  "gender": "M",
  "birth_year": 1990,
  "lost_date": "2024-01-15",
  "lost_city": "Abidjan",
  "lost_area": "Cocody",
  "description": "Perdu dans un taxi"
}

Déclarer un document trouvé

POST/api/v1/documents/found

Mêmes paramètres mais avec found_city, found_date, etc.

Gestion des erreurs

L'API retourne des erreurs au format JSON standardisé :

json

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Clé API invalide, expirée ou désactivée",
    "details": null
  },
  "timestamp": "2024-01-20T14:30:00Z"
}

Codes d'erreur

Code	HTTP	Description
`MISSING_API_KEY`	401	Clé API non fournie
`INVALID_API_KEY`	401	Clé API invalide ou expirée
`INSUFFICIENT_PERMISSIONS`	403	Permission manquante
`RATE_LIMIT_EXCEEDED`	429	Trop de requêtes
`INTERNAL_ERROR`	500	Erreur serveur

Limites de taux (Rate Limiting)

Les headers suivants sont inclus dans chaque réponse :

X-RateLimit-Limit : Limite par minute
X-RateLimit-Remaining : Requêtes restantes
X-RateLimit-Reset : Date de réinitialisation

Si vous atteignez la limite, attendez la réinitialisation ou passez à un plan supérieur.

Tarification

Gratuit

0 FCFA

✓ 100 requêtes/mois
✓ Endpoint /check
✓ Stats publiques
✗ Déclarations API

Populaire

Pro

50,000 FCFA/mois

✓ 10,000 requêtes/mois
✓ Tous les endpoints
✓ Stats détaillées
✓ Support email

Entreprise

200,000 FCFA/mois

✓ 100,000 requêtes/mois
✓ API dédiée
✓ SLA 99.9%
✓ Support prioritaire

Gouvernement

Sur devis

✓ Illimité
✓ Intégration sur-mesure
✓ Formation
✓ Support dédié

Contactez-nous pour discuter de vos besoins →