Onboarding API

La API de Onboarding permite gestionar el proceso de incorporación de clientes al sistema. Esto incluye el registro de nuevos procesos de onboarding, la carga de documentos necesarios para la verificación de identidad y validación, la consulta de información relacionada con los procesos en curso, y la gestión de datos maestros como actividades económicas.

Conceptos Clave

Proceso de Onboarding: Conjunto de pasos y verificaciones necesarios para incorporar a un nuevo cliente al sistema. Incluye la recopilación de información personal, fiscal y regulatoria, así como la carga y verificación de documentos.
Documentos: Archivos (como imágenes o PDFs) que los clientes deben proporcionar para verificar su identidad y cumplir con los requisitos regulatorios. Ejemplos incluyen DNI, selfies y documentos fiscales.
Tablas Maestras: Catálogos y datos de referencia utilizados durante el proceso de onboarding, como las actividades económicas disponibles.

Especificaciones Técnicas

Autenticación

Todas las solicitudes a la API requieren autenticación mediante un token JWT válido en el encabezado Authorization con el formato Bearer {token}.

Servidor

URL Base: https://api-dev.max.capital/onboarding/api

Versionado

La API utiliza versionado en la URL. La versión actual es v1, por lo que todos los endpoints comienzan con /v1/.

Límites Generales

Tamaño máximo de archivos para carga de documentos: 5MB.
Tiempo de espera de solicitud: 30 segundos.

Endpoints

1. Registrar un nuevo proceso de onboarding

Este endpoint permite crear un nuevo proceso de onboarding para un cliente. Es el punto de entrada para iniciar la incorporación.

Método	URL	Descripción
`POST`	`/v1/onboardings`	Registra un nuevo proceso de onboarding

Encabezados Requeridos

Encabezado	Requerido	Descripción
`Authorization`	Sí	Token Bearer para autenticación (ej. `Bearer {your-access-token}`)
`Content-Type`	Sí	Tipo de contenido de la solicitud (ej. `application/json`)

Parámetros de la solicitud

** affiliation_id**: Identificador de afiliación (opcional).
Cuerpo de la solicitud: Un objeto JSON que contiene la información necesaria para el registro del proceso de onboarding. Este objeto debe ajustarse al esquema RegisterOnboardingDTO.

Ejemplo de cuerpo de solicitud:

{
  "account": {
    "people": [
      {
        "type": "HUMAN",
        "ownership_type": "OWNER",
        "signature_type": "INDIVIDUAL",
        "personal_info": {
          "first_name": "Juan",
          "middle_name": "Carlos",
          "last_name": "Pérez",
          "second_last_name": "González",
          "document": {
            "type": "DNI_AR",
            "code": "28456789"
          },
          "gender": "MALE",
          "birth_date": "1982-05-15",
          "birth_country": "AR",
          "citizenship": "AR",
          "phone": "+5491156781234",
          "email": "[email protected]",
          "civil_status": {
            "type": "MARRIED",
            "spouse": {
              "name": "María",
              "surname": "López",
              "tax_document": {
                "type": "CUIT_AR",
                "code": "27301234569"
              }
            }
          }
        },
        "addresses": [
          {
            "type": "REAL",
            "street": "Av. Corrientes",
            "number": "1234",
            "floor": "5",
            "apartment": "A",
            "zip_code": "C1043AAZ",
            "city": "Buenos Aires",
            "state": "AR-C",
            "country": "AR"
          }
        ],
        "tax_info": {
          "document": {
            "type": "CUIT_AR",
            "code": "20284567890"
          },
          "income_tax_type": "NOT_REACHED",
          "value_added_tax_type": "NOT_REACHED",
          "is_obliged_subject": false,
          "gross_income_type": "NOT_APPLICABLE",
          "economic_activity": "43"
        }
      }
    ]
  }
}

Respuestas

201 Created: Proceso de onboarding registrado exitosamente. Retorna un objeto con el ID del proceso y otros detalles.

