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

# Enrolamiento

Generar un enlace de enrolamiento para que el ejecutivo pueda detonarlo.

## Objetivo

Este endpoint permite crear una URL de enrolamiento por persona dentro de un expediente existente, para iniciar el proceso desde el canal de atención (por ejemplo, Microsoft Teams).

## ¿Cuándo usarlo?

Úsalo cuando:

* Ya cuentas con un `DocumentId` válido del expediente.
* Ya identificaste a la persona (`PersonId`) que debe completar su enrolamiento.
* En la petición de `tracking`, el campo `IsEnrollmentAllowed` es `true`.

## Datos requeridos

La petición requiere:

* `DocumentId`: identificador del expediente.
* `PersonId`: identificador de la persona a enrolar.
* `AgentMail`: correo del ejecutivo que dispara la acción.

Ejemplo de payload:

```json theme={null}
{
  "DocumentId": "eaeea393-81db-4269-9dcc-ede8669f2ecf",
  "PersonId": "7c1cf3c0-9c2c-4c66-9b34-6b5f4c6c9a1e",
  "AgentMail": "ejecutivo@correo.com"
}
```

## Respuesta esperada (200)

Cuando la operación es exitosa, se devuelve un objeto con:

* `Code`: código de resultado interno.
* `Status`: estado general de la operación.
* `Message`: mensaje descriptivo.
* `Data.Id`: identificador del registro generado.
* `Data.EnrollmentUrl`: URL de enrolamiento lista para compartirse con el ejecutivo.

Ejemplo:

```json theme={null}
{
  "Code": 200,
  "Status": "Success",
  "Message": "Enrolamiento generado",
  "Data": {
    "Id": "2b0db6c2-9e1d-4a4b-8a4b-5a7b7d9b6c3f",
    "EnrollmentUrl": "https://oam.institucional.com:5442/AbeWeb#/firstStepOrq?data=..."
  }
}
```

## Posibles respuestas de error

| Código | Escenario        | Descripción                                                                          |
| ------ | ---------------- | ------------------------------------------------------------------------------------ |
| 400    | Validación       | Faltan campos requeridos o formato inválido (`DocumentId`, `PersonId`, `AgentMail`). |
| 401    | Autenticación    | API Key inválida o sin suscripción activa.                                           |
| 403    | Autorización     | Workspace inválido o inactivo.                                                       |
| 404    | Regla de negocio | Enrolamiento no permitido para la persona/expediente.                                |

## Recomendación operativa

Después de generar `EnrollmentUrl`, compártela de inmediato al ejecutivo y registra el seguimiento con el endpoint de tracking para monitorear el avance del enrolamiento.


## OpenAPI

````yaml POST /enrollment/v1/url
openapi: 3.0.0
info:
  title: KYB API
  version: 1.0.0
servers:
  - url: https://nufi.azure-api.net/kyb
    description: Productivo
  - url: https://nufi.azure-api.net/kyb/dev
    description: Sandbox
  - url: https://nufi-kyb-services-staging-azurefunction.azurewebsites.net/api
    description: Staging
security: []
paths:
  /enrollment/v1/url:
    post:
      tags:
        - default
      summary: enrollment
      operationId: createEnrollmentUrl
      parameters:
        - name: NUFI-API-KEY
          in: header
          required: true
          schema:
            type: string
          example: '{{NUFI_API_KEY}}'
        - name: X-Workspace
          in: header
          required: true
          schema:
            type: string
          example: '{{WORKSPACE_ID}}'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - DocumentId
                - PersonId
                - AgentMail
              properties:
                DocumentId:
                  type: string
                PersonId:
                  type: string
                AgentMail:
                  type: string
            examples:
              default:
                value:
                  DocumentId: eaeea393-81db-4269-9dcc-ede8669f2ecf
                  PersonId: 7c1cf3c0-9c2c-4c66-9b34-6b5f4c6c9a1e
                  AgentMail: ejecutivo@correo.com
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    example: 200
                  Status:
                    type: string
                    example: Success
                  Message:
                    type: string
                    example: Enrolamiento generado
                  Data:
                    type: object
                    properties:
                      Id:
                        type: string
                        example: 2b0db6c2-9e1d-4a4b-8a4b-5a7b7d9b6c3f
                      EnrollmentUrl:
                        type: string
                        format: uri
              examples:
                success:
                  value:
                    Code: 200
                    Status: Success
                    Message: Enrolamiento generado
                    Data:
                      Id: 2b0db6c2-9e1d-4a4b-8a4b-5a7b7d9b6c3f
                      EnrollmentUrl: >-
                        https://oam.institucional.com:5442/AbeWeb#/firstStepOrq?data=sample
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    example: 400
                  Status:
                    type: string
                    example: bad_request
                  Message:
                    type: string
                    example: Error de validacion
                  Data:
                    type: array
                    items:
                      type: string
              examples:
                validationError:
                  value:
                    Code: 400
                    Status: bad_request
                    Message: Error de validacion
                    Data:
                      - El campo DocumentId es obligatorio
                      - El campo PersonId es obligatorio
                      - El campo AgentMail es obligatorio
                      - El DocumentId no es válido.
                      - El PersonId no es válido.
                      - El AgentMail no es válido.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  status:
                    type: string
                    example: forbidden
                  message:
                    type: string
                  data:
                    nullable: true
              examples:
                unauthorized:
                  value:
                    code: 401
                    status: forbidden
                    message: >-
                      La API Key ha sido denegada, asegurate de mandar una API
                      Key valida y con una suscripción activa
                    data: null
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    example: 403
                  Status:
                    type: string
                    example: forbidden
                  Message:
                    type: string
                  Data:
                    nullable: true
              examples:
                forbidden:
                  value:
                    Code: 403
                    Status: forbidden
                    Message: El ID de Workspace no es válido o no está activo
                    Data: null
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  Code:
                    type: integer
                    example: 403
                  Status:
                    type: string
                    example: not_allowed
                  Message:
                    type: string
                    example: Enrolamiento no permitido
                  Data:
                    nullable: true
              examples:
                notAllowed:
                  value:
                    Code: 403
                    Status: not_allowed
                    Message: Enrolamiento no permitido
                    Data: null

````