Aller au contenu principal

Référence de l'API OmniHSS

← Retour au Guide des Opérations

Table des Matières​

Aperçu de l'API​

URL de Base​

https://[hostname]:8443/api

Format de la Demande​

  • Content-Type : application/json
  • Protocole : HTTPS uniquement
  • Port : 8443 (configurable)

Important : Tous les points de terminaison de l'API attendent des charges utiles JSON "plates" sans objets enveloppants.

Format Correct :

{
  "name": "value",
  "field": "value"
}

Format Incorrect (Ne Pas Utiliser) :

{
  "subscriber": {
    "name": "value",
    "field": "value"
  }
}

Exemple :

# ✓ Correct
curl -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "ifc_template": "..."}'

# ✗ Incorrect
curl -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{"ims_profile": {"name": "default", "ifc_template": "..."}}'

Format de la Réponse​

Toutes les réponses sont en JSON avec la structure suivante :

Réponse de Succès :

{
  "status": "success",
  "response": { ... }
}

Réponse d'Erreur :

{
  "status": "error",
  "response": {
    "invalid_fields": {
      "field_name": "error message"
    }
  }
}

Codes de Statut HTTP​

CodeSignificationCas d'Utilisation
200OKGET, PUT, DELETE réussi
201CrééPOST réussi
400Mauvaise DemandeDonnées d'entrée invalides
404Non TrouvéLa ressource n'existe pas
422Entité Non TraitableErreur de validation
500Erreur Interne du ServeurErreur côté serveur

Flux de Demande API​

Gestion des Abonnés​

Lister les Abonnés​

Récupérer tous les abonnés ou filtrer par critères.

Point de Terminaison : GET /api/subscriber

Paramètres de Requête :

ParamètreTypeDescription
enabledbooleanFiltrer par statut activé
ims_enabledbooleanFiltrer par statut IMS activé

Exemple de Demande :

curl -k https://hss.example.com:8443/api/subscriber

Exemple de Réponse :

{
  "data": [
    {
      "id": 1,
      "imsi": "001001123456789",
      "enabled": true,
      "ims_enabled": true,
      "sim_id": 1,
      "key_set_id": 1,
      "epc_profile_id": 1,
      "ims_profile_id": 1,
      "roaming_profile_id": 1,
      "custom_attributes": {},
      "inserted_at": "2025-10-15T10:30:00Z",
      "updated_at": "2025-10-15T10:30:00Z"
    }
  ]
}

Obtenir un Abonné par ID​

Récupérer un abonné spécifique par ID de base de données.

Point de Terminaison : GET /api/subscriber/:id

Paramètres de Chemin :

ParamètreTypeDescription
idintegerID de base de données de l'abonné

Exemple de Demande :

curl -k https://hss.example.com:8443/api/subscriber/1

Obtenir un Abonné par IMSI​

Récupérer un abonné par son IMSI.

Point de Terminaison : GET /api/subscriber/imsi/:imsi

Paramètres de Chemin :

ParamètreTypeDescriptionFormat
imsistringIdentité Internationale d'Abonné Mobile14-15 chiffres

Exemple de Demande :

curl -k https://hss.example.com:8443/api/subscriber/imsi/001001123456789

Cas d'Utilisation : Dépannage d'un abonné spécifique par son IMSI.

Obtenir un Abonné par MSISDN​

Récupérer un abonné par son numéro de téléphone.

Point de Terminaison : GET /api/subscriber/msisdn/:msisdn

Paramètres de Chemin :

ParamètreTypeDescriptionFormat
msisdnstringNuméro ISDN de la Station Mobile1-15 chiffres (E.164)

Exemple de Demande :

curl -k https://hss.example.com:8443/api/subscriber/msisdn/14155551234

Cas d'Utilisation : Recherche d'informations sur un abonné lorsque vous n'avez que son numéro de téléphone.

Créer un Abonné​

Provisionner un nouvel abonné.

Point de Terminaison : POST /api/subscriber

Corps de la Demande :

{
  "subscriber": {
    "imsi": "001001123456789",
    "enabled": true,
    "ims_enabled": true,
    "sim_id": 1,
    "key_set_id": 1,
    "epc_profile_id": 1,
    "ims_profile_id": 1,
    "roaming_profile_id": 1,
    "custom_attributes": {
      "note": "Abonné de test"
    }
  }
}

Champs Requis :

  • imsi - Doit être de 14 à 15 chiffres, unique
  • key_set_id - Doit référencer un Ensemble de Clés existant
  • epc_profile_id - Doit référencer un Profil EPC existant

Champs Optionnels :

  • enabled - Par défaut : true
  • ims_enabled - Par défaut : true
  • sim_id - Référence à une carte SIM
  • ims_profile_id - Référence à un Profil IMS (requis pour les services IMS)
  • roaming_profile_id - Référence à un Profil de Roaming (requis pour le contrôle du roaming)
  • msisdns - Tableau d'IDs MSISDN (numéros de téléphone)
  • static_ips - Tableau d'IDs IP Statique pour les affectations APN
  • custom_attributes - Paires clé-valeur personnalisées