Ejemplo:

{
  "id": 12345,
  "template": "DEFAULT",
  "account": {
    "type": "ACCOUNT_HOLDER",
    "number": 987654,
    "people": [
      {
        "id": 67890,
        "type": "HUMAN",
        "personalInfo": {
          "firstName": "Juan",
          "lastName": "Pérez",
          "documentType": "DNI_AR",
          "documentNumber": "28456789"
        }
      }
    ]
  }
}

400 Bad Request: Error en los parámetros enviados.

Ejemplo:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "El parámetro 'account' es requerido.",
  "errorCode": "VALIDATION_ERROR"
}

401 Unauthorized: Token de autenticación inválido o no proporcionado.

Ejemplo:

{
  "statusCode": "401",
  "title": "Unauthorized",
  "detail": "Token de autenticación inválido o no proporcionado.",
  "errorCode": "AUTH_ERROR"
}

500 Internal Server Error: Error interno del servidor.

Ejemplo:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "Ocurrió un error inesperado en el servidor.",
  "errorCode": "SERVER_ERROR"
}

Ejemplo de Uso

curl -X POST 'https://api-dev.max.capital/onboarding/api/v1/onboardings' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: application/json' \
  -d '{
        "account": {
          "people": [
            {
              "type": "HUMAN",
              "ownership_type": "OWNER",
              "signature_type": "INDIVIDUAL",
              "personal_info": {
                "first_name": "Juan",
                "last_name": "Pérez",
                "document": {
                  "type": "DNI_AR",
                  "code": "28456789"
                },
                "gender": "MALE",
                "birth_date": "1982-05-15",
                "birth_country": "AR",
                "citizenship": "AR",
                "phone": "+5491156781234",
                "email": "[email protected]"
              },
              "addresses": [
                {
                  "type": "REAL",
                  "street": "Av. Corrientes",
                  "number": "1234",
                  "zip_code": "C1043AAZ",
                  "city": "Buenos Aires",
                  "state": "AR-C",
                  "country": "AR"
                }
              ],
              "tax_info": {
                "document": {
                  "type": "CUIT_AR",
                  "code": "20284567890"
                },
                "income_tax_type": "NOT_REACHED",
                "value_added_tax_type": "NOT_REACHED",
                "is_obliged_subject": false,
                "gross_income_type": "NOT_APPLICABLE",
                "economic_activity": "43"
              }
            }
          ]
        }
      }'

2. Subir documentos para verificación

Este endpoint permite cargar documentos necesarios para el proceso de verificación de identidad y validación durante el onboarding.

Método	URL	Descripción
`POST`	`/v1/onboardings/{id}/person/{idPerson}/document`	Sube un documento para una persona específica

Encabezados Requeridos

Encabezado	Requerido	Descripción
`Authorization`	Sí	Token Bearer para autenticación (ej. `Bearer {your-access-token}`)
`Content-Type`	Sí	Tipo de contenido de la solicitud (ej. `multipart/form-data`)

Parámetros de la URL

Parámetro	Requerido	Descripción
`id`	Sí	Identificador único del proceso de onboarding
`idPerson`	Sí	Identificador único de la persona asociada

Parámetros de Consulta

Parámetro	Requerido	Descripción
`documentType`	Sí	Tipo de documento (ej. `DNI_FRENTE_AR`)
`status`	Sí	Estado inicial del documento (ej. `PENDING`)
`expirationDate`	Sí	Fecha de expiración en formato ISO 8601 (ej. `2025-12-31T13:43:48.000Z`)
`runOcr`	Sí	Indica si se debe ejecutar OCR (`true`/`false`)

Cuerpo de la Solicitud

Un archivo multipart/form-data con el documento (PDF, JPG, PNG).

Respuestas

200 OK: Documento cargado exitosamente. Retorna el ID del documento.
- Ejemplo: 67890

400 Bad Request: Error en los parámetros enviados.

