shippinginyectionext
home
shippinginyectionext
Inyección de información de envíos
Descripción general de la API:
Esta Api permite realizar una carga de información referente a uno o varios envíos hacia las aplicaciones de Correos que necesitan consultar o mostrar la trazabilidad de esos envíos (RODA, Minerva, etcétera).
Detalles del API:
- Políticas de seguridad implementadas:
- Información de soporte:
- Consultas generales: dl-mantenimiento-trazabilidad@eviden.com
Uso general de la Api
Esta Api cuenta con un único endpoint (/api2kinbulto) el cual recibe un mensaje JSON con varios campos como pueden ser los datos de la persona emisora del envío, referencias a la(s) oficina(s) de Correos que ha gestionado el envío o los datos de la persona destinataria (ver ejemplo). Ese mensaje es procesado por un microservicio que, si no existe errores en la estructura del mensaje que impida procesar la información, propaga la información a distintas aplicaciones de Trazabilidad de Correos.
Ejemplo del JSON que recibe en la petición:
curl "https://api1.correos.es/support/shippinginyection/api/v1/api2kinbulto
"inputData": {
"addedValues": [
{
"addedValueType": 13,
"deliveryAttempts": 9
},
{
"addedValueType": 16,
"activeAdditionalManagement": false,
"managementTask": "ENTREGA EXCLUSIVA AL DESTINATARIO TITULAR DEL ENVIO. No entregar si no nos presentan DNI original d"
},
{
"addedValueType": 19,
"timeZone": "01"
},
{
"addedValueType": 8,
"returnItemCode": "62215100015030001000119"
}
],
"createdOn": "2023-06-01T15:15:15+01:00",
"deliveryOfficeCode": "12345678",
"shipmentId": "63300020049654101280058",
"collectionolddevice": "S",
"productCode": "X0",
"itemsQuantity": 2,
"customerShipmentCode": "PKJ1510001503000100123P",
"ownerCode": "X",
"createdAt": "22",
"sourceApp": "22",
"partialDelivery": false,
"referenceShipmentCode": "PKJ1510123",
"printedReference": "printedReference_TEST",
"recipient": {
"firstName": "Leonardo",
"LastName1": "Tortuga López",
"customerCode": "123456",
"phoneNumber": "600123456",
"email": "leo@mail.com",
"latitude": 42.45598622792,
"longitude": -2.44503402069,
"address": {
"cityName": "Madrid",
"countryCode": "ESP",
"fullAddress": "Plaza Galápagos, 13, 28080 Madrid, España",
"postalCode": "28080"
},
"doi": {
"code": "99452784"
},
"contact": {
"value": "ALFONSO ALONSO"
}
},
"sender": {
"firstName": "Leonardo",
"LastName1": "Tortuga López",
"customerCode": "123456",
"phoneNumber": "600123456",
"email": "leo@mail.com",
"observations": "Entregar por la mañana",
"address": {
"cityName": "Madrid",
"countryCode": "ESP",
"fullAddress": "Plaza Galápagos, 13, 28080 Madrid, España",
"postalCode": "28080"
},
"doi": {
"code": "99452784"
},
"contact": {
"value": "ALFONSO ALONSO"
}
},
"items": [
{
"createdOn": "2023-06-01T15:15:15+01:00",
"shipmentCreatedOn": "2023-06-01T15:15:15+01:00",
"id": "62215100015030001000119",
"status": {
"id": "G01L010V",
"statusDate": "2023-06-01T15:15:15+01:00",
"reportingNode":"12345678"
},
"itemNumber": 1,
"height": 200,
"wide": 100,
"large": 200,
"weight": 500,
"realVolume": 3,
"itemCertainDate": "2023-06-01T15:15:15+01:00",
"createdAt": "22",
"customerItemCode": "89350124046054104580529",
"referenceOfficeCodeCex": "12345678",
"terminalId": "S1000396D",
"openCode": "12345678",
"committedDateDetail": "2023-06-05T18:00:00+01:00",
"safeDelivery": 0,
"amounts": [
{
"base": 15.5,
"iban": "ES2201822370410201508813",
"total": 30.4,
"type": "065"
}
]
}
]
}De esta manera se crea un flujo cuyo objetivo es conocer toda la información de Trazabilidad de un envío.
Nota: Al ser una Api de inyección de información, sólo recibimos como respuesta un mensaje de Ok si se el proceso de ingesta ha sido exitoso o, por el contrario, del error específico que ha imposibilitado el proceso.
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
Políticas de seguridad implementadas:
- Rate limiting SLA Based
- Cross-Origin Resource Sharing (CORS)Rate limiting SLA based
La política Rate-Limiting Service Level Agreement (SLA) based 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.
Para aplicar esta política, se debe crear un contrato entre la API y una aplicación cliente registrada y elegir qué tipo de SLA (SLA tier) le es aplicada, es decir, la cantidad de solicitudes que una API puede recibir en un tiempo determinado.
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 SLA based se define a la hora de publicar la API en MuleSoft.
Client ID Enforcement
Política de aplicación de ID de cliente que está incluida en el Rate Limiting SLA Based: 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"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.
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](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](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 ("#").