Voir Également :

Exemple de Demande :

curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "imsi": "001001123456789",
      "key_set_id": 1,
      "epc_profile_id": 1
    }
  }'

Flux de Provisionnement :

Mettre à Jour un Abonné​

Modifier un abonné existant.

Point de Terminaison : PUT /api/subscriber/:id

Paramètres de Chemin :

ParamètreTypeDescription
idintegerID de base de données de l'abonné

Corps de la Demande :

{
  "subscriber": {
    "enabled": false,
    "ims_enabled": false,
    "epc_profile_id": 2,
    "custom_attributes": {
      "note": "Désactivé temporairement"
    }
  }
}

Champs Modifiables :

Non Modifiable :

  • imsi - Ne peut pas changer l'IMSI (supprimer et recréer à la place)

Voir Également :

Exemple de Demande :

curl -k -X PUT https://hss.example.com:8443/api/subscriber/1 \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "enabled": false
    }
  }'

Cas d'Utilisation :

  • Désactiver temporairement un abonné : {"enabled": false}
  • Désactiver uniquement les services vocaux : {"ims_enabled": false}
  • Changer le profil de service : {"epc_profile_id": 2} (voir Profils EPC)
  • Mettre à jour la politique de roaming : {"roaming_profile_id": 3} (voir Gestion du Roaming)

Supprimer un Abonné​

Retirer un abonné du système.

Point de Terminaison : DELETE /api/subscriber/:id

Paramètres de Chemin :

ParamètreTypeDescription
idintegerID de base de données de l'abonné

Exemple de Demande :

curl -k -X DELETE https://hss.example.com:8443/api/subscriber/1

Avertissement : Cela supprime définitivement l'abonné et toutes les données d'état associées (sessions PDN, appels, etc.). L'IMSI peut être réutilisé après la suppression.

Remarque : La suppression d'un abonné ne supprime PAS les éléments associés :

  • Ensemble de Clés - Peut être réutilisé pour d'autres abonnés
  • SIM - Peut être réattribuée à un nouvel abonné
  • Profils - Ressources partagées utilisées par plusieurs abonnés
  • MSISDNs - Doivent être supprimés séparément si désiré

Annuler la Demande de Localisation (Détachement Forcé)​

Envoyer une Demande d'Annulation de Localisation (CLR) pour forcer le détachement d'un abonné de son MME actuellement enregistré.

Point de Terminaison : POST /api/subscriber/cancel_location

Corps de la Demande :

{
  "imsi": "001001123456789"
}

Paramètres :

ParamètreTypeRequisDescription
imsistringOuiIMSI de l'abonné à détacher (14-15 chiffres)

Exemple de Demande :

curl -k -X POST https://hss.example.com:8443/api/subscriber/cancel_location \
  -H "Content-Type: application/json" \
  -d '{"imsi": "001001123456789"}'

Réponse de Succès (200 OK) :

{
  "data": {
    "message": "Demande d'Annulation de Localisation envoyée avec succès",
    "imsi": "001001123456789",
    "destination_host": "mme01.operator.com",
    "destination_realm": "epc.operator.com"
  }
}

Réponse d'Erreur (404 Non Trouvé) :

{
  "error": "Abonné non trouvé ou non enregistré actuellement à aucun MME"
}

Comportement :

  • Envoie un CLR S6a au MME où l'abonné est actuellement enregistré (subscriber_state.last_seen_mme)
  • Utilise Cancellation-Type: subscription_withdrawal (force le détachement complet)
  • Définit CLR-Flags: {s6a_indicator: 1, reattach_required: 1} (UE doit se ré-authentifier)
  • Retourne 404 si l'abonné n'a jamais été enregistré ou si last_seen_mme est nul
  • Affecte tous les MSISDN associés à l'IMSI (même appareil physique/SIM)

Cas d'Utilisation :

  • Prévention de Fraude : Détacher immédiatement un abonné suspect
  • Résiliation de Souscription : Forcer la déconnexion lorsque le compte est désactivé
  • Dépannage : Effacer l'enregistrement MME obsolète pour le débogage
  • Migration : Forcer la ré-authentification pour appliquer de nouveaux paramètres de profil
  • Sécurité : Déconnecter immédiatement un abonné compromis

Considérations Multi-IMSI :

Lors de l'utilisation de CLR avec des scénarios multi-MSISDN :

  1. Plusieurs MSISDN, Un Seul IMSI :

    // L'abonné a l'IMSI 001001123456789 avec des MSISDNs ["+1234567890", "+9876543210"]
    POST /api/subscriber/cancel_location
    {"imsi": "001001123456789"}

    // Résultat : Un CLR envoyé, les deux MSISDNs affectés (même appareil)

  2. Différents IMSIs (Appareils Différents) :

    // Deux abonnés avec le même MSISDN mais différents IMSIs (scénario de portabilité de numéro)
    // Abonné A : IMSI 001001111111111, MSISDN "+1234567890"
    // Abonné B : IMSI 001001222222222, MSISDN "+1234567890"

    POST /api/subscriber/cancel_location
    {"imsi": "001001111111111"}

    // Résultat : Seul l'Abonné A est détaché, l'Abonné B n'est pas affecté