Ejemplo:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "El parámetro 'documentType' es requerido.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: No se encontró el proceso de onboarding o la persona.

Ejemplo:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Proceso de onboarding no encontrado.",
  "errorCode": "NOT_FOUND"
}

413 Payload Too Large: El archivo excede el tamaño permitido.

Ejemplo:

{
  "statusCode": "413",
  "title": "Payload Too Large",
  "detail": "El archivo excede el tamaño máximo permitido de 5MB.",
  "errorCode": "FILE_TOO_LARGE"
}

500 Internal Server Error: Error interno del servidor.

Ejemplo:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "Ocurrió un error inesperado en el servidor.",
  "errorCode": "SERVER_ERROR"
}

Ejemplo de Uso

curl -X POST 'https://api-dev.max.capital/onboarding/api/v1/onboardings/12345/person/67890/document?documentType=DNI_FRENTE_AR&status=PENDING&expirationDate=2025-12-31T13:43:48.000Z&runOcr=false' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/ruta/al/archivo/dni_frente.jpg'

3. Consultar un proceso de onboarding

Este endpoint permite obtener la información completa de un proceso de onboarding específico mediante su identificador único.

Método	URL	Descripción
`GET`	`/v1/onboardings/{id}`	Consulta un proceso de onboarding por su ID

Encabezados Requeridos

Encabezado	Requerido	Descripción
`Authorization`	Sí	Token Bearer para autenticación (ej. `Bearer {your-access-token}`)

Parámetros de la URL

Parámetro	Requerido	Descripción
`id`	Sí	Identificador único del proceso de onboarding

Respuestas

200 OK: Información del proceso recuperada exitosamente.

Ejemplo:

{
  "id": 12345,
  "status": "PENDING",
  "account": {
    "number": 987654,
    "type": "ACCOUNT_HOLDER",
    "people": [
      {
        "id": 67890,
        "type": "HUMAN",
        "status": "PENDING",
        "personalInfo": {
          "firstName": "Juan",
          "lastName": "Pérez",
          "documentType": "DNI_AR",
          "documentNumber": "28456789"
        }
      }
    ]
  }
}

400 Bad Request: Error en los parámetros enviados.

Ejemplo:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "El parámetro 'id' debe ser un número entero positivo.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Proceso de onboarding no encontrado.

Ejemplo:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Proceso de onboarding no encontrado.",
  "errorCode": "NOT_FOUND"
}

500 Internal Server Error: Error interno del servidor.

Ejemplo:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "Ocurrió un error inesperado en el servidor.",
  "errorCode": "SERVER_ERROR"
}

Ejemplo de Uso

curl -X GET 'https://api-dev.max.capital/onboarding/api/v1/onboardings/12345' \
  -H 'Authorization: Bearer {your-access-token}'

4. Obtener actividades económicas

Este endpoint permite recuperar el catálogo completo de actividades económicas disponibles en el sistema.

Método	URL	Descripción
`GET`	`/v1/master-tables/economic-activities`	Obtiene el catálogo de actividades económicas

Encabezados Requeridos

Encabezado	Requerido	Descripción
`Authorization`	Sí	Token Bearer para autenticación (ej. `Bearer {your-access-token}`)

Respuestas

200 OK: Catálogo recuperado exitosamente.

Ejemplo:

[
  {
    "idOption": "47",
    "description": "Empleados en relación de dependencia"
  },
  {
    "idOption": "620900",
    "description": "Otros servicios relacionados con la informática"
  }
]

400 Bad Request: Error en los parámetros enviados.

Ejemplo:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "Parámetros inválidos en la solicitud.",
  "errorCode": "VALIDATION_ERROR"
}

401 Unauthorized: Token de autenticación inválido o no proporcionado.

Ejemplo:

{
  "statusCode": "401",
  "title": "Unauthorized",
  "detail": "Token de autenticación inválido o no proporcionado.",
  "errorCode": "AUTH_ERROR"
}

500 Internal Server Error: Error interno del servidor.

