documentmanager

documentmanager

Framework de Servicios de Gestión Documental Corporativo

• Descripción general del API
• Aspectos generales de las APIs de Correos
  • Solicitud de acceso al API
  • Niveles de uso
  • Políticas de seguridad
  • Introducción uso de API REST

Descripción general del API

Framework de Servicios de Gestión Documental Corporativo las aplicaciones de gestión en Correos que necesitan trabajar con documetnos, dispondrán de una arquitectura de integración para acceder al repositorio documental Corporativo.

Detalles del API:

• Políticas de seguridad implementadas:
  • Cross-Origin Resource Sharing
  • Validación JWT
  • Rate Limiting - SLA Based
• Información de soporte:
  • Consultas generales: mantenimiento.edocumento@correos.com

Uso general del API

Operaciones en Ágora

Estas son las operaciones en Ágora más importantes:

Crear un documento

Un ejemplo de la llamada para la creación de un documento:

curl --location 'https://api1.correos.es/digital-services/documentmanager/api/v1/documents/create' \
--form 'requestXml=@"FICHEROS ADJUNTOS/CORREOS/AGORA/FW/entradadatos_TESORERIA_HTML.xml"' \
--form 'content=@"FICHEROS ADJUNTOS/CORREOS/AGORA/FW/html-sample.html"'

Visualizar un documento

Un ejemplo de la llamada para la visualización de un documento:

curl --location 'https://api1.correos.es/digital-services/documentmanager/api/v1/documents/A355D4/content?documentSubType=Curriculum&state=Definitivo&responsibleUnit=Tecnologia&accessLevel=Publico&name=prueba.pdf' \

Operaciones en E-Documento

Buscar una Prueba de Entrega Electrónica

curl --location 'https://api1.correos.es/digital-services/documentmanager/api/v1/edoc/search-unique-content?shippingCode=AA53000924111600040382N&associatedShippingCode=PS2ALS0700000140108001P&type=correos_pentrega_electronica&generatePDF=true' \

Buscar un documento de Certificación Electrónica

curl --location 'https://api1.correos.es/digital-services/documentmanager/api/v1/edoc/search-unique-unified-content?shippingCode=AA92840294060003467356H&associatedShippingCode=NB994566637231020748682&type=correos_certificacion_electronic' \

Buscar documentos de tipo POD

curl --location 'https://api1.correos.es/digital-services/documentmanager/api/v1/edoc/search-pod?shippingCode=CDPRUPAPPDA2018050902' \

Aspectos generales de las APIs de Correos

Nota: Se incluyen ejemplos ilustrativos usando curl. Esto no significa que esté obligado a usar curl, cualquier cliente que pueda realizar peticiones HTTP serviría.

Solicitud de acceso al API

Desde el propio Exchange, o el portal de acceso a las APIs que se esté usando, existirá una opción de Solicitar acceso. Si no ve esa opción quiere decir que esa API no admite solicitudes de acceso.

Antes de que a una aplicación cliente se le permita consumir una API se debe solicitar acceso a la API. Una vez solicitado el acceso, la petición pasa por un flujo de aprobación. Una vez finalizado ese flujo, y aprobado por el propietario del API, recibirá un email con las credenciales de acceso (si estuviesen definidas).

Niveles de uso

Los APIS pueden tener definidos diferentes niveles de uso. Al solicitar acceso a un API verá indicaciones del nivel de uso (SLA) que ofrece el API. Tenga en cuenta que algunos niveles de uso pueden tener un coste asociado.

Para conocer los niveles de uso que aplican a su API puede revisar la Descripción general del API

Políticas de seguridad

Existen varias políticas de seguridad que puede aplicarse a las APIS. Un API ofrecido por Correos puede llevar ninguna, una o varias de estas políticas.

Para conocer las políticas de seguridad que aplican a su API puede revisar la Descripción general del API

Sin política de seguridad

Un API puede haber sido definido para que no requiera autorización (APIs de uso interno o de uso abierto) por lo que no hay necesidade de incluir ningún aspecto adicional en las llamadas al API.

curl "http://example.restapi.es/myResource"

Client ID Enforcement

Política de aplicación de ID de cliente: El API espera unas cabeceras con pareja clave / valor en sus peticiones.

Antes de que a una aplicación cliente se le permita consumir una API protegida esta política, se debe solicitar acceso a la API. Después de que exista un contrato aprobado entre la aplicación cliente y la API, cada solicitud debe incluir las credenciales de la aplicación cliente de conformidad con la configuración de la política.

Las credenciales irán como cabeceras de la petición tal como muestra el siguiente ejemplo de petición usando curl:

curl "http://example.restapi.es/myResource" -H "client_id:1234" -H "client_secret:abcd"

¿Es posible consultar client_id y client_secret si se me han olvidado o los he perdido?: Desde Exchange, o el portal de acceso a las APIs que se esté usando, puede consultar Mis Aplicaciones y ahí puede encontrar las credenciales de acceso.

Validación JWT

Política de seguridad capaz da validar tanto tokens JWT generados por ISAM como tokens generados por CorreosID (producto de seguridad de Correos).

Todas las llamadas al API deberán incluir el token JWT (Json Web Token) para poder usar el API.

Para realizar la llamada se deberá introducir la cabecera Authorization con el valor Bearer seguido del token.

curl "http://example.restapi.es/myResource" -H "Authorization: Bearer {token}"

¿Cómo obtener el token JWT?: La obtención del token JWT será específico del sistema que lo proporciona (por ejemplo CorreosID) y deberá haber proporcionado documentación al respecto para hacer las llamadas a sus APIs para obtener un token válido. Por favor consulte con su contacto en Correos para obtener documentación relativa a CorreosID.

Rate Limiting - SLA Based

Supervisa el acceso a una API definiendo el número máximo de solicitudes procesadas dentro de un período de tiempo, según los SLA.

Cada solicitud debe identificarse mediante un client_id y un client_secret.

curl "http://example.restapi.es/myResource" -H "client_id:1234" -H "client_secret:abcd"

Introducción uso de API REST

REST APIs utilizan Uniform Resource Identifiers (URI) para direccionar los recursos. Los diseños de URIs bien hechos comunicarían claramente el recurso de la API, como por ejemplo:

http://example.restapi.es/france/paris/louvre/leonardo-da-vinci/mona-lisa

Un diseño incorrecto de los URIs daría un recurso mucho más difícil de entender como:

http://example.restapi.es/68dd0-a9d3-11e0-9f1c-0800200c9a66

Formato de URI

La sintaxis del URI genérico se define como sigue:

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

• scheme: El esquema identifica el protocolo de acceso a los recursos (http, https)
• authority: Es el elemento jerárquico que identifica la autoridad de nomenclatura, está formado por el nombre de host y el puerto.
• path: La ruta es la parte más específica del URI que indica la ruta o ubicación del recurso dentro del servidor. El camino puede incluir jerarquías profundas y a menudo refleja la estructura organizativa de los recursos..
• query: Es un componente opcional que se incluye después de la ruta de acceso y tiene una estructura no jerárquica, y proporciona una cadena de información que el recurso puede utilizar para algún propósito, por ejemplo, para buscar parámetros o datos a procesar. La consulta suele ser una cadena de pares de parámetros y valores ("argumento=valor"). Los argumentos junto con los valores se separan entre sí con un ampersand ("&").
• fragment: El fragmento es un componente opcional que permite identificar una parte del recurso principal, o la vista de una representación del mismo. El comienzo de este componente se indica con el carácter de libra ("#").