expclidocs

1.0.x
(0 reviews)
API que permite a usuarios externos autorizados consultar documentos digitales de envíos (Pruebas de Entrega Electrónica y Firmas) de Correos con validación de permisos y autenticación JWT.

expclidocs API

API de Experiencia para exponer a través de MuleSoft el servicio de consulta de Pruebas de Entrega Electrónica (PEEs) y PODs (Proof of Delivery) a usuarios externos de Correos.

Descripción general

La API expclidocs permite a usuarios externos autorizados consultar documentación digital de envíos de Correos, específicamente:

  • PEE (Prueba de Entrega Electrónica): Documentos de certificación electrónica de entrega en formato PDF o XML
  • POD (Proof of Delivery): Documentos de firma/entrega del destinatario en formato JPG o XML

La API valida automáticamente los permisos del usuario contra el sistema de relaciones (MdR) antes de permitir el acceso a los documentos, garantizando que solo usuarios autorizados puedan consultar envíos asociados a sus detallables o etiquetadores.

Características del API

  • Políticas de seguridad requeridas:
    • Rate Limiting - SLA Based (Client ID y control de límites)
    • Validación JWT
    • Cross-Origin Resource Sharing (CORS)
  • Endpoints disponibles:
    • GET /pee/{shippingCode} - Consulta de Pruebas de Entrega Electrónica
    • GET /pod/{shippingCode} - Consulta de PODs (Proof of Delivery)
  • Formatos soportados:
    • PEE: pdf, xml
    • POD: jpg, xml
  • Validaciones automáticas:
    • Permisos de usuario en MdR (perfiles PEEPDF, PEEXML, PODJPG, PODXML)
    • Relación del código de envío con detallable/etiquetador del usuario
  • Información de soporte:

Nota: En esta documentación se incluyen ejemplos ilustrativos usando curl. Esto no significa que esté obligado a usar curl, para utilizar el API puede emplear cualquier programa que permita realizar peticiones HTTP.

Sobre las políticas de seguridad requeridas

Antes de poder usar el API lo primero será conseguir las credenciales de acceso necesarias para cumplir con las políticas de seguridad requeridas.

Rate Limiting - SLA Based

El API está protegido por una política de limitación de velocidad basada en SLA que combina validación de Client ID con control de límites de llamadas. Todas las llamadas al API deberán incluir las credenciales necesarias.

CabeceraValor
client_idSuministrado una vez solicitado el acceso al API
client_secretSuministrado una vez solicitado el acceso al API

Antes de que a una aplicación cliente se le permita consumir una API protegida con esta política se debe solicitar acceso a la API.

Desde el propio Exchange, o el portal de acceso a las APIs que se esté usando, existirá una opción de Solicitar acceso o Request access. Si no ve esa opción quiere decir que esa API no admite solicitudes de acceso y deberá ponerse en contacto con el equipo de soporte del 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 y los límites de SLA asociados a su contrato.

Control de SLA: Esta política también controla el número máximo de llamadas permitidas dentro de un período de tiempo determinado, de acuerdo con el nivel de servicio (SLA) contratado. Si se exceden los límites, recibirá un error 429 (Too Many Requests).

Las credenciales se adjuntarán como cabeceras de todas las invocaciones al API tal como muestra el siguiente ejemplo usando curl:

curl --location 'https://api1.correos.es/digital-services/expclidocs/api/v1/pee/ZZ00000000000?format=pdf' \
--header 'client_id: 123456' \
--header 'client_secret: my_secret'
Dudas frecuentes
¿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

