# Charikat.ma — Manuel Exhaustif Open Data, Scraping & API Entreprises Maroc
Version: 2026.1-LIVE
Auteur: Charikat (https://charikat.ma)
Licence: Open Data Commons Attribution License (ODC-By) / CC BY 4.0

---

## 1. Algorithme de Calcul et Vérification ICE (Modulo 97 Maroc)

L'Identifiant Commun de l'Entreprise (ICE) se compose de 15 chiffres décimaux :
- **Position 1 à 9** : Racine unique de l'entreprise (Identifiant de base).
- **Position 10 à 13** : Numéro de succursale ou établissement (0000 = Siège social, 0001 = Succursale 1...).
- **Position 14 à 15** : Clé de contrôle ISO 7064 Modulo 97-10.

### Formule Mathématique Officielle :
```
num = int(ICE[0:13]) * 100
reste = num % 97
cle = 97 - reste
si cle == 97: cle = 0
cle_chaine = f"{cle:02d}"
```

### Exemple Python :
```python
def validate_ice(ice_str: str) -> bool:
    cleaned = ''.join(filter(str.isdigit, str(ice_str)))
    if len(cleaned) != 15:
        return False
    base13 = int(cleaned[:13])
    expected_check = (97 - ((base13 * 100) % 97)) % 97
    return int(cleaned[13:]) == expected_check
```

---

## 2. Guide de Scraping & Requêtage HTTP

Charikat autorise et encourage l'extraction de données à des fins d'analyse, d'enrichissement ERP/CRM, et de recherche académique.

### Headers Recommandés :
```http
User-Agent: MonScraper/1.0 (+https://mon-domaine.com)
Accept: application/json
```

### Formats de Réponse Supportés par Fiche :
- `https://charikat.ma/ice/001589324000179.json` -> Retourne l'objet JSON standardisé.
- `https://charikat.ma/ice/001589324000179.csv` -> Retourne l'enregistrement CSV avec en-têtes.
- `https://charikat.ma/ice/001589324000179.xml` -> Retourne le XML structuré.
- `https://charikat.ma/ice/001589324000179.md` -> Retourne la fiche Markdown haute densité.

---

## 3. Endpoints de l'API REST v1

### A. Recherche Multicritère
`GET https://charikat.ma/api/v1/directory/search`
- `q` : Nom, Dénomination, Enseigne, ICE, RC ou IF.
- `city` : Ville (Casablanca, Rabat, Tanger, Marrakech, Fès, Agadir, etc.).
- `region` : Région administrative marocaine.
- `legal_form` : Forme juridique (SARL, SA, SAS, AU, SNC, GIE).
- `page` : Numéro de page (défaut: 1).
- `per_page` : Résultats par page (1 à 100, défaut: 20).

### B. Recherche par Lot (Batch Lookup)
`POST https://charikat.ma/api/v1/directory/batch-lookup`
```json
{
  "ices": [
    "001589324000179",
    "001526374000085",
    "002194830000045"
  ]
}
```

### C. Export en Masse Filtrable
`GET https://charikat.ma/api/v1/directory/export?format=csv&city=Casablanca&min_capital=1000000`
Formats acceptés : `csv`, `jsonl`, `ndjson`, `json`, `xml`.

---

## 4. Dictionnaire des Données

| Champ | Type | Description | Exemple |
| :--- | :--- | :--- | :--- |
| `ice` | string(15) | Identifiant Commun Entreprise | "001589324000179" |
| `denomination` | string | Raison sociale officielle | "ATTIJARIWAFA BANK SA" |
| `trade_name` | string | Enseigne commerciale | "AWB" |
| `rc_number` | string | Registre de Commerce | "333" |
| `rc_city` / `tribunal` | string | Greffe du Tribunal | "Casablanca" |
| `if_number` | string | Identifiant Fiscal DGI | "01085020" |
| `cnss_number` | string | Numéro d'affilié CNSS | "1002938" |
| `legal_form` | string | Forme juridique | "SA", "SARL", "SAS" |
| `capital_mad` | float | Capital social en Dirhams | 21514083000.0 |
| `headquarters_address` | string | Adresse du siège social | "2, Bd Moulay Youssef" |
| `city` | string | Ville d'établissement | "Casablanca" |
| `region` | string | Région marocaine | "Casablanca-Settat" |
| `activity_code` | string | Nomenclature NMA 2008 | "6419" |
| `activity_description` | string | Objet social & activité | "Services Financiers..." |
| `status` | string | État d'activité | "ACTIVE", "RADIEE" |
| `creation_date` | string | Date de constitution | "1904-01-01" |
| `vigilance_score` | float | Indice de vigilance (0-100) | 99.0 |
| `vigilance_grade` | string | Notation souveraine | "A+", "A", "B", "C", "D" |
| `tax_compliance_status` | string | Statut Art. 145 CGI | "REGULAR", "IRREGULAR" |
| `article_145_compliant` | boolean | Déductibilité TVA garantie | true |

---

## 5. Exemples de Code pour Scrapers

### Python (Requests + Pandas) :
```python
import requests
import pandas as pd

# 1. Télécharger le dump complet CSV
df = pd.read_csv('https://charikat.ma/dumps/companies-morocco.csv')
print(f"Total entreprises: {len(df)}")

# 2. Requête API directe
resp = requests.get('https://charikat.ma/ice/001589324000179.json')
data = resp.json()
print("Dénomination:", data["denomination"])
```

### Node.js / TypeScript :
```typescript
const response = await fetch('https://charikat.ma/ice/001589324000179.json');
const company = await response.json();
console.log(company.denomination, company.rc_number, company.capital_mad);
```

---
Pour toute question d'intégration : contact@charikat.ma