Remarques Importantes :

  • Basé sur l'IMSI : CLR est toujours envoyé par IMSI, pas par MSISDN
  • Asynchrone : CLR est envoyé de manière asynchrone ; la réponse de succès signifie que le CLR a été envoyé, pas que le MME l'a traité
  • Pas de validation du statut MME : CLR est envoyé même si le MME est injoignable (comportement standard de l'HSS)
  • Idempotent : Sûr d'appeler plusieurs fois pour le même IMSI

Documentation Connexe :

Gestion des MSISDN​

Les MSISDN (numéros de téléphone) peuvent être attribués aux abonnés pour activer les services vocaux. Voir Documentation Multi-MSISDN pour des détails sur l'attribution de plusieurs numéros à un seul abonné.

Lister les MSISDN​

Récupérer tous les numéros de téléphone.

Point de Terminaison : GET /api/msisdn

Exemple de Demande :

curl -k https://hss.example.com:8443/api/msisdn

Obtenir un MSISDN​

Récupérer un numéro de téléphone spécifique.

Point de Terminaison : GET /api/msisdn/:id

Exemple de Demande :

curl -k https://hss.example.com:8443/api/msisdn/1

Créer un MSISDN​

Créer un nouveau numéro de téléphone.

Point de Terminaison : POST /api/msisdn

Corps de la Demande :

{
  "msisdn": {
    "msisdn": "14155551234"
  }
}

Validation :

  • Doit être de 1 à 15 chiffres
  • Doit être unique
  • Doit suivre le format E.164 (format international sans signe +)

Exemple de Demande :

curl -k -X POST https://hss.example.com:8443/api/msisdn \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": {
      "msisdn": "14155551234"
    }
  }'

Assigner un MSISDN à un Abonné​

Pour attribuer un numéro de téléphone à un abonné, vous devez créer un enregistrement de jointure. Cela se fait généralement via le point de terminaison de mise à jour de l'abonné ou par manipulation directe de la base de données.

Modèle Multi-MSISDN :

Voir Fonctionnalités Multi-MSISDN et Multi-IMSI pour une utilisation détaillée.

Supprimer un MSISDN​

Retirer un numéro de téléphone.

Point de Terminaison : DELETE /api/msisdn/:id

Exemple de Demande :

curl -k -X DELETE https://hss.example.com:8443/api/msisdn/1

Gestion des SIM​

Les enregistrements de carte SIM stockent des informations physiques sur la carte SIM, y compris l'ICCID, les détails du fournisseur, les codes PIN/PUK et les clés OTA. Les enregistrements SIM peuvent être liés à des abonnés.

Voir Également :

Lister les SIM​

Récupérer toutes les cartes SIM.

Point de Terminaison : GET /api/sim

Exemple de Demande :

curl -k https://hss.example.com:8443/api/sim

Obtenir une SIM​

Récupérer une carte SIM spécifique.

Point de Terminaison : GET /api/sim/:id

Exemple de Demande :

curl -k https://hss.example.com:8443/api/sim/1

Créer une SIM​

Créer un nouvel enregistrement de carte SIM.

Point de Terminaison : POST /api/sim

Corps de la Demande :

{
  "sim": {
    "iccid": "8991101200003204510",
    "sim_vendor": "Gemalto",
    "batch_name": "2025-Q1-Batch-01",
    "is_esim": false,
    "pin1": "1234",
    "pin2": "5678",
    "puk1": "12345678",
    "puk2": "87654321",
    "adm1": "admin-code-1",
    "kic": "0123456789ABCDEF0123456789ABCDEF",
    "kid": "FEDCBA9876543210FEDCBA9876543210"
  }
}

Champs Requis :

  • iccid - 19-20 chiffres, unique

Champs Optionnels mais Importants :

  • sim_vendor - Nom du fabricant
  • batch_name - Pour le suivi
  • is_esim - Indicateur booléen pour eSIM
  • pin1, pin2 - Codes PIN de l'utilisateur final
  • puk1, puk2 - Codes de déverrouillage PIN
  • adm1-adm10 - Codes administratifs
  • kic, kid - Clés de sécurité OTA (chaîne hexadécimale)

Exemple de Demande :

curl -k -X POST https://hss.example.com:8443/api/sim \
  -H "Content-Type: application/json" \
  -d '{
    "sim": {
      "iccid": "8991101200003204510",
      "sim_vendor": "Gemalto"
    }
  }'

Mettre à Jour une SIM​

Modifier les données de la carte SIM.

Point de Terminaison : PUT /api/sim/:id

Exemple de Demande :

curl -k -X PUT https://hss.example.com:8443/api/sim/1 \
  -H "Content-Type: application/json" \
  -d '{
    "sim": {
      "batch_name": "Nom de Lot Mis à Jour"
    }
  }'

Supprimer une SIM​

Retirer un enregistrement de carte SIM.

Point de Terminaison : DELETE /api/sim/:id

