¶ Introducción
DocDigital es la plataforma de comunicaciones oficiales del Estado, para el envío y recepción de documentos.
La API Middleware V2 de DocDigital, en adelante API MW, permite a las instituciones integrar su gestor documental con DocDigital, para realizar el despacho y la recepción de comunicaciones oficiales.
El presente documento está dirigido a profesionales del área de tecnologías de la información. Tiene como objetivo facilitar la integración con DocDigital, como complemento a la descripción técnica del API MW.
En la siguiente URL se encuentra la documentación técnica detallada de la API MW:
https://api-doc.digital.gob.cl/api/defs/ con la descripción de los distintos métodos disponibles.
Con el objetivo de facilitar el proceso de integración, está disponible una versión de pruebas de la API MW DocDigital en el ambiente DemoDoc.
¶ Requisitos para integración API MW
1. Contar con una plataforma: Las instituciones que deseen usar la API de DocDigital deberán contar con una plataforma que permita emitir y almacenar documentos en formato PDF firmados con Firma Electrónica Avanzada(FEA). No se admitirán documentos sin FEA. En caso de que su certificado no sea reconocido por docDigital comuníquese con nuestra mesa de servicios aquí.
2. Registrar su Administrador Principal: Asegúrese de que su institución tenga nombrado y registrado un Administrador Principal para DocDigital. Si no lo tiene, entonces el Coordinador de Transformación Digital deberá realizar la gestión en el siguiente enlace .
3. Interlocutor: Para la atención de consultas técnicas sobre la implementación, las instituciones deberán contar con un interlocutor de la institución pública actuando como intermediario entre su proveedor de tecnología y la SGD. En ningún caso la SGD tratará directamente con proveedores de servicios. Dudas y consultas aquí.
4. Revisar la siguiente documentación: Además del presente documento, revise lo siguiente:
- Documentación de la API MW disponible en: https://api-demodoc.digital.gob.cl/api/defs/
3. Obtener credenciales: Debe solicitar, a través de Mesa de Servicios, la habilitación de la entidad para el uso de API. Las credenciales serán notificadas por un agente de Mesa de Servicios, una vez habilitada la institución, el Administrador principal y el Administrador podrán acceder a cambiar (Generar) las credenciales de acceso (Client Id / Client secret)
4. Realice pruebas de integración: debe realizar los siguientes casos de uso como pruebas de integración en su gestor documental.
5. Caso de uso de recepción de documentos.
6. Caso de uso de devolución de documentos.
7. Caso de uso de despacho de documentos: envío efectivo a usuarios destinatarios específicos/oficina de partes y, si corresponde, ingreso de documentos en formato borrador.
8. Habilitación en producción: Para obtener acceso al ambiente productivo es obligatorio que la Secretaría de Gobierno Digital certifique la integración, para ello siga las instrucciones descritas en el documento “Certificación de Integraciones para API DocDigital” y envíe dicho documento con las evidencias solicitadas a través del formulario https://digital.gob.cl/incidencia. Al recibir su documento, nuestro equipo técnico lo revisará para darle una respuesta.
¶ 3. Herramientas sugeridas
Se sugiere el uso de algún software para pruebas de consumo de la API, algunos ejemplos:
¶ 4. URLs Base API MW v2 por ambiente
| Ambiente Certificación(Demo) | Ambiente Productivo |
| https://api-demodoc.digital.gob.cl/api | https://api-doc.digital.gob.cl/api |
¶ 1. Autentificación
Para acceder a cualquiera de los métodos expuestos en en la API MW v2 se requiere la cabecera Authorization Bearer que debe contener el JWT requerido.
Para obtener el token se dispone del siguiente método, donde Client Id y Client secret, son las credenciales de autenticación mencionadas anteriormente(ver aquí).
URL: {{url_base_api_mw}}/oauth/token
Método HTTP: POST
Cabecera Authorization: Basic base64[Client Id:Client secret]
¶ 2. Despacho de comunicación oficial
Permite a una institución, autorizada para el uso de API MW, crear y enviar una comunicación oficial a otra institución a través de docDigital.
El resultado de esta operación es la comunicación despachada a uno o más destinatarios definidos en la solicitud.
URL: {{url_base_api_mw}}/documentos/firmado/ingresar
Método HTTP: POST
Cabecera Authorization: Bearer token
Payload: java
{
"descripcion": "string",
"documento": "string",
"nombre": "string",
"documentos_anexos": [
{
"contenido": "string",
"nombre_archivo": "string",
"tipo": "anexo"
}
],
"es_reservado": false,
"folio": "string",
"id_entidad_creadora": 0,
"listado_id_entidades_destinatarias": [
0
],
"listado_id_usuarios_destinatarios": [
0
],
"materia": "string",
"run_usuario_creador": "string",
"tipo_id": 0
}
|
Respuesta de la operación:
A continuación se detallan algunas consideraciones importantes al respecto de la solicitud de despacho de una comunicación.
¶ 2.1 Archivos
Se permite solo el ingreso de una comunicación cuyo documento principal(documento) es un archivo PDF con firma electrónica avanzada (FEA) reconocida por DocDigital. Los firmantes del documento principal quedarán registrados en la plataforma.
El archivo principal y los anexos adjuntos se deben envíar codificados en Base64.
Se permite además ingresar anexos mediante URL
¶ 2.2 Entidad creadora
La entidad creadora (id_entidad_creadora) corresponde al identificador de la entidad autenticada.
Los datos de la entidad autenticada se pueden obtener a través de del método:
URL: {{url_base_api_mw}}/entidades/token
Método HTTP: GET
Cabecera Authorization: Bearer token
¶ 2.3 Configuración de destinatarios
¶ 2.3.1 Entidades Destinatarias
La comunicación debe tener al menos un destinatario agregado en el listado de entidades destinatarias(listado_id_entidades_destinatarias) .
Puede realizar la búsqueda de identificadores de entidades destinatarias con el método:
URL: {{url_base_api_mw}}/entidades/
Método HTTP: GET
Cabecera Authorization: Bearer token
Respuesta:
Los identificadores de las entidades varían entre el ambiente de prueba y el productivo.No utilizar los identificadores de forma estática.
Nuevos Atributos:
En respuesta base se incorporan los siguientes atributos que permiten paginación de resultados:
total_count: Total de registros encontrados [NUEVO ATRIBUTO]
total_pages: Total de páginas de datos [NUEVO ATRIBUTO]
page: Página de datos retornada [NUEVO ATRIBUTO]
Importante: se incorporan nuevos parámetros pageSize (tamaño de página de datos) y pageNumber (número de página solicitada) para permitir la paginación de resultados.
¶
2.3.2 Usuarios destinatarios
Su uso es opcional, y corresponde al listado de identificadores de usuarios destinatarios de la comunicación (listado_id_usuarios_destinatarios). Estos usuarios deben pertenecer a alguna de las entidades destinatarias de la comunicación. Puede buscar los usuarios utilizando el siguiente método:
URL: {{url_base_api_mw}}/usuarios/
Método HTTP: GET
Cabecera Authorization: Bearer token
Respuesta:
Nuevos Atributos:
En respuesta base se incorporan los siguientes atributos que permiten paginación de resultados:
total_count: Total de registros encontrados [NUEVO ATRIBUTO]
total_pages: Total de páginas de datos [NUEVO ATRIBUTO]
page: Página de datos retornada [NUEVO ATRIBUTO]
Importante: se incorporan nuevos parámetros pageSize (tamaño de página de datos) y pageNumber (número de página solicitada) para permitir la paginación de resultados.
¶ 2.4 Tipo de documento oficial
Corresponde al identificador para la clasificación del documento(tipo_id). Puede obtener el listado disponible en el siguiente método
URL: {{url_base_api_mw}}/tipos/documentos/
Método HTTP: GET
Cabecera Authorization: Bearer token
¶ 3. Obtener comunicaciones recibidas
Para obtener los documentos recibidos por la entidad asociada al token de autenticación, es decir, donde la entidad es destinataria de la comunicación utilice el siguiente método.
URL: {{url_base_api_mw}}/documentos/recibidos
Método HTTP: GET
Cabecera Authorization: Bearer token
Respuesta: Ver modelo detalle modelo DocumentoResponse en documentación swagger. Se incorporan nuevos atributos
Nuevos Atributos:
En respuesta base se incorporan los siguientes atributos que permiten paginación de resultados:
total_count: Total de registros encontrados [NUEVO ATRIBUTO]
total_pages: Total de páginas de datos [NUEVO ATRIBUTO]
page: Página de datos retornada [NUEVO ATRIBUTO]
En documentoPrincipal:
id: Identificador archivo principal [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo. [NUEVO ATRIBUTO]
metadata_version:Versión de la metadata del documento [NUEVO ATRIBUTO]
atributos_adicionales: Atributos adicionales del documento [NUEVO ATRIBUTO]
En documentosAnexos:
id: Identificador archivo anexo [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo [NUEVO ATRIBUTO]
En infoVisaciones:
tipo_descripcion: Descripción tipo de visación
En info_firmas;
pagina_numero: Página de firma del documento
tipo_tramitacion: Tipo de tramitación del documento [NUEVO ATRIBUTO]
estado_tramitacion: Estado de la tramitación [NUEVO ATRIBUTO]
Parámetros:
Importante: para obtener los documentos pendientes de recepción (sin acuse de recibo o rechazo) se debe enviar el parámetro notificado con valor false
Otros filtros se encuentran en la documentación de la API MW.
¶ 5. Acuse de recibido y Rechazo de una comunicación
Para completar la recepción de una comunicación pendiente de forma positiva(acuse de recibido) se dispone del siguiente método:
URL: {{url_base_api_mw}}/documentos/recibidos/{id}/acusorecibo
Método HTTP: PUT
Cabecera Authorization: Bearer token
Path param:
- id: Identificador del documento a recepcionar(obligatorio)
Query param:
- entidadDestinataria: Identificador de entidad destinataria(opcional)
Para completar la recepción de una comunicación pendiente de forma negativa(rechazo) se dispone del siguiente método.:
URL: {{url_base_api_mw}}/documentos/recibidos/{id}/devolver
Método HTTP: PUT
Cabecera Authorization: Bearer token
Path param:
- id: Identificador del documento a recepcionar(obligatorio)
Payload:
- entidadDestinataria: Identificador de entidad destinataria(opcional)
- Motivo de rechazo del documento. String Entre 3 y 255 caracteres
¶ 6. Obtener detalle de una comunicación
El siguiente método permite obtener el detalle de una comunicación mediante su identificador, entregando como resultado destinatarios, firmantes, visadores, información del documento principal y anexos entre otros.
URL: {{url_base_api_mw}}/documentos/{id}
Método HTTP: GET
Cabecera Authorization: Bearer token
Path param:
- id: Identificador del documento
Respuesta: Ver modelo detalle modelo DocumentoResponse en documentación swagger. Se incorporan nuevos atributos
Nuevos Atributos:
En documentoPrincipal:
id: Identificador archivo principal [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo. [NUEVO ATRIBUTO]
metadata_version:Versión de la metadata del documento [NUEVO ATRIBUTO]
atributos_adicionales: Atributos adicionales del documento [NUEVO ATRIBUTO]
En documentosAnexos:
id: Identificador archivo anexo [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo [NUEVO ATRIBUTO]
En infoVisaciones:
tipo_descripcion: Descripción tipo de visación
En info_firmas;
pagina_numero: Página de firma del documento
tipo_tramitacion: Tipo de tramitación del documento [NUEVO ATRIBUTO]
estado_tramitacion: Estado de la tramitación [NUEVO ATRIBUTO]
¶ 7. Descargar archivos de una comunicación
El siguiente método permite obtener el contenido(Bytes) del archivo de una comunicación mediante su identificador.
URL: {{url_base_api_mw}}/documentos/{id}/archivo/descargar
Método HTTP: GET
Cabecera Authorization: Bearer token
Path param:
- id: Identificador del documento
Query param:
- archivo_id: Identificador único del archivo(UUID)
¶ 8. Atributos adicionales a la comunicación
Permite actualizar atributos adicionales del documento
URL: {{url_base_api_mw}}/documentos/{id}/atributos-adicionales
Método HTTP: POST
Cabecera Authorization: Bearer token
Ejemplo: java
{
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}¶ 9. Obtener comunicaciones despachadas
Método que permite obtener las comunicaciones enviadas por la entidad asociada el token de autenticación
URL: {{url_base_api_mw}}/documentos/creados/enviados
Método HTTP: GET
Cabecera Authorization: Bearer token
Respuesta: Ver modelo detalle modelo DocumentoResponse en documentación swagger. Se incorporan nuevos atributos
Nuevos Atributos:
En respuesta base se incorporan los siguientes atributos que permiten paginación de resultados:
total_count: Total de registros encontrados [NUEVO ATRIBUTO]
total_pages: Total de páginas de datos [NUEVO ATRIBUTO]
page: Página de datos retornada [NUEVO ATRIBUTO]
En documentoPrincipal:
id: Identificador archivo principal [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo. [NUEVO ATRIBUTO]
metadata_version:Versión de la metadata del documento [NUEVO ATRIBUTO]
atributos_adicionales: Atributos adicionales del documento [NUEVO ATRIBUTO]
En documentosAnexos:
id: Identificador archivo anexo [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo [NUEVO ATRIBUTO]
En infoVisaciones:
tipo_descripcion: Descripción tipo de visación
En info_firmas;
pagina_numero: Página de firma del documento
tipo_tramitacion: Tipo de tramitación del documento [NUEVO ATRIBUTO]
estado_tramitacion: Estado de la tramitación [NUEVO ATRIBUTO]
Parámetros:
¶ 9. Búsqueda de comunicaciones
Método que permite buscar comunicaciones mediante filtros de búsqueda
URL: {{url_base_api_mw}}/documentos/buscar
Método HTTP: GET
Cabecera Authorization: Bearer token
Respuesta: Ver modelo detalle modelo DocumentoResponse en documentación swagger. Se incorporan nuevos atributos
Nuevos Atributos:
En respuesta base se incorporan los siguientes atributos que permiten paginación de resultados:
total_count: Total de registros encontrados [NUEVO ATRIBUTO]
total_pages: Total de páginas de datos [NUEVO ATRIBUTO]
page: Página de datos retornada [NUEVO ATRIBUTO]
En documentoPrincipal:
id: Identificador archivo principal [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo. [NUEVO ATRIBUTO]
metadata_version:Versión de la metadata del documento [NUEVO ATRIBUTO]
atributos_adicionales: Atributos adicionales del documento [NUEVO ATRIBUTO]
En documentosAnexos:
id: Identificador archivo anexo [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo [NUEVO ATRIBUTO]
En infoVisaciones:
tipo_descripcion: Descripción tipo de visación
En info_firmas;
pagina_numero: Página de firma del documento
tipo_tramitacion: Tipo de tramitación del documento [NUEVO ATRIBUTO]
estado_tramitacion: Estado de la tramitación [NUEVO ATRIBUTO]
Parámetros:
¶ 10. Obtener comunicaciones creadas
Método que permite obtener las comunicaciones creadas por la entidad asociada el token de autenticación
URL: {{url_base_api_mw}}/documentos/creados
Método HTTP: GET
Cabecera Authorization: Bearer token
Respuesta: Ver modelo detalle modelo DocumentoResponse en documentación swagger. Se incorporan nuevos atributos
Nuevos Atributos:
En respuesta base se incorporan los siguientes atributos que permiten paginación de resultados:
total_count: Total de registros encontrados [NUEVO ATRIBUTO]
total_pages: Total de páginas de datos [NUEVO ATRIBUTO]
page: Página de datos retornada [NUEVO ATRIBUTO]
En documentoPrincipal:
id: Identificador archivo principal [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo. [NUEVO ATRIBUTO]
metadata_version:Versión de la metadata del documento [NUEVO ATRIBUTO]
atributos_adicionales: Atributos adicionales del documento [NUEVO ATRIBUTO]
En documentosAnexos:
id: Identificador archivo anexo [NUEVO ATRIBUTO]
url_descarga: Url de descarga del archivo [NUEVO ATRIBUTO]
En infoVisaciones:
tipo_descripcion: Descripción tipo de visación
En info_firmas;
pagina_numero: Página de firma del documento
tipo_tramitacion: Tipo de tramitación del documento [NUEVO ATRIBUTO]
estado_tramitacion: Estado de la tramitación [NUEVO ATRIBUTO]
Parámetros:
¶ 11. Listado de endpoints deprecados (obsoletos)
Los métodos listados a continuación se encuentran obsoletos y su uso no está soportado para nuevas integraciones.
- {{url_base_api_mw}}/layouts/
- {{url_base_api_mw}}/documentos/firmado/borrador
- {{url_base_api_mw}}/documentos/{id}/reservado/archivo
- {{url_base_api_mw}}/documentos/{id}/archivo