El API espera un token JWT para poder aceptar la llamada (puede leer información general sobre tokens JWT en https://jwt.io/introduction)

Todas las llamadas al API deberán incluir el token JWT para poder usar el API.

Para realizar la llamada se deberá introducir la cabecera Authorization con el valor Bearer seguido del token (siendo el token una cadena de caracteres del estilo de la que se muestra en el ejemplo)

curl --location 'https://api1.correos.es/digital-services/expclidocs/api/v1/pee/ZZ00000000000?format=pdf' \
--header 'client_id: 123456' \
--header 'client_secret: my_secret' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
Dudas frecuentes
¿Cómo obtener el token JWT?El token JWT es generado por CorreosId, el sistema de identidad centralizado de Correos. Ver instrucciones debajo.

Para obtener el token JWT:

  1. Regístrate en CorreosId: Accede a https://identidad.correos.es
  2. Crea credenciales OAuth: Crea tus credenciales de aplicación y obtendrás un client_id y client_secret
  3. Solicita el token: Realiza la siguiente llamada:
curl --location 'https://apioauthcid.correos.es/api/authorize/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<tu-client-id>' \
  --data-urlencode 'client_secret=<tu-client-secret>' \
  --data-urlencode 'scope=ECD'

Luego: Incluye el token recibido en la cabecera Authorization: Bearer <token> en tus llamadas al API

Cross-Origin Resource Sharing (CORS)

El API implementa la política Cross-Origin Resource Sharing (CORS) para controlar qué orígenes (dominios) tienen permiso para acceder a los recursos desde navegadores web.

¿Por qué es importante CORS?

Dado que esta API está diseñada para ser consumida por aplicaciones cliente externas, CORS proporciona un mecanismo de seguridad que:

  • Permite que solo dominios autorizados realicen peticiones directas desde el navegador
  • Protege contra accesos no autorizados desde orígenes desconocidos
  • Mantiene la integridad de los datos al restringir quién puede hacer peticiones

Dominios permitidos:

Los orígenes (dominios) autorizados se configuran a nivel de contrato durante el proceso de aprobación de acceso. Si su aplicación necesita acceder desde un dominio específico, incluya esa información en su solicitud de acceso.

Ejemplo de petición desde navegador:

fetch('https://api1.correos.es/digital-services/expclidocs/api/v1/pee/ZZ00000000000?format=pdf', {
  method: 'GET',
  headers: {
    'client_id': '123456',
    'client_secret': 'my_secret',
    'Authorization': 'Bearer <token>'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Si la petición proviene de un origen no autorizado, recibirá un error CORS del navegador indicando que el acceso está bloqueado.

Solución: Si necesita acceder desde un dominio no autorizado, contacte con el equipo de soporte para solicitar que se añada a la lista de orígenes permitidos.

Niveles de uso

El API expclidocs está diseñado para proporcionar acceso controlado a documentación de envíos a usuarios externos autorizados.

Acceso bajo demanda (aprobación previa requerida)

El acceso al API requiere:

  1. Solicitud de acceso a través del portal Exchange de MuleSoft
  2. Aprobación del propietario del API que verificará la legitimidad de la solicitud
  3. Asignación de perfiles en MdR correspondientes a los tipos de documentos que el usuario podrá consultar:
    • PEEPDF - Permite consultar PEEs en formato PDF
    • PEEXML - Permite consultar PEEs en formato XML
    • PODJPG - Permite consultar PODs en formato JPG
    • PODXML - Permite consultar PODs en formato XML

El usuario debe tener el perfil adecuado para el formato solicitado y el código de envío debe estar asociado a su detallable o etiquetador en el sistema de relaciones (MdR).

Limitaciones de uso

El API está sujeto a las políticas de uso estándar de la plataforma Anypoint. Los límites específicos de llamadas se configuran a nivel de contrato durante el proceso de aprobación según las necesidades del cliente.

En caso de necesitar límites superiores o acceso a volúmenes mayores de consultas, contacte con el equipo de soporte para evaluar su caso.

Guía de uso

Una vez se tengan las credenciales necesarias (client_id, client_secret, token JWT) y los permisos adecuados configurados en MdR, ya podemos realizar llamadas a los distintos endpoints del API.

Consultar PEE (Prueba de Entrega Electrónica)

Las Pruebas de Entrega Electrónica son documentos de certificación de envíos que pueden consultarse en formato PDF o XML.

Solicitar PEE en formato PDF
curl --location 'https://api1.correos.es/digital-services/expclidocs/api/v1/pee/ZZ000000000000000000?format=pdf' \
     --header 'client_id: <my-id>' \
     --header 'client_secret: <my-secret>' \
     --header 'Authorization: Bearer <token>'

Ejemplo de respuesta exitosa (200 OK):

{
  "shippingCode": "ZZ000000000000000000",
  "format": "pdf",
  "content": "JVBERi0xLjQKJcOow6AK...",
  "metadata": {
    "contentType": "application/pdf",
    "shippingCodeInternal": "AA000000000000000000000",
    "sizeBytes": 6658,
    "registrationDate": "2023-11-29T17:08:10Z",
    "digitizationDate": "2023-11-29T17:08:10Z",
    "secureVerificationCode": "170126298343504c4292e627d67",
    "customerCode": "00000000",
    "provinceCode": "28"
  }
}

El campo content contiene el documento en formato Base64 que puede ser decodificado para obtener el PDF original.

Solicitar PEE en formato XML
curl --location 'https://api1.correos.es/digital-services/expclidocs/api/v1/pee/ZZ000000000000000000?format=xml' \
     --header 'client_id: <my-id>' \
     --header 'client_secret: <my-secret>' \
     --header 'Authorization: Bearer <token>'

Ejemplo de respuesta exitosa (200 OK):

{
  "shippingCode": "ZZ000000000000000000",
  "format": "xml",
  "content": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...",
  "metadata": {
    "contentType": "text/xml",
    "shippingCodeInternal": "AA000000000000000000000",
    "sizeBytes": 6658,
    "registrationDate": "2023-11-29T17:08:10Z",
    "digitizationDate": "2023-11-29T17:08:10Z",
    "secureVerificationCode": "170126298343504c4292e627d67",
    "customerCode": "00000000",
    "provinceCode": "28"
  }
}

Consultar POD (Proof of Delivery)

Los PODs son documentos de firma/entrega que pueden existir en múltiples formatos (JPG o XML). Un mismo envío puede tener varios documentos POD asociados.

Solicitar PODs en formato JPG
curl --location 'https://api1.correos.es/digital-services/expclidocs/api/v1/pod/ZZ0000000000000000000000?format=jpg' \
     --header 'client_id: <my-id>' \
     --header 'client_secret: <my-secret>' \
     --header 'Authorization: Bearer <token>'

Ejemplo de respuesta exitosa (200 OK) con múltiples documentos:

{
  "shippingCode": "ZZ0000000000000000000000",
  "format": "jpg",
  "documents": [
    {
      "content": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
      "metadata": {
        "contentType": "image/jpeg",
        "sizeBytes": 111933,
        "registrationDate": "2023-06-21T12:34:19Z",
        "digitizationDate": "2016-12-14T09:35:13Z",
        "signed": "1",
        "unitCode": "3122494",
        "provinceCode": "31"
      }
    },
    {
      "content": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
      "metadata": {
        "contentType": "image/jpeg",
        "sizeBytes": 98765,
        "registrationDate": "2023-06-20T10:15:30Z",
        "digitizationDate": "2016-12-13T08:20:00Z",
        "signed": "1",
        "unitCode": "3122494",
        "provinceCode": "31"
      }
    }
  ]
}

Nota: A diferencia de las PEE, los PODs devuelven un array documents que puede contener uno o más documentos.

Solicitar PODs en formato XML
curl --location 'https://api1.correos.es/digital-services/expclidocs/api/v1/pod/ZZ0000000000000000000000?format=xml' \
     --header 'client_id: <my-id>' \
     --header 'client_secret: <my-secret>' \
     --header 'Authorization: Bearer <token>'

Ejemplo de respuesta exitosa (200 OK):

{
  "shippingCode": "ZZ0000000000000000000000",
  "format": "xml",
  "documents": [
    {
      "content": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...",
      "metadata": {
        "contentType": "text/xml-signature",
        "sizeBytes": 111933,
        "registrationDate": "2023-06-21T12:34:19Z",
        "digitizationDate": "2016-12-14T09:35:13Z",
        "signed": "1",
        "unitCode": "3122494",
        "provinceCode": "31"
      }
    }
  ]
}

Descripción de implementación

La API expclidocs actúa como capa de experiencia que orquesta la validación de permisos y la búsqueda de documentos en sistemas internos de Correos, proporcionando una interfaz simplificada y segura para usuarios externos.

Flujo de ejecución

  ┌──────────────────────┐         ┌──────────────────────┐       ┌──────────────────────┐
  │                      │         │                      │       │                      │
  │   Aplicación         │         │   expclidocs API     │       │   E-Documento        │
  │   Cliente Externa    ├────1───►│   (MuleSoft)         ├───2──►│   Búsqueda PEE/POD   │
  │                      │         │   Validación         │       │                      │
  │                      │         │   de parámetros      │◄──3───┤                      │
  │                      │         │                      │       └──────────────────────┘
  │                      │         │         │            │
  │                      │         │         │            │       ┌──────────────────────┐
  │                      │         │         │            │       │                      │
  │                      │         │         └────────────│───4──►│   MdR (Relaciones)   │
  │                      │         │                      │       │   Validación         │
  │                      │         │                      │       │   Permisos           │
  │                      │         │                      │◄──5───┤                      │
  │                      │◄────6───┤                      │       └──────────────────────┘
  │                      │         │                      │
  │                      │         │         │            │       ┌──────────────────────┐
  │                      │         │         │            │       │                      │
  │                      │         │         └────────────│───7──►│   PostgreSQL         │
  │                      │         │                      │       │   Auditoría          │
  └──────────────────────┘         └──────────────────────┘       └──────────────────────┘

Pasos del flujo:

  1. Solicitud del cliente: La aplicación externa realiza una petición GET con credenciales y token JWT
  2. Validación de parámetros: Se valida que los parámetros de entrada (código de envío y formato) sean correctos
  3. Búsqueda en E-Documento: Se busca el documento en el sistema de gestión documental
  4. Validación de permisos en MdR: Una vez encontrado el documento, el API consulta el sistema de relaciones para verificar:
    • El usuario tiene el perfil adecuado (PEEPDF, PEEXML, PODJPG, PODXML) para el formato solicitado
    • El código de envío está asociado a su detallable o etiquetador
  5. Control de acceso: Si el usuario no tiene permisos, se rechaza la solicitud con error 403
  6. Preparación de respuesta: El API formatea el documento en Base64 con metadatos adicionales
  7. Respuesta al cliente: Se devuelve el documento al cliente con código 200 OK
  8. Auditoría: Se registra la operación en base de datos PostgreSQL para trazabilidad

Integración con sistemas backend

La API se integra con los siguientes sistemas internos:

  • MdR (Relaciones): Sistema de gestión de relaciones entre usuarios, detallables, etiquetadores y perfiles
  • E-Documento: Sistema de gestión documental que almacena PEEs y PODs digitalizados
  • PostgreSQL: Base de datos para auditoría de todas las consultas realizadas

Todos los sistemas están protegidos dentro de la red interna y solo son accesibles a través de esta API desde el exterior.

Códigos de error

La API utiliza códigos de estado HTTP estándar y devuelve información detallada en caso de error.

400 - Bad Request

Causa: Parámetros de entrada incorrectos o faltantes.

PEE

  • Formato no válido:
{
  "code": "400",
  "message": "Bad Request",
  "moreInformation": {
    "description": "The 'format' parameter must be 'pdf' or 'xml'",
    "link": "www.correos.es"
  }
}
  • Código de envío ausente:
{
  "code": "400",
  "message": "Bad Request",
  "moreInformation": {
    "description": "The 'shippingcode' parameter is required",
    "link": "www.correos.es"
  }
}

POD

  • Formato no válido:
{
  "code": "400",
  "message": "Bad Request",
  "moreInformation": {
    "description": "The 'format' parameter must be 'jpg' or 'xml'",
    "link": "www.correos.es"
  }
}
  • Código de envío ausente:
{
  "code": "400",
  "message": "Bad Request",
  "moreInformation": {
    "description": "The 'shippingcode' parameter is required",
    "link": "www.correos.es"
  }
}

401 - Unauthorized

Causa: Problemas de autenticación con JWT o Client ID

Token JWT inválido:

{
  "error": "Invalid token."
}

Client ID inválido:

{
  "error": "Authentication denied."
}

Solución: Verifique que su token JWT no ha expirado y que sus credenciales client_id/client_secret son correctas.

403 - Forbidden

Causa: El usuario no tiene permisos suficientes para acceder al documento.

PEE

  • Error en MdR:
{
  "code": "403",
  "message": "Forbidden",
  "moreInformation": {
    "description": "User profile not authorized for this operation",
    "link": "www.correos.es"
  }
}
  • Sin permisos sobre el envío:
{
  "code": "403",
  "message": "Forbidden",
  "moreInformation": {
    "description": "User is not authorized to access this shipping code",
    "link": "www.correos.es"
  }
}

POD

  • Error en MdR:
{
  "code": "403",
  "message": "Forbidden",
  "moreInformation": {
    "description": "User profile not authorized for this operation",
    "link": "www.correos.es"
  }
}
  • Sin permisos sobre los documentos POD:
{
  "code": "403",
  "message": "Forbidden",
  "moreInformation": {
    "description": "User does not have permissions to access the requested POD documents",
    "link": "www.correos.es"
  }
}

Solución: Contacte con el administrador del sistema para verificar que tiene los perfiles adecuados asignados en MdR y que el código de envío/documentos están asociados a su cuenta.

404 - Not Found

Causa: El documento solicitado no existe, ha sido dado de baja o no hay documentos en el formato solicitado.

PEE

  • No encontrado:
{
  "code": "404",
  "message": "Resource not found",
  "moreInformation": {
    "description": "The requested PEE was not found",
    "link": "www.correos.es"
  }
}
  • PEE dado de baja:
{
  "code": "404",
  "message": "Resource not found",
  "moreInformation": {
    "description": "The requested PEE has been disabled and is not available",
    "link": "www.correos.es"
  }
}

POD

  • No hay PODs para el envío:
{
  "code": "404",
  "message": "Resource not found",
  "moreInformation": {
    "description": "No PODs found for the requested shipping code",
    "link": "www.correos.es"
  }
}
  • No hay PODs en el formato solicitado:
{
  "code": "404",
  "message": "Resource not found",
  "moreInformation": {
    "description": "No POD documents found in the requested format",
    "link": "www.correos.es"
  }
}

503 - Service Unavailable

Causa: Uno de los sistemas backend (MdR o E-Documento) no está disponible temporalmente

Sistema MdR no disponible:

{
  "code": "503",
  "message": "Service Unavailable",
  "moreInformation": {
    "description": "Unable to access the relations system (MdR) to validate user permissions",
    "link": "www.correos.es"
  }
}

Sistema E-Documento no disponible:

{
  "code": "503",
  "message": "Service Unavailable",
  "moreInformation": {
    "description": "Unable to access the document management system to search for the PEE document",
    "link": "www.correos.es"
  }
}

Solución: Reintente la operación después de unos minutos. Si el problema persiste, contacte con el equipo de soporte.

500 - Internal Server Error

Causa: Error interno no controlado en el procesamiento

{
  "code": "500",
  "message": "Internal Server Error",
  "moreInformation": {
    "description": "Internal error processing the request",
    "link": "www.correos.es"
  }
}

Solución: Contacte con el equipo de soporte proporcionando detalles de la solicitud y el timestamp del error.

Para más información o soporte técnico, contacte con: mantenimiento.edocumento@correos.com

Nota: Gráfico de implementación realizado con https://asciiflow.com

Reviews