> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Estats de verificació: cicle de vida de la sessió i codis

> Estats de sessió de Didit: aprovada, rebutjada, en revisió, caducada, reenviada, abandonada i KYC caducat. Gestiona decisions i webhooks.

Cada sessió de verificació passa per una sèrie d'estats. Entendre'ls t'ajuda a supervisar el progrés de l'usuari, automatitzar les decisions de compliment i optimitzar la conversió.

Aquest enum és l'única font de veritat per a les cadenes que retornen `GET /v3/session/<id>/decision/` i cada webhook de Didit.

***

## Tots els valors d'estat

> [!NOTE]
>
> Cada estat és una **cadena exacta** que retornen l'API i els webhooks de Didit. Utilitza sempre la comparació estricta de cadenes al codi (per exemple, `=== "In Review"`): aquests valors distingeixen majúscules i minúscules i inclouen espais. El valor `Kyc Expired` també fa servir una única `K` majúscula (no `KYC`).

| Estat | Valor de cadena | Descripció |
| - | - | - |
| No iniciada | `"Not Started"` | Sessió creada, l'usuari encara no ha obert l'enllaç |
| En progrés | `"In Progress"` | L'usuari està completant activament la verificació |
| Aprovada | `"Approved"` | Totes les comprovacions s'han superat: identitat verificada |
| Rebutjada | `"Declined"` | Una o més comprovacions han fallat |
| En revisió | `"In Review"` | Marcada per a revisió manual de compliment |
| Esperant l'usuari | `"Awaiting User"` | Esperant que una o més parts completin la seva verificació (KYB) |
| Reenviada | `"Resubmitted"` | S'ha demanat a l'usuari que repeteixi passos específics |
| Caducada | `"Expired"` | La sessió ha caducat abans que l'usuari obrís l'enllaç |
| Abandonada | `"Abandoned"` | L'usuari ha començat però no ha acabat a temps |
| KYC caducat | `"Kyc Expired"` | Sessió aprovada anteriorment, el document verificat de la qual ha superat la data de caducitat |

***

## Estats de les sessions

> [accordion] No iniciada - "Not Started"
>
> **Valor de l'API:** `"Not Started"`
>
> La sessió s'ha creat mitjançant l'API, però l'usuari **encara no ha obert l'enllaç de verificació**.
>
> * **Què cal fer:** Esperar que l'usuari comenci o enviar-li un recordatori si passa massa temps.
> * **Transicions a:** `"In Progress"`, `"Expired"`

> [accordion] En curs - "In Progress"
>
> **Valor de l'API:** `"In Progress"`
>
> L'usuari ha obert l'enllaç i està **completant activament els passos de verificació** (captura del document, prova de vida, etc.).
>
> * **Què cal fer:** No cal fer res, perquè l'usuari està seguint el flux.
> * **Transicions a:** `"Approved"`, `"Declined"`, `"In Review"`, `"Abandoned"`

> [accordion] Aprovada - "Approved"
>
> **Valor de l'API:** `"Approved"`
>
> Totes les comprovacions de verificació **s'han superat correctament**. La identitat de l'usuari s'ha verificat.
>
> * **Què cal fer:** Concedir l'accés a l'usuari, actualitzar-ne el perfil i emmagatzemar les dades de la decisió.
> * **El webhook inclou:** L'objecte `decision` complet amb tots els resultats de les funcionalitats.
> * **Transicions a:** `"Kyc Expired"` (quan passa la data de caducitat del document verificat, que és el comportament per defecte tret que el **Expiration mode** sigui **Allow expired** per a aquell país i tipus de document). Un revisor o l'endpoint d'actualització d'estat també la pot posar a `"Declined"` o `"Resubmitted"`.

