Aprobación individual

Para solicitar la aprobación de un documento individual, el sistema cliente debe enviar una petición al servicio del aprobador de Ciudadanía Digital. A continuación, se detalla el proceso y parámetros requeridos:

Solicitud

Tipo: POST

https://<url-aprobador>/api/solicitudes

Header

Campo	Tipo	Descripción
Authorization	string	Bearer + token, token de autorización para consumir la ruta en el aprobador.
content-type	string	Etiqueta en la solicitud que indica el tipo de datos que se está enviando.

Parámetros

Campo	Tipo	Descripción
tipoDocumento	string	El tipo de documento que se envía puede ser en formato PDF o JSON
hashDocumento	string	El hash (SHA-256) del documento es una huella digital única del archivo, que permite verificar su integridad al cambiar su contenido.
descripcion	string	Descripción de la operación.
idTramite	uuid	Identificador único de trámite generado por el sistema cliente, se espera un campo del tipo uuidv4.
accessToken	string	El token generado al iniciar sesión a través de Ciudadanía Digital
documento	string	El documento debe enviarse en formato PDF o JSON, codificado en Base64, para garantizar su transmisión segura como texto.

Ejemplo solicitud de aprobación de documentos PDF

curl -L -X POST 'https://<url-aprobador>/api/solicitudes' \
-H 'Authorization: Bearer <token_cliente>' \
-H 'Content-Type: application/json' \
-d '{
  "tipoDocumento": "PDF",
  "hashDocumento": "09181e6f9a43e93602a5d4df6df998460ae02d779a559851d27af61d51ceb47a",
  "descripcion": "Trámite de prueba PDF",
  "idTramite": "bf6807c3-fd3c-49e7-97f7-8344f90e598e",
  "accessToken": "LbXAWFyNpvLRvU0UlCzB6Cp16iRGz_xKCvV4HNnNU-E",
  "documento": "NoZWNrc3VtIC8zRDJEOEU0N0VGRERERjU4OTQxMURCQkY3NEUzNkJBRgoPgpzdGFydHhyZWYKNzM2CiUlRU9GCg==..."
}'

Ejemplo solicitud de aprobación de documentos JSON

curl -L -X POST \
  https://<url-aprobador>/api/solicitudes \
  -H 'Authorization: Bearer <token_cliente>' \
  -H 'Content-Type: application/json' \
  -d '{
      "tipoDocumento": "JSON",
      "hashDocumento": "812c7d89f28613cbdc03976a4f6eebd8bb9ac4db23c5ecf6774c769a9372b01b",
      "descripcion": "Trámite de prueba JSON",
      "idTramite": "9dd95700-cb0d-11e8-a9c0-29fb28bbb654",
      "accessToken": "0UCOcFmVx5REpbeOHzpgf_z4jaduw7gQJWltcLB8Gdk",
      "documento":
        "eyJkb2N1bWVudG8iOiJBcHJvYmFjacOzbiBkZSBkb2N1bWVudG8gZGUgZGVjbGFyYWNpw7NuIiwibnJvLWRvY3VtZW50byI6OTAwMzIsImNvZGlnby1kb2N1bWVudG8iOiJBQzc4LTkwMDMyLTIwMTkiLCJyZW1pdGVudGVzIjpbeyJpdGVtIjoiY3VpZC01NiIsImZlY2hhLWZpcm1hIjoiMjAxOS8xMS8wMSAxNDowMDozMiJ9LHsiaXRlbSI6ImN1aWQtNTYiLCJmZWNoYS1maXJtYSI6IjIwMTkvMTAvMTggMTg6MTA6MjAifV0sImNvbnRlbmlkbyI6Ik1lZGlhbnRlIGxhIHByZXNlbnRlIHNlIGFwcnVlYmEgZWwgZG9jdW1lbnRvIEFDNzgtOTAwMzItMjAxOSB5IHNlIGNvbmZpcm1hIGxhIHJldmlzacOzbiIsIm9ic2VydmFjaW9uIjoiIiwicmV2aXNvciI6eyJpdGVtIjoiYXRydS0xMiIsImZlY2hhLWZpcm1hIjoiMjAxOS8xM
        S8wMyAxNDoxMToyMCJ9fQ==="
    }'

Respuesta

Ejemplo de respuesta exitosa (para PDF y JSON)

HTTP status code: 200