Ejemplo:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "Ocurrió un error inesperado en el servidor.",
  "errorCode": "SERVER_ERROR"
}

Ejemplo de Uso

curl -X GET 'https://api-dev.max.capital/onboarding/api/v1/master-tables/economic-activities' \
  -H 'Authorization: Bearer {your-access-token}'

5. Obtener documento por ID

Este endpoint permite recuperar la información completa de un documento específico utilizando su identificador único.

Método	URL	Descripción
`GET`	`/v1/documents/{id}`	Obtiene un documento por su ID

Encabezados Requeridos

Encabezado	Requerido	Descripción
`Authorization`	Sí	Token Bearer para autenticación (ej. `Bearer {your-access-token}`)

Parámetros de la URL

Parámetro	Requerido	Descripción
`id`	Sí	Identificador único del documento

Respuestas

200 OK: Documento recuperado exitosamente.

Ejemplo:

{
  "id": 67890,
  "status": "PENDING",
  "documentType": "DNI_FRENTE_AR",
  "expirationDate": "2025-12-31"
}

400 Bad Request: Error en los parámetros enviados.

Ejemplo:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "El parámetro 'id' debe ser un número entero positivo.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Documento no encontrado.

Ejemplo:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Documento no encontrado.",
  "errorCode": "NOT_FOUND"
}

500 Internal Server Error: Error interno del servidor.

Ejemplo:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "Ocurrió un error inesperado en el servidor.",
  "errorCode": "SERVER_ERROR"
}

Ejemplo de Uso

curl -X GET 'https://api-dev.max.capital/onboarding/api/v1/documents/67890' \
  -H 'Authorization: Bearer {your-access-token}'

6. Actualizar estado de un documento

Este endpoint permite actualizar el estado de un documento específico en el sistema.

Método	URL	Descripción
`PATCH`	`/v1/documents/{id}/status`	Actualiza el estado de un documento

Encabezados Requeridos

Encabezado	Requerido	Descripción
`Authorization`	Sí	Token Bearer para autenticación (ej. `Bearer {your-access-token}`)
`Content-Type`	Sí	Tipo de contenido de la solicitud (ej. `application/json`)

Parámetros de la URL

Parámetro	Requerido	Descripción
`id`	Sí	Identificador único del documento

Cuerpo de la Solicitud

Un objeto JSON con el nuevo estado del documento.

Ejemplo de cuerpo de solicitud:

{
  "status": "APPROVED"
}

Respuestas

200 OK: Estado del documento actualizado exitosamente.

Ejemplo:

{
  "id": 67890,
  "status": "APPROVED",
  "documentType": "DNI_FRENTE_AR",
  "expirationDate": "2025-12-31"
}

400 Bad Request: Error en los parámetros enviados.

Ejemplo:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "El estado proporcionado no es válido.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Documento no encontrado.

Ejemplo:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Documento no encontrado.",
  "errorCode": "NOT_FOUND"
}

500 Internal Server Error: Error interno del servidor.

Ejemplo:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "Ocurrió un error inesperado en el servidor.",
  "errorCode": "SERVER_ERROR"
}

Ejemplo de Uso

curl -X PATCH 'https://api-dev.max.capital/onboarding/api/v1/documents/67890/status' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: application/json' \
  -d '{"status": "APPROVED"}'

7. Eliminar un proceso de onboarding

Este endpoint permite eliminar un proceso de onboarding específico del sistema.

Método	URL	Descripción
`DELETE`	`/v1/onboardings/{id}`	Elimina un proceso de onboarding por su ID

Encabezados Requeridos

Encabezado	Requerido	Descripción
`Authorization`	Sí	Token Bearer para autenticación (ej. `Bearer {your-access-token}`)

Parámetros de la URL

Parámetro	Requerido	Descripción
`id`	Sí	Identificador único del proceso de onboarding

Respuestas

204 No Content: Proceso de onboarding eliminado exitosamente.

