trackpub

trackpub

Recuperación información canónica de la trazabilidad de un(os) envío(s)

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

Descripción general del API:

Esta Api, mediante la matriz estandarizada de eventos (Aplicación Matrix), obtiene la información canónica referente a la trazabilidad de envíos y expediciones.

Detalles del API:

• Políticas de seguridad implementadas:
  • Client ID Enforcement
  • JWT Validation
  • Rate limiting
  • Cross-Origin Resource Sharing (CORS)
• Información de soporte:
  • Consultas generales: dl-mantenimiento-trazabilidad@atos.com

Guía de uso

Las distintas operaciones existentes en este API son:

• Consulta de envío:

Esta Api devuelve, a través del endpoint (/search), toda la trazabilidad de un envío concreto añadiendo, a ese endpoint, el código de envío como parámetro de ruta (search/{shippingCode}).

• Consulta de expedición:

Al invocar al endpoint (/expedition), devuelve la trazabilidad de la expedición consultada, enviando el código de expedición como parámetro de ruta (expedition/{expeditionCode}).

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.

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

Políticas de seguridad implementadas:
    - Client ID Enforcement
    - JWT Validation
    - Rate limiting
    - CORS

Client ID Enforcement

El API espera unas cabeceras con pareja clave/valor en sus peticiones. Todas las llamadas al API deberán incluir estos datos.

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. 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.

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/<organization-name>/<api-name>/api/v1/myResource' \
--header 'client_id: 123456' \
--header 'client_secret: my_secret'

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/<organization-name>/<api-name>/api/v1/myResource' \
--header 'client_id: 123456' \
--header 'client_secret: my_secret' \
--header 'Authorization: Bearer e98b1107-b2ca-43f3-93ed-61d3d89f1f96'

Rate limiting

La política Rate-Limiting permite controlar el tráfico entrante a una API limitando la cantidad de solicitudes que la API puede recibir dentro de un período de tiempo determinado. Cuando se alcanza el límite antes de que expire el tiempo, la política rechaza todas las solicitudes, evitando así cualquier carga adicional.

Además, cada solicitud debe identificarse mediante un ID de cliente y un secreto de cliente (ver Client ID Enforcement).

¿Es necesario incluir algo en la llamada al API con Rate Limiting?: No es necesario realizar ninguna modificación en las llamadas de un API, la restricción de la política Rate limiting se define a la hora de publicar la API en MuleSoft.

CORS

CORS (Cross-Origin Resource Sharing) es un mecanismo mediante el cual una aplicación web puede acceder a recursos definidos en otro dominio. Los navegadores implementan este estándar de forma predeterminada. La política CORS cumple con la recomendación CORS W3C Estándar.

El uso más habitual de esta política es en navegadores (browsers) que detectan llamadas a APIs desde código JavaScript que invocan a una URL que no es del mismo dominio del que descargó la página.

Cuando sus páginas web solicitan datos, el navegador detecta si la solicitud proviene del mismo origen y determina si se aplica el algoritmo CORS. El algoritmo CORS funciona en el servidor web (backend) y en el lado del cliente de la página web que solicitó la información (browser). Si el backend no acepta el origen, el servidor backend responde a la solicitud sin un encabezado específico. De esta forma, el cliente (browser) comprende que el origen de la página no está permitido en ese servidor y no ejecuta la solicitud real.

Los orígenes permitidos desde los que se puede invocar al API se definen en el lado del servidor.

¿Es necesario incluir algo en la llamada al API con CORS?: No es necesario realizar ninguna modificación en las llamadas de un API, los orígenes permitidos en la política CORS se define en el lado del servidor.