{
  "finalizado": true,
  "mensaje": "Registro creado con éxito.",
  "datos": {
    "link": "https://<url-aprobador>/solicitudes/be54d222-af82-4c8d-8d6e-d503cfc9d0c1"
  }
}

Ejemplo de respuesta errónea

HTTP status code: 412

{
  "finalizado": false,
  "codigo": 412,
  "timestamp": 1738770315,
  "mensaje": "Token inválido, ingrese con su cuenta de Ciudadanía Digital"
}

Notificación backend

El sistema cliente debe exponer un servicio REST con formato JSON para que se pueda notificar si el ciudadano aceptó o rechazó la aprobación del documento. El servicio de aprobación utilizará los campos URL de notificación y URL de redirección que han sido configurados en el registro del sistema cliente.

Se envía esta notificación directamente al backend del sistema cliente.

Tipo: POST

Url: URL de notificación (backend)

Header

Campo	Tipo	Descripción
Authorization	string	Bearer + token, token de autorización para consumir la ruta, dicho token se registró en la configuración del servicio del sistema cliente.
content-type	string	Etiqueta en la solicitud que indica el tipo de datos que se está enviando.

El cuerpo del mensaje enviado por el servicio de aprobación de ciudadanía digital es el siguiente:

Parámetros enviados

Campos	Tipo	Descripción
aceptado	boolean	Parámetro que indica si el ciudadano aceptó/rechazó la información enviada en la solicitud de aprobación.
introducido	boolean	Parámetro que indica si se ha conseguido introducir el registro en la cadena de bloques exitosamente. En caso de error este campo es false y el sistema cliente deberá volver a enviar la solicitud de aprobación (con campo idTramite distinto).
requestUuid	uuid	Identificador de la solicitud del trámite (el mismo que el sistema cliente envió como idTramite al iniciar el flujo).
codigoOperacion	string	Identificador adicional de solicitud de aprobación. Se envía una cadena vacía en caso de que el campo introducido sea false.
mensaje	string	Mensaje del resultado de la operación, cuando el campo introducido es false en este campo se especifica el error.
transaction_id	string	Código de transacción para comprobaciones en la blockchain. Se envía cadena vacía en caso de que el campo introducido sea false.
fechaHoraSolicitud	string	Fecha y hora en que se realizó la solicitud de firma en formato DD/MM/YYYY HH:mm:ss.SSS
hashDatos	string	Hash del documento enviado en la solicitud.
ci	string	Número de documento del ciudadano que usa el servicio.

Ejemplo

{
  "aceptado": true,
  "introducido": true,
  "requestUuid": "68f14d69-89d1-4dd4-a954-b129250af68a",
  "codigoOperacion": "f8af9ace-0f60-4e27-808f-90b4a054b625",
  "mensaje": "Completado",
  "transaction_id": "f3b6c8b84e7f73a3d39b3e161701d160485bce519c63413bfdac04478ff0a07a",
  "fechaHoraSolicitud": "25/10/2024 15:19:14.000",
  "hashDatos": "0bd46d96d8b68e6040a2d2bd6fd48fbe1d4e60b9f2ac9a5a99ac844d54624a75",
  "ci": "9270816"
}

Redirección frontend

Adicionalmente, el aprobador realiza la redirección al frontend del sistema cliente (URL de redirección FrontEnd) en el cual se envían los siguientes parámetros:

Parámetros enviados

Campos	Tipo	Descripción
estado	string	Indica si el usuario ha confirmado o rechazado la solicitud de aprobación.
finalizado	string	Resultado de la aprobación o rechazo de la solicitud de aprobación, true si se confirmó y realizó, false si no se realizó la aprobación.
mensaje	string	Mensaje del resultado de la operación.
uuidBlockchain	string	UUID Blockchain.
linkVerificacion	string	Enlace de verificación general.
linkVerificacionUnico	string	Enlace de verificación exclusivo para este documento.
transactionCode	string	Identificador único del trámite en la blockchain.
requestUuid	string	Campo requestUuid enviado al iniciar el flujo de aprobación.

Ejemplo

https://<url-cliente>?estado=true&finalizado=true&mensaje=Completado&uuidBlockchain=f8af9ace-0f60-4e27-808f-90b4a054b625&linkVerificacion=<url-aprobador>%2Fhome%2Fverificacion-documentos&linkVerificacionUnico=<url-aprobador>%2Fhome%2Fverificacion%2Ff3b6c8b84e7f73a3d39b3e161701d160485bce519c63413bfdac04478ff0a07a&transactionCode=f3b6c8b84e7f73a3d39b3e161701d160485bce519c63413bfdac04478ff0a07a&requestUuid=68f14d69-89d1-4dd4-a954-b129250af68a