Avertissement : Assurez-vous qu'aucun abonné ne référence cette SIM avant de la supprimer.

Gestion des Ensembles de Clés​

Les ensembles de clés contiennent le matériel cryptographique (Ki, OPC/OP, AMF, SQN) utilisé pour l'authentification des abonnés via l'algorithme Milenage. Chaque abonné doit référencer un ensemble de clés.

Voir Également :

  • Flux de Protocole - Procédures d'authentification utilisant des ensembles de clés

Lister les Ensembles de Clés​

Récupérer tous les ensembles de clés cryptographiques.

Point de Terminaison : GET /api/key_set

Exemple de Demande :

curl -k https://hss.example.com:8443/api/key_set

Obtenir un Ensemble de Clés​

Récupérer un ensemble de clés spécifique.

Point de Terminaison : GET /api/key_set/:id

Exemple de Demande :

curl -k https://hss.example.com:8443/api/key_set/1

Exemple de Réponse :

{
  "data": {
    "id": 1,
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "op": null,
    "amf": "8000",
    "sqn": 0,
    "authentication_algorithm": "milenage",
    "ota_counter": 0
  }
}

Créer un Ensemble de Clés​

Créer un nouvel ensemble de clés cryptographiques.

Point de Terminaison : POST /api/key_set

Corps de la Demande :

{
  "key_set": {
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "amf": "8000",
    "sqn": 0,
    "authentication_algorithm": "milenage"
  }
}

Champs Requis :

  • ki - Clé de 128 bits (32 caractères hexadécimaux)
  • Soit opc OU op (L'OPC peut être dérivé de l'OP)
  • authentication_algorithm - Actuellement uniquement "milenage"

Champs Optionnels :

  • amf - Par défaut : "8000"
  • sqn - Par défaut : 0
  • ota_counter - Par défaut : 0

Format des Clés :

  • Toutes les clés sont des chaînes hexadécimales
  • Ki, OPC, OP : 32 caractères hexadécimaux (128 bits)
  • AMF : 4 caractères hexadécimaux (16 bits)

Exemple de Demande :

curl -k -X POST https://hss.example.com:8443/api/key_set \
  -H "Content-Type: application/json" \
  -d '{
    "key_set": {
      "ki": "0123456789ABCDEF0123456789ABCDEF",
      "opc": "FEDCBA9876543210FEDCBA9876543210",
      "authentication_algorithm": "milenage"
    }
  }'

Avertissement de Sécurité : Les ensembles de clés contiennent des matériaux cryptographiques très sensibles. Protégez l'accès à l'API en conséquence.

Mettre à Jour un Ensemble de Clés​

Modifier un ensemble de clés existant.

Point de Terminaison : PUT /api/key_set/:id

Avertissement : Changer les clés pour un abonné actif entraînera des échecs d'authentification. Ne mettez à jour les clés que pendant les fenêtres de maintenance ou pour de nouveaux abonnés.

Impact : Les mises à jour affectent immédiatement tous les abonnés utilisant cet ensemble de clés. Les abonnés actifs échoueront à l'authentification lors de la prochaine tentative de connexion.

Supprimer un Ensemble de Clés​

Retirer un ensemble de clés.

Point de Terminaison : DELETE /api/key_set/:id

Avertissement : Assurez-vous qu'aucuns abonnés ne référencent cet ensemble de clés avant de le supprimer. Interrogez d'abord les abonnés pour vérifier les références.

Gestion des Profils​

Profils EPC​

Les profils EPC (Evolved Packet Core) définissent les paramètres de service de données pour les abonnés. Ces profils sont référencés lors de la création des abonnés.

Lister les Profils EPC​

Point de Terminaison : GET /api/epc/profile

Obtenir un Profil EPC​

Point de Terminaison : GET /api/epc/profile/:id

Créer un Profil EPC​

Point de Terminaison : POST /api/epc/profile

Corps de la Demande :

{
  "apn_profiles": [],
  "name": "Plan de Données Standard",
  "network_access_mode": "packet_only",
  "tracking_area_update_interval_seconds": 600,
  "ue_ambr_dl_kbps": 100000,
  "ue_ambr_ul_kbps": 50000
}

Champs :

ChampDescriptionUnitésValeurs Typiques
nameNom du profilTexteIdentifiant unique
ue_ambr_dl_kbpsLimite de bande passante de téléchargementKbps10000-1000000
ue_ambr_ul_kbpsLimite de bande passante de téléchargementKbps5000-500000
network_access_modeType d'accèsChaîne"packet_only" ou "packet_and_circuit"
tracking_area_update_interval_secondsMinuteur TAUSecondes600 (typique)
apn_profilesListe d'IDs de profils APNTableau[] ou [1, 2, 3]

Exemple de Demande :

curl -k -X POST https://hss.example.com:8443/api/epc/profile \
  -H "Content-Type: application/json" \
  -d '{
    "apn_profiles": [],
    "name": "Premium 100Mbps",
    "network_access_mode": "packet_only",
    "tracking_area_update_interval_seconds": 600,
    "ue_ambr_dl_kbps": 100000,
    "ue_ambr_ul_kbps": 50000
  }'