400 Bad Request: Error en los parámetros enviados.

Ejemplo:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "El parámetro 'id' debe ser un número entero positivo.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Proceso de onboarding no encontrado.

Ejemplo:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Proceso de onboarding no encontrado.",
  "errorCode": "NOT_FOUND"
}

500 Internal Server Error: Error interno del servidor.

Ejemplo:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "Ocurrió un error inesperado en el servidor.",
  "errorCode": "SERVER_ERROR"
}

Ejemplo de Uso

curl -X DELETE 'https://api-dev.max.capital/onboarding/api/v1/onboardings/12345' \
  -H 'Authorization: Bearer {your-access-token}'

Notas Adicionales

Autenticación: Todas las solicitudes requieren un token JWT válido en el encabezado Authorization.
Versionado: Todos los endpoints pertenecen a la versión v1 de la API, como se indica en la URL (/v1/).
Esquemas: Para una definición completa del esquema RegisterOnboardingDTO y otros, consulta la documentación oficial de esquemas en el repositorio de la API.
Manejo de Errores: La API devuelve respuestas de error en formato JSON con un código de estado HTTP correspondiente y detalles sobre el error.
Formatos de Fecha: Todas las fechas deben estar en formato ISO 8601 (ej. 2025-12-31T13:43:48.000Z).
Tipos de Documentos Soportados: Los tipos de documentos aceptados incluyen DNI_FRENTE_AR, DNI_DORSO_AR, SELFIE, entre otros, según las tablas maestras del sistema.

Conceptos Clave​

Especificaciones Técnicas​

Autenticación​

Servidor​

Versionado​

Límites Generales​

Endpoints​

1. Registrar un nuevo proceso de onboarding​

Encabezados Requeridos​

Parámetros de la solicitud​

Respuestas​

Ejemplo de Uso​

2. Subir documentos para verificación​

Encabezados Requeridos​

Parámetros de la URL​

Parámetros de Consulta​

Cuerpo de la Solicitud​

Respuestas​

Ejemplo de Uso​

3. Consultar un proceso de onboarding​

Encabezados Requeridos​

Parámetros de la URL​

Respuestas​

Ejemplo de Uso​

4. Obtener actividades económicas​

Encabezados Requeridos​

Respuestas​

Ejemplo de Uso​

5. Obtener documento por ID​

Encabezados Requeridos​

Parámetros de la URL​

Respuestas​

Ejemplo de Uso​

6. Actualizar estado de un documento​

Encabezados Requeridos​

Parámetros de la URL​

Cuerpo de la Solicitud​

Respuestas​

Ejemplo de Uso​

7. Eliminar un proceso de onboarding​

Encabezados Requeridos​

Parámetros de la URL​

Respuestas​

Ejemplo de Uso​

Notas Adicionales​

Conceptos Clave

Especificaciones Técnicas

Autenticación

Servidor

Versionado

Límites Generales

Endpoints

1. Registrar un nuevo proceso de onboarding

Encabezados Requeridos

Parámetros de la solicitud

Respuestas

Ejemplo de Uso

2. Subir documentos para verificación

Encabezados Requeridos

Parámetros de la URL

Parámetros de Consulta

Cuerpo de la Solicitud

Respuestas

Ejemplo de Uso

3. Consultar un proceso de onboarding

Encabezados Requeridos

Parámetros de la URL

Respuestas

Ejemplo de Uso

4. Obtener actividades económicas

Encabezados Requeridos

Respuestas

Ejemplo de Uso

5. Obtener documento por ID

Encabezados Requeridos

Parámetros de la URL

Respuestas

Ejemplo de Uso

6. Actualizar estado de un documento

Encabezados Requeridos

Parámetros de la URL

Cuerpo de la Solicitud

Respuestas

Ejemplo de Uso

7. Eliminar un proceso de onboarding

Encabezados Requeridos

Parámetros de la URL

Respuestas

Ejemplo de Uso

Notas Adicionales