Aprobación individual

Solicitud

Tipo: POST

https://<url-aprobador>/api/solicitudes

Header

Campo	Tipo	Descripción
Authorization	string	Bearer + token, token de autorización para consumir la ruta en el aprobador.
content-type	string	Etiqueta en la solicitud que indica el tipo de datos que se está enviando.

Parámetros

Campo	Tipo	Descripción
tipoDocumento	string	El tipo de documento que se envía puede ser en formato PDF o JSON
hashDocumento	string	El hash (SHA-256) del documento es una huella digital única del archivo, que permite verificar su integridad al cambiar su contenido.
descripcion	string	Descripción de la operación.
idTramite	uuid	Identificador único de trámite generado por el sistema cliente, se espera un campo del tipo uuidv4.
accessToken	string	El token generado al iniciar sesión a través de Ciudadanía Digital
documento	string	El documento debe enviarse en formato PDF o JSON, codificado en Base64, para garantizar su transmisión segura como texto.

Ejemplo solicitud de aprobación de documentos PDF

curl -L -X POST 'https://<url-aprobador>/api/solicitudes' \
-H 'Authorization: Bearer <token_cliente>' \
-H 'Content-Type: application/json' \
-d '{
  "tipoDocumento": "PDF",
  "hashDocumento": "09181e6f9a43e93602a5d4df6df998460ae02d779a559851d27af61d51ceb47a",
  "descripcion": "Trámite de prueba PDF",
  "idTramite": "bf6807c3-fd3c-49e7-97f7-8344f90e598e",
  "accessToken": "LbXAWFyNpvLRvU0UlCzB6Cp16iRGz_xKCvV4HNnNU-E",
  "documento": "NoZWNrc3VtIC8zRDJEOEU0N0VGRERERjU4OTQxMURCQkY3NEUzNkJBRgoPgpzdGFydHhyZWYKNzM2CiUlRU9GCg==..."
}'

Ejemplo solicitud de aprobación de documentos JSON

curl -L -X POST \
  https://<url-aprobador>/api/solicitudes \
  -H 'Authorization: Bearer <token_cliente>' \
  -H 'Content-Type: application/json' \
  -d '{
      "tipoDocumento": "JSON",
      "hashDocumento": "812c7d89f28613cbdc03976a4f6eebd8bb9ac4db23c5ecf6774c769a9372b01b",
      "descripcion": "Trámite de prueba JSON",
      "idTramite": "9dd95700-cb0d-11e8-a9c0-29fb28bbb654",
      "accessToken": "0UCOcFmVx5REpbeOHzpgf_z4jaduw7gQJWltcLB8Gdk",
      "documento":
        "eyJkb2N1bWVudG8iOiJBcHJvYmFjacOzbiBkZSBkb2N1bWVudG8gZGUgZGVjbGFyYWNpw7NuIiwibnJvLWRvY3VtZW50byI6OTAwMzIsImNvZGlnby1kb2N1bWVudG8iOiJBQzc4LTkwMDMyLTIwMTkiLCJyZW1pdGVudGVzIjpbeyJpdGVtIjoiY3VpZC01NiIsImZlY2hhLWZpcm1hIjoiMjAxOS8xMS8wMSAxNDowMDozMiJ9LHsiaXRlbSI6ImN1aWQtNTYiLCJmZWNoYS1maXJtYSI6IjIwMTkvMTAvMTggMTg6MTA6MjAifV0sImNvbnRlbmlkbyI6Ik1lZGlhbnRlIGxhIHByZXNlbnRlIHNlIGFwcnVlYmEgZWwgZG9jdW1lbnRvIEFDNzgtOTAwMzItMjAxOSB5IHNlIGNvbmZpcm1hIGxhIHJldmlzacOzbiIsIm9ic2VydmFjaW9uIjoiIiwicmV2aXNvciI6eyJpdGVtIjoiYXRydS0xMiIsImZlY2hhLWZpcm1hIjoiMjAxOS8xM
        S8wMyAxNDoxMToyMCJ9fQ==="
    }'

Respuesta

Ejemplo de respuesta exitosa (para PDF y JSON)

HTTP status code: 200