Voir Également :

Mettre à Jour un Profil EPC​

Point de Terminaison : PUT /api/epc/profile/:id

Remarque : Les modifications des profils EPC affectent tous les abonnés utilisant ce profil. Les sessions actives peuvent devoir être rétablies.

Supprimer un Profil EPC​

Point de Terminaison : DELETE /api/epc/profile/:id

Avertissement : Assurez-vous qu'aucun abonné ne référence ce profil avant de le supprimer.

Profils IMS​

Les profils IMS (IP Multimedia Subsystem) définissent les paramètres de service vocal et les Critères de Filtrage Initiaux (IFC) pour les abonnés. Ces profils sont référencés lors de la création des abonnés avec les services IMS activés.

Lister les Profils IMS​

Point de Terminaison : GET /api/ims/profile

Créer un Profil IMS​

Point de Terminaison : POST /api/ims/profile

Corps de la Demande :

{
  "name": "Standard VoLTE",
  "ifc_template": "<IMS-XML-Template-Here>"
}

Champs Requis :

  • name - Nom du profil (doit être unique)
  • ifc_template - Modèle XML IFC (Critères de Filtrage Initiaux) avec des variables de modèle Liquid

Variables du Modèle IFC :

Le modèle IFC prend en charge les variables de modèle Liquid suivantes qui sont substituées dynamiquement :

VariableDescriptionValeur Exemple
{{ imsi }}IMSI de l'abonné001001123456789
{{ msisdns }}Tableau de MSISDNs (pour boucles)["14155551234", "14155555678"]
{{ mcc }}Code de Pays Mobile001
{{ mnc }}Code de Réseau Mobile001

Comment Fonctionne le Rendu du Modèle :

Le modèle IFC est stocké comme un modèle Liquid (similaire à Jinja2) et est rendu dynamiquement lors des opérations IMS :

  1. Stockage : Lorsque vous créez un profil IMS, le modèle est stocké tel quel avec des variables comme {{ imsi }} et {% for msisdn in msisdns %}
  2. Validation : L'API valide le modèle en le rendant avec des données de test pour garantir une syntaxe XML valide
  3. Rendu à l'Exécution : Lorsqu'un abonné effectue une inscription IMS (MAA/SAA), l'HSS :
    • Récupère le profil IMS de l'abonné
    • Rendu le modèle avec les données réelles de l'abonné :
      • {{ imsi }} → IMSI de l'abonné
      • {{ msisdns }} → numéros de téléphone de l'abonné
      • {{ mcc }} → Code de Pays Mobile configuré
      • {{ mnc }} → Code de Réseau Mobile configuré
    • Retourne le XML rendu au S-CSCF via Cx/Diameter

Syntaxe du Modèle :

<!-- Substitution simple de variable -->
{{ imsi }}

<!-- Pour les boucles sur des tableaux -->
{% for msisdn in msisdns %}
  <MSISDN>{{ msisdn }}</MSISDN>
{% endfor %}

