[[:identifier_les_etapes_en_echec|Français]] | [[:en:identifier_les_etapes_en_echec|English]]
----
====== 📄 How to Identify Failed Steps in an ID360 JSON Report ======

When an ID360 verification returns a **KO** ❌ status, it is possible to analyze the cause by checking the structure of the JSON file 📂.  
Here are the paths to follow to find the relevant information 🔍.

⚠️ **Important:** You must review **all the steps described in this guide** 🗂️, even if certain **keys** or **sections** of the JSON file are not present **at the current moment** in your workflow.\\
Each JSON key corresponds to a **specific configuration of the workflow** 🛠️.\\
\\
🔄 If your process configuration changes (adding ➕, removing ➖, or modifying ✏️ steps or checks), the list of possible errors will also change.\\
**Therefore, the absence of a key in today’s JSON does not guarantee it will be absent tomorrow.**\\
\\
✅ For this reason, it is essential to review **all the steps mentioned in this guide** in order to anticipate and properly handle future changes 🚀.

===== 1. 📌 Major Errors: ''all_status_codes'' =====

**JSON Path**: ''all_status_codes''

This array contains the major errors detected during verification.

Each status_code element contains:
  * ''code'': the error code (e.g., VLD_VALIDATION_KO, exhaustive list [[https://id360docaposte.com/fr/documentation/status-codes|here]]))
  * ''message'': a description of the failed validations

**Example**:
<code json>
{
  "all_status_codes": [{
     "status_code": {
        "code": "VLD_VALIDATION_KO",
        "message": "1 validations failed: . Max allowed: 0"
        },
        "where": "ID360"
      },{
     "status_code": {
        "code": "MDL_INPUT_INVALID",
        "message": "No MRZ could be read on the uploaded image(s)"
       },
       "where": "id_document"
      },{
      "status_code": {
        "code": "VLD_ID_INVALID",
        "message": "Id from id_document_result is ignored because the format is not recognized"
        },
        "where": "validation"
      }]
}
</code>

**🎯 Purpose**: Identification of major errors.

⚠️ As part of the use of an Electronic Identification Means (such as Identité Numérique La Poste, FranceConnect+ or PVID), when the identification result is KO, the returned code is EIM_RESPONSE_KO.

===== 2. 📄 Validation Details: ''validations'' =====

**JSON Path**: ''finalizer_reports > validator_report > validations''

Each validation represents a business rule applied to a data field.

Check for:
  * ''is_valid: false'' → indicates a failed validation  
  * ''ref'': rule identifier (e.g., ''IDENTITY.FIRST_NAME.first_name'')  
  * ''fields'': affected data

**Example**:
<code json>
{
  "ref": "IDENTITY.FIRST_NAME.first_name",
  "is_valid": false,
  "fields": [...]
}
</code>

**🎯 Use Case**: Identify which user data failed the controls.

⚠️ **Note**: For last name comparisons, two checks are performed: one on the **preferred name**, the other on the **birth name**.  
Therefore, you may see the field "ref": "IDENTITY.NAME.name" appear twice.  
If either check is successful, the name comparison should be considered **passed**.

-----

===== 3. 🆚 Cross-Source Comparisons: ''comparisons'' =====

**JSON Path**: ''finalizer_reports > validator_report > comparisons''

These blocks compare values from multiple sources (e.g., user input vs. documents, or between documents).

Check for:
  * ''is_equivalent: false'' → comparison failed  
  * ''ref'': rule identifier  
  * ''field1'' and ''field2'': the values being compared

**Example**:
<code json>
{
  "ref": "KBIS.SIREN.siren",
  "is_equivalent": false,
  "field1": {...},
  "field2": {...}
}
</code>

**🎯 Use Case**: Detect inconsistencies between documents or between documents and user input.

-----

===== 4. ⚙️ Custom Rules: ''customs'' =====

**JSON Path**: ''finalizer_reports > validator_report > customs''

These checks are client-specific or related to particular document types.

Check for:
  * ''is_valid: false'' → custom rule failed  
  * ''ref'': rule name  
  * ''fields'': data fields being evaluated

**Example**:
<code json>
{
  "ref": "IDENTITY_DOCUMENT.document_number",
  "is_valid": false,
  "fields": [...]
}
</code>

**🎯 Use Case**: Understand failures on custom rules defined for a specific client.

-----

===== 5. 🔢 Step-Level Analysis: ''steps'' =====

**JSON Path**: ''steps''

The ''steps'' block contains the various steps of the process.  
For each step, you should:

  * Read the ''status'' field  
  * If the value is ''KO'', review the ''status_codes'' list within that step to understand the causes

**Example**:
<code json>
"steps": {
  "id_document": {
    "status": "KO",
    "status_codes": [
      {
        "code": "MDL_INPUT_INVALID",
        "message": "No MRZ could be read on the uploaded image(s)"
      }
    ]
  }
}
</code>

**🎯 Use Case**: Helps isolate which steps failed and provides contextual details on the encountered issues.

-----

===== ✅ Summary =====

^ Element          ^ JSON Path                                                  ^ Check Criteria                                                  ^                         
| All Status Code  | ''all_status_code''         | at least one ''status_code'' exists|
| Validations      | ''finalizer_reports > validator_report > validations''     | ''is_valid: false''|
| Comparisons      | ''finalizer_reports > validator_report > comparisons''     | ''is_equivalent: false''|
| Customs          | ''finalizer_reports > validator_report > customs''         | ''is_valid: false''   |                                     
| Steps            | ''steps > [step_name] > status'' + ''status_codes''        | If ''status: KO'', review associated ''status_codes'' entries    | 

\\
For example, to check that an identity document is not expired, you should look for the ''IDENTITY_DOCUMENT.expired'' reference across the different blocks and then verify the value of the ''is_valid'' field (true or false).
The references remain stable and are not expected to change.