{
  "finalizado": true,
  "mensaje": "Registro creado con éxito.",
  "datos": {
    "link": "https://<url-aprobador>/solicitudes/be54d222-af82-4c8d-8d6e-d503cfc9d0c1"
  }
}

Ejemplo de respuesta errónea

HTTP status code: 412

{
  "finalizado": false,
  "codigo": 412,
  "timestamp": 1738770315,
  "mensaje": "Token inválido, ingrese con su cuenta de Ciudadanía Digital"
}

Notificación backend

Se envía esta notificación directamente al backend del sistema cliente.

Tipo: POST

Url: URL de notificación (backend)

Header

Campo	Tipo	Descripción
Authorization	string	Bearer + token, token de autorización para consumir la ruta, dicho token se registró en la configuración del servicio del sistema cliente.
content-type	string	Etiqueta en la solicitud que indica el tipo de datos que se está enviando.

El cuerpo del mensaje enviado por el servicio de aprobación de ciudadanía digital es el siguiente:

Parámetros enviados

Campos	Tipo	Descripción
aceptado	boolean	Parámetro que indica si el ciudadano aceptó/rechazó la información enviada en la solicitud de aprobación.
introducido	boolean	Parámetro que indica si se ha conseguido introducir el registro en la cadena de bloques exitosamente. En caso de error este campo es false y el sistema cliente deberá volver a enviar la solicitud de aprobación (con campo idTramite distinto).
requestUuid	uuid	Identificador de la solicitud del trámite (el mismo que el sistema cliente envió como idTramite al iniciar el flujo).
codigoOperacion	string	Identificador adicional de solicitud de aprobación. Se envía una cadena vacía en caso de que el campo introducido sea false.
mensaje	string	Mensaje del resultado de la operación, cuando el campo introducido es false en este campo se especifica el error.
transaction_id	string	Código de transacción para comprobaciones en la blockchain. Se envía cadena vacía en caso de que el campo introducido sea false.
fechaHoraSolicitud	string	Fecha y hora en que se realizó la solicitud de firma en formato DD/MM/YYYY HH:mm:ss.SSS
hashDatos	string	Hash del documento enviado en la solicitud.
ci	string	Número de documento del ciudadano que usa el servicio.

Ejemplo

{
  "aceptado": true,
  "introducido": true,
  "requestUuid": "68f14d69-89d1-4dd4-a954-b129250af68a",
  "codigoOperacion": "f8af9ace-0f60-4e27-808f-90b4a054b625",
  "mensaje": "Completado",
  "transaction_id": "f3b6c8b84e7f73a3d39b3e161701d160485bce519c63413bfdac04478ff0a07a",
  "fechaHoraSolicitud": "25/10/2024 15:19:14.000",
  "hashDatos": "0bd46d96d8b68e6040a2d2bd6fd48fbe1d4e60b9f2ac9a5a99ac844d54624a75",
  "ci": "9270816"
}

Redirección frontend

Adicionalmente, el aprobador realiza la redirección al frontend del sistema cliente (URL de redirección FrontEnd) en el cual se envían los siguientes parámetros:

Parámetros enviados

Campos	Tipo	Descripción
estado	string	Indica si el usuario ha confirmado o rechazado la solicitud de aprobación.
finalizado	string	Resultado de la aprobación o rechazo de la solicitud de aprobación, true si se confirmó y realizó, false si no se realizó la aprobación.
mensaje	string	Mensaje del resultado de la operación.
uuidBlockchain	string	UUID Blockchain.
linkVerificacion	string	Enlace de verificación general.
linkVerificacionUnico	string	Enlace de verificación exclusivo para este documento.
transactionCode	string	Identificador único del trámite en la blockchain.
requestUuid	string	Campo requestUuid enviado al iniciar el flujo de aprobación.

Ejemplo

https://<url-cliente>?estado=true&finalizado=true&mensaje=Completado&uuidBlockchain=f8af9ace-0f60-4e27-808f-90b4a054b625&linkVerificacion=<url-aprobador>%2Fhome%2Fverificacion-documentos&linkVerificacionUnico=<url-aprobador>%2Fhome%2Fverificacion%2Ff3b6c8b84e7f73a3d39b3e161701d160485bce519c63413bfdac04478ff0a07a&transactionCode=f3b6c8b84e7f73a3d39b3e161701d160485bce519c63413bfdac04478ff0a07a&requestUuid=68f14d69-89d1-4dd4-a954-b129250af68a