> [accordion] Rebutjada - "Declined"
>
> **Valor de l'API:** `"Declined"`
>
> Una o més comprovacions **han fallat**. L'usuari no ha superat la verificació.
>
> * **Què cal fer:** Notificar l'usuari. Opcionalment, sol·licitar que es tornin a presentar els passos si el problema es pot resoldre.
> * **El webhook inclou:** L'objecte `decision` complet amb les advertències que expliquen el motiu del fracàs.
> * **Transicions a:** `"Resubmitted"` (si un revisor ho sol·licita). Un revisor o l'endpoint d'actualització d'estat també la pot posar a `"Approved"`.

> [accordion] En revisió - "In Review"
>
> **Valor de l'API:** `"In Review"`
>
> Les comprovacions automàtiques han marcat **advertències que necessiten revisió humana**. Un responsable de compliment ha de prendre la decisió final.
>
> * **Què cal fer:** Un revisor ha d'obrir la sessió a la Console i aprovar-la, rebutjar-la o sol·licitar que es tornin a presentar els passos.
> * **El webhook inclou:** L'objecte `decision` complet amb les advertències.
> * **Transicions a:** `"Approved"`, `"Declined"`, `"Resubmitted"`

> [accordion] Esperant l’usuari - "Awaiting User"
>
> **Valor de l'API:** `"Awaiting User"`
>
> S'utilitza en **sessions de KYB (verificació d'empreses)** quan el pas de persones clau ha enviat la llista de parts i ha generat sessions KYC o KYB filles. La sessió pare espera fins que **totes les parts obligatòries completin la seva verificació individual**.
>
> * **Què cal fer:** Supervisar els estats de les sessions KYC filles. Quan totes les parts obligatòries acabin (aprovades, rebutjades o caducades), la sessió pare tornarà a agregar automàticament els resultats per determinar l'estat final.
> * **El webhook inclou:** La llista actual de parts i els estats de les seves sessions filles.
> * **Transicions a:** `"Approved"`, `"Declined"`, `"In Review"` (quan totes les sessions filles hagin arribat a un estat terminal)
> * **Transicions des de:** `"In Progress"` (després d'enviar el pas de persones clau)
> * **Nota:** Si es tornen a presentar els passos d'una sessió KYC filla, la sessió pare torna a `"Awaiting User"` fins que es completi la sessió tornada a presentar. Una comprovació del registre KYB amb estat `"Declined"` té prioritat sobre `"Awaiting User"`.

> [accordion] Tornada a presentar - "Resubmitted"
>
> **Valor de l'API:** `"Resubmitted"`
>
> Un revisor ha sol·licitat que l'usuari **torni a fer passos de verificació concrets** (per exemple, tornar a fer una fotografia borrosa del document).
>
> * **Què cal fer:** Esperar que l'usuari completi els passos que s'han de tornar a presentar. El sistema tornarà a avaluar automàticament la sessió.
> * **El webhook inclou:** L'objecte `resubmit_info` amb la llista de funcionalitats que cal repetir i els motius.
> * **Transicions a:** `"Approved"`, `"Declined"`, `"In Review"` o `"Abandoned"` quan la finestra de la sessió acabi abans que la persona torni a fer els passos.

> [accordion] Caducada - "Expired"
>
> **Valor de l'API:** `"Expired"`
>
> La sessió **ha caducat abans que l'usuari obrís l'enllaç de verificació**.
>
> * **Què cal fer:** Crear una sessió nova i enviar a l'usuari un enllaç nou.
> * **Estat terminal:** no hi ha més transicions.

> [accordion] Abandonada - "Abandoned"
>
> **Valor de l'API:** `"Abandoned"`
>
> L'usuari **ha començat però no ha acabat** la verificació dins del termini permès.
>
> * **Què cal fer:** Enviar un recordatori o crear una sessió nova.
> * **Sense transicions automàtiques.** Un revisor, o `PATCH /v3/session/{sessionId}/update-status/`, encara la pot posar a `"Approved"`, `"Declined"` o `"Resubmitted"`.

> [accordion] KYC caducat - "Kyc Expired"
>
> **Valor de l'API:** `"Kyc Expired"`
>
> El document verificat durant la sessió **ha superat la seva pròpia data de caducitat**. L'activador és aquesta data, no un termini mesurat des de l'aprovació, i no s'envia cap avís previ.
>
> * **Què cal fer:** Demanar a l'usuari que es torni a verificar amb una sessió nova. `status.updated` notifica la transició, i el resultat de la verificació d'identitat porta una advertència `DOCUMENT_EXPIRED`.
> * **Controlat per:** el **Expiration mode** d'aquell país i tipus de document a *ID verification → Additional settings by country & document type*. **Reject expired** (el valor per defecte) supervisa el document; **Allow expired** fa que la sessió mai passi a aquest estat.
> * **Sense transicions automàtiques.** Un revisor, o `PATCH /v3/session/{sessionId}/update-status/`, encara la pot posar a `"Approved"`, `"Declined"` o `"Resubmitted"`.

***

## Transicions d'estat

| Des de | A | Activador |
| - | - | - |
| `"Not Started"` | `"In Progress"` | L'usuari obre l'enllaç de verificació |
| `"Not Started"` | `"Expired"` | El TTL de la sessió venç abans que l'usuari obri l'enllaç |
| `"In Progress"` | `"Approved"` | Totes les comprovacions automàtiques es superen |
| `"In Progress"` | `"Declined"` | Una o més comprovacions fallen |
| `"In Progress"` | `"In Review"` | Les comprovacions marquen advertències que requereixen revisió humana |
| `"In Progress"` | `"Awaiting User"` | S'envia el pas de persones clau de KYB; el pare espera les parts KYC filles |
| `"In Progress"` | `"Abandoned"` | L'usuari no acaba dins del termini |
| `"Awaiting User"` | `"Approved"` | Totes les parts KYB obligatòries acaben i les comprovacions agregades es superen |
| `"Awaiting User"` | `"Declined"` | Una part obligatòria és rebutjada o la comprovació del registre de KYB falla |
| `"Awaiting User"` | `"In Review"` | El resultat agregat de KYB requereix revisió manual |
| `"In Review"` | `"Approved"` | El revisor aprova manualment |
| `"In Review"` | `"Declined"` | El revisor rebutja manualment |
| `"In Review"` | `"Resubmitted"` | El revisor sol·licita que es refacin passos concrets |
| `"Declined"` | `"Resubmitted"` | El revisor sol·licita que es refacin passos concrets |
| `"Approved"` | `"Resubmitted"` | El revisor sol·licita que es refacin passos concrets |
| `"Approved"` | `"Declined"` | El revisor o l'API estableix l'altra decisió |
| `"Declined"` | `"Approved"` | El revisor o l'API estableix l'altra decisió |
| `"Abandoned"`, `"Kyc Expired"` | `"Approved"`, `"Declined"`, `"Resubmitted"` | El revisor o l'API decideix una sessió que va acabar sense decisió |
| `"Resubmitted"` | `"Abandoned"` | La finestra de la sessió acaba abans que la persona refaci els passos |
| `"Resubmitted"` | `"Approved"` | Els passos reenviats superen totes les comprovacions |
| `"Resubmitted"` | `"Declined"` | Els passos reenviats fallen |
| `"Resubmitted"` | `"In Review"` | Els passos reenviats marquen advertències noves |
| `"Resubmitted"` (fill de KYB) | `"Awaiting User"` (pare de KYB) | El pare torna a l'estat d'espera fins que el fill acaba |
| `"Approved"` | `"Kyc Expired"` | Passa la data de caducitat del document verificat (el mode de caducitat és **Reject expired**) |

### Diagrama del cicle de vida

```mermaid theme={null}
flowchart LR
    NS["Not Started"] --> IP["In Progress"]
    NS --> EX["Expired"]
    IP --> AP["Approved"]
    IP --> DC["Declined"]
    IP --> IR["In Review"]
    IP --> AU["Awaiting User<br/>(KYB only)"]
    IP --> AB["Abandoned"]
    AU --> AP
    AU --> DC
    AU --> IR
    IR --> AP
    IR --> DC
    IR --> RS["Resubmitted"]
    DC --> RS
    AP --> RS
    AP <--> DC
    AB --> AP
    AB --> DC
    AB --> RS
    KE --> AP
    KE --> DC
    KE --> RS
    RS --> AB
    RS --> AP
    RS --> DC
    RS --> IR
    AP --> KE["Kyc Expired"]
```

***

## Terminal vs no terminal

| Categoria | Estats | Significat |
| - | - | - |
| **Decidit** | `"Approved"`, `"Declined"`, `"Kyc Expired"` | Les comprovacions han produït una decisió i res no la canvia per si sol, excepte `"Approved"` → `"Kyc Expired"` quan passa la data de caducitat del document verificat. Un revisor o l'endpoint d'actualització d'estat encara pot canviar la decisió. |
| **No terminal** | `"Not Started"`, `"In Progress"`, `"Resubmitted"`, `"Awaiting User"` | Encara actius: esperen l'acció de l'usuari, sessions filles o processament. |
| **Actuable** | `"In Review"` | Requereix intervenció manual del vostre equip. |
| **Inactiu** | `"Expired"`, `"Abandoned"` | Han acabat sense una decisió de verificació. `"Expired"` no canvia mai; un revisor encara pot decidir una sessió `"Abandoned"`. |

***

## Gestió dels estats al vostre codi

Utilitzeu webhooks o la [API de recuperació de sessió](https://docs.didit.me/ca/sessions-api/retrieve-session.md) per reaccionar als canvis d'estat.

> [!WARNING]
>
> Els estats són **cadenes exactes, sensibles a majúscules i minúscules, amb espais**. Per exemple, `"In Review"` (no `"in_review"` ni `"IN_REVIEW"`). Utilitzeu sempre la igualtat estricta (`===`) en fer la comparació.

```javascript theme={null}
// All ten possible status string values (StatusChoices, source of truth):
// "Not Started"  | "In Progress" | "Approved"     | "Declined" |
// "In Review"    | "Resubmitted" | "Awaiting User"|
// "Expired"      | "Abandoned"   | "Kyc Expired"

async function handleWebhook(webhook) {
  const { status, vendor_data: vendorData } = webhook;

  switch (status) {
    case "Not Started":
      // Session created but user hasn't opened the link yet
      break;

    case "In Progress":
      // User is actively completing verification steps
      break;

    case "Approved":
      // All checks passed — grant access
      await db.users.update(vendorData, {
        verified: true,
        verifiedAt: new Date(),
        decision: webhook.decision,
      });
      break;

    case "Declined":
      // Verification failed — notify user
      await db.users.update(vendorData, {
        verificationStatus: "declined",
        declineReasons: webhook.decision?.warnings,
      });
      break;

    case "In Review":
      // Needs manual review by compliance team
      await db.users.update(vendorData, {
        verificationStatus: "pending_review",
      });
      break;

    case "Awaiting User":
      // KYB parent waiting for all child KYC parties to finish
      await db.users.update(vendorData, {
        verificationStatus: "awaiting_kyb_parties",
      });
      break;

    case "Resubmitted":
      // User will redo specific steps
      await db.users.update(vendorData, {
        verificationStatus: "resubmission_pending",
        resubmitInfo: webhook.resubmit_info,
      });
      break;

    case "Abandoned":
      // User started but didn't finish — send reminder
      await sendReminderEmail(vendorData);
      break;

    case "Expired":
    case "Kyc Expired":
      // Session expired — create a new one
      await createNewSession(vendorData);
      break;
  }
}
```

***

## Reenviament

L'estat **Resubmitted** permet que el vostre equip de compliment doni a l'usuari una segona oportunitat sense crear una sessió nova.

**1. El revisor inicia el reenviament**

Des de la Console, obre una sessió `In Review` o `Declined` i fes clic a **Sol·licitar reenviament**. Selecciona quins passos s'han de tornar a fer.

**2. Les dades anteriors s'arxiven**

El sistema reinicia les funcionalitats seleccionades i marca les dades prèvies com a `previous_attempt`, conservant tot el registre d'auditoria.

**3. Es notifica l'usuari**

Si hi ha un correu electrònic disponible, l'usuari rep un correu electrònic localitzat amb un enllaç directe per reprendre el procés.

**4. L'usuari refà passos concrets**

L'usuari només repeteix els passos marcats, no tota la verificació.

**5. El sistema torna a avaluar**

Quan es completa, la sessió passa automàticament a `"Approved"`, `"Declined"` o `"In Review"`.

### Payload del webhook de reenviament

```json theme={null}
{
  "session_id": "uuid-of-the-session",
  "status": "Resubmitted",
  "resubmit_info": {
    "nodes_to_resubmit": [
      { "node_id": "feature_ocr", "feature": "OCR" },
      { "node_id": "feature_liveness", "feature": "LIVENESS" }
    ],
    "reasons": {
      "feature_ocr": "DOCUMENT_EXPIRED",
      "feature_liveness": "LOW_LIVENESS_SCORE"
    }
  }
}
```

`reasons` relaciona cada `node_id` reenviat amb el codi d'advertència del registre més rellevant d'aquest pas (els mateixos codis que informa la [decisió](https://docs.didit.me/ca/reference/data-models.md)), perquè el pugueu relacionar amb la vostra pròpia còpia. També és el codi que la pantalla de reenviament del flux allotjat i el correu de reenviament localitzen per a l'usuari, excepte les advertències que revelarien un senyal de cribratge o de frau (duplicats, AML, llista de bloqueig, comprovacions entre organitzacions, integritat de la ubicació i similars): en aquests casos la persona veu un motiu genèric, i `resubmit_info.reasons` del vostre webhook sempre conté el codi real. Un pas sense cap advertència registrada no té entrada.

### Quines funcionalitats es poden reenviar?

Qualsevol funcionalitat amb un estat no aprovat: **Declined**, **In Review**, **Not Finished**, **Not Started** o **Expired**.

> [!TIP]
>
> Podeu sol·licitar el reenviament diverses vegades en la mateixa sessió. Cada cicle arxiva les dades de l'intent anterior, cosa que us dona una visibilitat completa de l'historial de verificació de l'usuari.

***

## Pràctiques recomanades

> [card] Supervisa les sessions en revisió
>
> Configura alertes (per correu electrònic o Slack) a la Didit Console per rebre una notificació quan les sessions necessitin revisió manual.

> [card] Prioritza el reenviament
>
> Si el problema es pot resoldre (una fotografia borrosa, el costat equivocat del document), sol·licita un reenviament en lloc de rebutjar la sessió. Així millora la conversió.

> [card] Fes seguiment dels abandonaments
>
> Unes taxes elevades de sessions abandonades o caducades poden indicar fricció en l'experiència d'usuari. Considera ajustar el TTL de la sessió o millorar les indicacions per a l'usuari.

> [card] Gestors idempotents
>
> Els webhooks es poden reintentar. Utilitza `session_id` com a clau única per assegurar que processis cada canvi d'estat només una vegada.

> [!WARNING]
>
> Verifica sempre les signatures dels webhooks abans de processar els payloads. Didit ofereix tres mètodes: `X-Signature`, `X-Signature-V2` (recomanat) i `X-Signature-Simple`, obsolet, que només autentica l'embolcall i mai el cos `decision`. Consulta [Webhooks](https://docs.didit.me/ca/integration/webhooks.md#verificació-de-la-signatura) per a més detalls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.