<!-- Combinaison de variables -->
{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org

Exemple de Modèle IFC :

<?xml version="1.0" encoding="UTF-8"?>
<IMSSubscription>
<PrivateID>{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</PrivateID>
<ServiceProfile>
{% for msisdn in msisdns %}
<PublicIdentity>
<Identity>sip:{{ msisdn }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</Identity>
<Extension>
<IdentityType>0</IdentityType>
</Extension>
</PublicIdentity>
<PublicIdentity>
<Identity>tel:{{ msisdn }}</Identity>
<Extension>
<IdentityType>0</IdentityType>
</Extension>
</PublicIdentity>
{% endfor %}
<InitialFilterCriteria>
<Priority>10</Priority>
<TriggerPoint>
<ConditionTypeCNF>0</ConditionTypeCNF>
<SPT>
<ConditionNegated>0</ConditionNegated>
<Group>0</Group>
<Method>REGISTER</Method>
</SPT>
</TriggerPoint>
<ApplicationServer>
<ServerName>sip:as.ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
</InitialFilterCriteria>
</ServiceProfile>
</IMSSubscription>

Exemple de Demande (curl) :

curl -k -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default",
    "ifc_template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><IMSSubscription><ServiceProfile>...</ServiceProfile></IMSSubscription>"
  }'

Exemple de Demande (Python) :

import requests

response = requests.post(
    "https://hss.example.com:8443/api/ims/profile",
    json={
        "name": "default",
        "ifc_template": ifc_template_string
    },
    verify=False  # Pour les certificats auto-signés
)

Réponse de Succès (201 Créé) :

{
  "status": "success",
  "response": {
    "id": 1,
    "name": "default",
    "ifc_template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
  }
}

Validation :

  • L'API valide que le modèle IFC est un XML valide
  • Les variables du modèle sont rendues avec des données de test pour vérifier la syntaxe
  • Le champ name doit être unique et non vide

Voir Également :

Profils APN​

Les profils APN (Access Point Name) se composent de trois composants qui fonctionnent ensemble :

  1. Identifiant APN - Définit le nom de l'APN et la version IP
  2. Profil QoS APN - Définit les paramètres de Qualité de Service
  3. Profil APN - Combine l'identifiant et le QoS, lié aux Profils EPC

Voir Documentation PCRF pour la configuration détaillée des politiques, la gestion du QoS et la ré-authentification automatique. Voir également Documentation des Profils pour des exemples de configuration APN.

Lister les Identifiants APN​

Point de Terminaison : GET /api/apn/identifier

Créer un Identifiant APN​

Point de Terminaison : POST /api/apn/identifier

Corps de la Demande :

{
  "apn": "internet",
  "ip_version": "ipv4v6"
}

Valeurs de Version IP :

  • "ipv4" - IPv4 uniquement
  • "ipv6" - IPv6 uniquement
  • "ipv4v6" - IPv4v6 (double pile)
  • "ipv4_or_ipv6" - IPv4 ou IPv6 (choix du réseau)

Lister les Profils QoS APN​

Point de Terminaison : GET /api/apn/qos_profile

Créer un Profil QoS APN​

Point de Terminaison : POST /api/apn/qos_profile

Corps de la Demande :

{
  "name": "Internet Meilleur Effort",
  "allocation_retention_priority": 8,
  "apn_ambr_dl_kbps": 50000,
  "apn_ambr_ul_kbps": 25000,
  "pre_emption_capability": false,
  "pre_emption_vulnerability": true,
  "qci": 9
}

Lister les Profils APN​

Point de Terminaison : GET /api/apn/profile

Créer un Profil APN​

Point de Terminaison : POST /api/apn/profile

Corps de la Demande :

{
  "apn_identifier_id": 1,
  "apn_qos_profile_id": 1,
  "name": "APN Internet"
}

Champs Requis :

Voir Également :

Gestion des IP Statique​

Les adresses IP statiques peuvent être attribuées à des APNs spécifiques pour des abonnés individuels. Cela permet aux abonnés de recevoir une adresse IPv4 et/ou IPv6 prédéterminée lors de la connexion à un APN particulier, plutôt que de recevoir une adresse dynamique d'un pool DHCP.

Architecture :

Flux de Données Lors de la Connexion de l'Abonné :

Réponse de Mise à Jour de Localisation - Mappage des Données de Configuration APN :

Ce diagramme montre exactement d'où provient chaque champ dans l'AVP de Configuration APN de la Réponse de Mise à Jour de Localisation S6a dans la base de données :

Observations Clés :

  1. Identifiant de Contexte : Index séquentiel (0, 1, 2...) pour chaque APN dans le profil
  2. Sélection de Service : Vient directement de apn_identifier.apn (par exemple, "internet", "ims")
  3. Type de PDN : Encodé à partir de apn_identifier.ip_version (ipv4=0, ipv6=1, ipv4v6=2, ipv4_or_ipv6=3)
  4. Paramètres QoS : Tous provenant de la table apn_qos_profile
  5. Bande Passante AMBR : Les valeurs sont multipliées par 1000 (conversion kbps → bps)
  6. Adresse IP de Partie Servie : Inclus uniquement si une IP statique existe pour cette combinaison abonné+APN
    • Processus de recherche : subscriber.static_ips → filtrer par apn_profile_id → extraire les IPs
    • La compatibilité de la version IP est vérifiée par rapport à apn_identifier.ip_version
  7. VPLMN-Dynamic-Address-Allowed : Codé en dur à 0 (non autorisé) - force l'utilisation d'une IP statique si fournie

Hiérarchie des Relations :

Concepts Clés :

  • Attribution par APN : Chaque IP Statique est liée à un Profil APN spécifique
  • Une IP par APN par Abonné : Un abonné ne peut avoir qu'une seule attribution d'IP statique par APN
  • Support IPv4 et IPv6 : Les IP statiques peuvent être uniquement IPv4, uniquement IPv6 ou double pile
  • Unicité Globale des IP : Chaque adresse IP doit être globalement unique à travers tous les enregistrements d'IP statiques dans le système
    • La même adresse IPv4 ou IPv6 ne peut pas être attribuée à plusieurs abonnés (même sur différents APNs)
    • Cela empêche les conflits de routage et l'ambiguïté des adresses IP
    • Imposé par des index uniques dans la base de données sur les champs ipv4_static_ip et ipv6_static_ip
  • Relation Plusieurs-à-Plusieurs : Les abonnés et les IP statiques sont liés via une table de jointure

Cas d'Utilisation :

  • Adresses IP fixes pour des dispositifs IoT
  • Hébergement de serveurs sur des dispositifs mobiles (nécessite une IP statique pour les connexions entrantes)
  • Applications héritées nécessitant des adresses IP spécifiques
  • Routage de politiques réseau basé sur l'IP source
  • Conformité réglementaire nécessitant le suivi des adresses IP

Lister les IP Statiques​

Récupérer toutes les affectations d'IP statiques.

Point de Terminaison : GET /api/epc/static_ip

Exemple de Demande :

curl -k https://hss.example.com:8443/api/epc/static_ip

Exemple de Réponse :

{
  "data": [
    {
      "id": 1,
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111",
      "apn_profile": {
        "id": 5,
        "name": "APN Internet",
        "apn_identifier": {
          "apn": "internet",
          "ip_version": "ipv4v6"
        }
      },
      "inserted_at": "2025-11-15T10:30:00Z",
      "updated_at": "2025-11-15T10:30:00Z"
    }
  ]
}

Obtenir une IP Statique​

Récupérer une affectation d'IP statique spécifique.

Point de Terminaison : GET /api/epc/static_ip/:id

Paramètres de Chemin :

ParamètreTypeDescription
idintegerID de base de données de l'IP statique

Exemple de Demande :

curl -k https://hss.example.com:8443/api/epc/static_ip/1

Créer une IP Statique​

Créer une nouvelle affectation d'IP statique pour un APN.

Point de Terminaison : POST /api/epc/static_ip

Corps de la Demande :

{
  "static_ip": {
    "apn_profile_id": 5,
    "ipv4_static_ip": "100.64.1.1",
    "ipv6_static_ip": "2606:4700:4700::1111"
  }
}

Champs Requis :

  • apn_profile_id - Doit référencer un Profil APN existant
  • Au moins une des ipv4_static_ip OU ipv6_static_ip doit être spécifiée

Champs Optionnels :

  • ipv4_static_ip - Adresse IPv4 (notation décimale pointée)
  • ipv6_static_ip - Adresse IPv6 (notation standard)

Validation du Format IP :

  • IPv4 : Format standard décimal pointé (par exemple, 100.64.1.1)
  • IPv6 : Format standard hexadécimal séparé par des deux-points (par exemple, 2606:4700:4700::1111)
  • Les adresses IPv4 et IPv6 doivent être globalement uniques à travers tous les enregistrements d'IP statiques
    • Cela empêche les conflits d'adresses IP dans le réseau
    • La même IP ne peut pas être attribuée à plusieurs abonnés, même sur différents APNs
    • C'est une contrainte au niveau de la base de données imposée par des index uniques

Options de Configuration :

ConfigurationIPv4IPv6Exemple
Uniquement IPv4✓-{"ipv4_static_ip": "100.64.1.1"}
Uniquement IPv6-✓{"ipv6_static_ip": "2606:4700:4700::1111"}
Double Pile✓✓Les deux champs spécifiés

Exemples de Demandes :

IP Statique uniquement IPv4 :

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1"
    }
  }'

