Guide de migration - API Portabilité

Vue d'ensemble

L'ancienne API de portabilité basée sur le système d'éligibilité (/api/v1/portability/eligibility) est dépréciée et inactive depuis la migration vers notre nouveau système de portabilité. Ce guide vous accompagne dans la migration vers la nouvelle API basée sur le système des Cart et Order.

• Vérifier que vous avez un préfixe de portabilité hébergé
• Récupérer les service_id de vos préfixes via /service
• Adapter votre code pour le flux Cart → Order (4 étapes)
• Mettre à jour la structure des données client
• Si vous utilisez la fiabilisation, implémenter le nouveau processus /reliability-check
• Adapter le format rio_or_did pour RIO et DID
• Renommer les options (call_validation → option_call_validation)
• Tester le nouveau flux avec wanted_date

Comparaison des processus de commande

Ancienne API

Le processus était centré avant sur le concept d'éligibilités:

1. Réalisation d'une éligibilité POST /api/v1/portability/eligibility
2. Commande POST /eligibility/create_order

Nouvelle API

Le processus utilise maintenant un concept plus flexible de Cart (un panier de commande) et Order (la commande réalisée).

1. Récupération du préfixe de portabilité GET /service
2. Création d'un panier de commande avec une entrée POST /cart
3. Récupérer l'identifiant de l'entrée GET /cart/{id}/lines
4. Effecter la commande POST /orders

Changements majeurs

1. Processus de commande

Ancienne API

POST /api/v1/portability/eligibility
{
  "did": ["0100020001", "0100020002"],
  "idn": "0100020000",
  "call_validation": true,
  "reliability": false,
  "customer": { ... }
}

→ eligibility_id

POST /eligibility/create_order
{
  "eligibility-id": "3715E50C-...",
  "customer": { ... }
}

Nouvelle API

1. GET /service?product_category[]=prefix_hosting
   → Récupérer prefix_service_id

2. POST /cart
{
  "lines": [{
    "entity": {
      "portability": {
        "idn": "0123456789",
        "wanted_date": "2024-12-01T10:00:00.000Z",
        "rio_or_did": {
          "did": ["0234567890", "0234567891"]
        },
        "portability_type": "total",
        "option_call_validation": false
      }
    }
  }],
  "context": "buyer"
}
   → cart_id

3. GET /cart/{{cart_id}}/lines
   → cart_line_id

4. POST /orders
{
  "cart_id": "{{cart_id}}",
  "lines": [{
    "cart_line_id": "{{cart_line_id}}",
    "attributes": {
      "portability": {
        "routing": "routing_on_prefix",
        "prefix_service_id": "{{prefix_service_id}}"
      }
    },
    "customer": { ... }
  }]
}

2. Fiabilisation

Avant (ancienne API)

La fiabilisation était incluse dans la requête d'éligibilité via le paramètre reliability: true.

Après (nouvelle API)

Processus complètement séparé :

POST /portability/reliability-check
{
  "idn": "0123456789",
  "operator_code": "XXXX00"
}
→ reliability_check_id

GET /portability/reliability-check/{reliability_check_id}
→ État: COMPLETED (avec did) ou REJECTED

Important : La fiabilisation n'a de sens que pour les groupements de numéros (pas pour les numéros isolés avec RIO).

3. Structure des données client

Avant

{
  "customer": {
    "name": "Netwo SAS",
    "company_number": "84412522900014",
    "address": {
      "address": "35 rue des Jeuneurs",
      "zip_code": "75002",
      "city": "PARIS",
      "country": "France"
    },
    "contact": {
      "name": "Jean-Michel",
      "email": "[email protected]",
      "phone": "0102030405"
    }
  }
}

Après

{
  "customer": {
    "name": "Societé",
    "company_number": "00000000000000",
    "customer_location": {
      "address": {
        "street_number": "35",
        "street": "Rue des Jeuneurs",
        "zip_code": "75002",
        "city": "Paris"
      }
    }
  },
  "contact": {
    "name": "societe",
    "email": "[email protected]",
    "phone": "+33601020304"
  }
}

Changements :

• address → customer_location.address
• address.address séparé en street_number et street
• contact n'est plus dans customer mais au même niveau dans lines

4. Nouveaux concepts obligatoires

Préfixe de portabilité

Vous devez désormais avoir un préfixe de portabilité hébergé et récupérer son service_id avant de passer commande.

GET /service?product_category[]=prefix_hosting

Routage

Le routage doit être spécifié dans les attributs de la commande :

• Sur préfixe : "routing": "routing_on_prefix"
• Sur SIP Trunk C5 :

"routing": {
  "sip_trunk_c5": {
    "service_id": "{{sip_trunk_service_id}}"
  }
}

5. RIO vs DID

Avant

{
  "rio": "XXXXXXXXXX",
  "idn": "0179919856"
}

Après

{
  "idn": "0123456789",
  "rio_or_did": {
    "did": ["0234567890", "0234567891"]
  }
}

ou

{
  "idn": "0123456789",
  "rio_or_did": {
    "rio": "XXXXXXXXXX"
  }
}

6. Options

7. Suivi technique APNF

Nouveau dans l'API actuelle, vous pouvez obtenir des informations techniques détaillées :

GET /portability/order-line/{order_line_id}

Retourne les requêtes APNF avec états (Planned, ArOk, etc.), références opérateurs, et dates planifiées.