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 ("#").