IP Statique uniquement IPv6 :

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 6,
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }'

IP Statique en Double Pile :

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }'

Réponse de Succès (201 Créé) :

{
  "data": {
    "id": 1,
    "apn_profile_id": 5,
    "ipv4_static_ip": "100.64.1.1",
    "ipv6_static_ip": "2606:4700:4700::1111",
    "inserted_at": "2025-11-15T10:30:00Z",
    "updated_at": "2025-11-15T10:30:00Z"
  }
}

Voir Également :

Mettre à Jour une IP Statique​

Modifier une affectation d'IP statique existante.

Point de Terminaison : PUT /api/epc/static_ip/:id

Paramètres de Chemin :

ParamètreTypeDescription
idintegerID de base de données de l'IP statique

Corps de la Demande :

{
  "static_ip": {
    "ipv4_static_ip": "100.64.1.2",
    "ipv6_static_ip": "2606:4700:4700::1112"
  }
}

Champs Modifiables :

  • ipv4_static_ip - Changer l'adresse IPv4
  • ipv6_static_ip - Changer l'adresse IPv6
  • apn_profile_id - Changer l'attribution APN

Non Modifiable :

  • id - Clé primaire (lecture seule)

Avertissement : Changer l'adresse IP pour un abonné actif affectera sa prochaine connexion PDN. Les sessions PDN actives continueront d'utiliser l'ancienne IP jusqu'à ce qu'elles se déconnectent et se reconnectent.

Exemple de Demande :

curl -k -X PUT https://hss.example.com:8443/api/epc/static_ip/1 \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "ipv4_static_ip": "100.64.1.2"
    }
  }'

Supprimer une IP Statique​

Retirer une affectation d'IP statique.

Point de Terminaison : DELETE /api/epc/static_ip/:id

Paramètres de Chemin :

ParamètreTypeDescription
idintegerID de base de données de l'IP statique

Exemple de Demande :

curl -k -X DELETE https://hss.example.com:8443/api/epc/static_ip/1

Comportement :

  • Supprime l'affectation d'IP statique
  • N'affecte PAS le Profil APN (l'APN reste disponible pour d'autres abonnés)
  • Les abonnés utilisant cette IP statique recevront des IP dynamiques lors de la prochaine connexion
  • L'adresse IP devient disponible pour réutilisation après suppression

Avertissement : Si un abonné utilise activement cette IP statique, la supprimer entraînera la réception d'une IP dynamique lors de sa prochaine connexion PDN. Assurez-vous que les abonnés sont hors ligne ou envoyez une Demande d'Annulation de Localisation avant de supprimer.

Attribuer une IP Statique à un Abonné​

Pour attribuer une IP statique à un abonné, vous devez associer l'enregistrement IP Statique avec l'Abonné lors de la création ou de la mise à jour.

Modèle d'Attribution :

  1. Créer l'IP Statique (voir Créer une IP Statique)
  2. Attribuer à l'Abonné en utilisant le champ static_ips

Créer un Abonné avec une IP Statique :

# Étape 1 : Créer une IP statique pour l'APN "internet"
STATIC_IP_ID=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }' | jq -r '.data.id')

# Étape 2 : Créer un abonné avec l'IP statique attribuée
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriber\": {
      \"imsi\": \"001001123456789\",
      \"key_set_id\": 1,
      \"epc_profile_id\": 1,
      \"static_ips\": [$STATIC_IP_ID]
    }
  }"

Mettre à Jour un Abonné Existant avec une IP Statique :

curl -k -X PUT https://hss.example.com:8443/api/subscriber/1 \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "static_ips": [1, 2]
    }
  }'

Plusieurs IP Statiques (Différents APNs) :

Un abonné peut avoir plusieurs IP statiques tant que chacune est pour un APN différent :

# Créer une IP statique pour l'APN "internet"
INTERNET_IP=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1"
    }
  }' | jq -r '.data.id')

# Créer une IP statique pour l'APN "ims"
IMS_IP=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 6,
      "ipv4_static_ip": "100.64.2.1"
    }
  }' | jq -r '.data.id')

# Attribuer les deux à l'abonné
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriber\": {
      \"imsi\": \"001001123456789\",
      \"key_set_id\": 1,
      \"epc_profile_id\": 1,
      \"static_ips\": [$INTERNET_IP, $IMS_IP]
    }
  }"

Règles de Validation :

  • ✓ Autorisé : Plusieurs IP statiques pour différents APNs
  • ✗ Rejeté : Plusieurs IP statiques pour le même APN

Exemple d'Erreur - APN Dupliqué :

# Cela échouera si les deux IP statiques référencent le même APN
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "imsi": "001001123456789",
      "static_ips": [1, 2]
    }
  }'

# Réponse d'Erreur :
{
  "errors": {
    "static_ips": [
      "les IP statiques par apn par abonné doivent être uniques. par exemple, un abonné ne peut pas se voir attribuer l'IP statique 100.64.1.1 pour internet et également 100.64.1.2 pour internet"
    ]
  }
}

Voir Également :

Gestion du Roaming​

Les profils de roaming contrôlent si les abonnés peuvent accéder aux services de données et IMS sur les réseaux visités. Les profils sont attribués aux abonnés et se composent de règles correspondant à MCC/MNC.

Lister les Profils de Roaming​

Point de Terminaison : GET /api/roaming/profile

Créer un Profil de Roaming​

Point de Terminaison : POST /api/roaming/profile

Corps de la Demande :

{
  "roaming_profile": {
    "name": "Uniquement les Opérateurs Américains",
    "data_action_if_no_rules_match": "deny",
    "ims_action_if_no_rules_match": "deny",
    "roaming_rules": []
  }
}

Valeurs d'Action :

  • "allow" - Autoriser
  • "deny" - Refuser

Actions par Défaut :

  • data_action_if_no_rules_match - Action lorsque aucune règle de roaming ne correspond
  • ims_action_if_no_rules_match - Action par défaut spécifique à l'IMS

Lister les Règles de Roaming​

Point de Terminaison : GET /api/roaming/rule

Créer une Règle de Roaming​

Point de Terminaison : POST /api/roaming/rule

Corps de la Demande :

{
  "roaming_rule": {
    "name": "Autoriser AT&T",
    "mcc": "310",
    "mnc": "410",
    "data_action": "allow",
    "ims_action": "allow"
  }
}

Champs :

  • mcc - Code de Pays Mobile (3 chiffres)
  • mnc - Code de Réseau Mobile (2-3 chiffres)
  • data_action - "allow" ou "deny" pour les services de données
  • ims_action - "allow" ou "deny" pour les services IMS/voix

Voir Également :

Gestion de l'EIR​

OmniHSS fonctionne comme un Registre d'Identité de Matériel (EIR) via l'interface Diameter S13. Les règles EIR contrôlent l'accès des dispositifs en fonction des modèles IMEI.

Voir Documentation EIR pour des vérifications détaillées de l'identité des équipements, des flux d'interface S13 et de validation des IMEI.

Lister les Règles EIR​

Point de Terminaison : GET /api/eir/rule

Créer une Règle EIR​

Point de Terminaison : POST /api/eir/rule

Corps de la Demande :

{
  "eir_rule": {
    "name": "Bloquer iPhone 6",
    "imei_regex": "^35[0-9]{6}0[0-9]{7}$",
    "action": 1
  }
}

Champs :

  • name - Nom descriptif pour la règle
  • imei_regex - Expression régulière pour correspondre aux numéros IMEI
  • action - Liste blanche (0), Liste noire (1