Skip to content
OMS Documentation

Troncales

Conceptos Básicos

Consideramos que hay un paralelismo directo entre lo que hoy en la API son los Step (Tramos), con lo que se utiliza como hoja de ruta de VKM, es decir, un elemento asociado a cada Tramo del Envío que identifica varios estados por los que puede ir pasando en ese trayecto. Por lo tanto, exponemos las definiciones que tomamos y algunos puntos a definir/consultar con IFLOW.

Hoja de Ruta (Route)

Es un elemento que se utiliza para agrupar los envíos que estarán presentes en un viaje de un punto a otro (Step). Por ejemplo, un chofer recibe ese listado donde figuran todos los Paquetes que transportará.

Datos

  • Depósito (Depot  - Referencia al Sistema de Procesamiento)

  • Número Hoja de Ruta (número)

  • Dominio (Patente)

  • Chofer

  • Origen (Nodo)

  • Destino (Nodo)

Datos enviados al Step

  • Operación (Utilizado VKM para identificar el cliente , guardar en tramo)

Relación con Shippings

  • Cada Hoja Estará relacionada a muchos Tramos (Step), para establecer la relación con los Envíos (Shipping).

  • Cada Step puede tener una sola Hoja de Ruta asociada. Si se repitieran origen y destino en dos Hojas de Ruta, para el mismo Shipping, se crearía un nuevo Step con los mismos Origen y Destino que en anterior.

Untitled

Identificador unívoco

  • Su clave única estará compuesta por Número de Hoja de Ruta y Depósito

Depósito (Depot)

Representa al sistema de comunicación que envía y recibe información de algunos Envíos (Shipping) y/o Tramos (Step) involucrados. Hoy son las instancias de VKM con las que nos comunicamos, pero podría ser algún otro sistema.

Datos

  • Nombre

A Definir

  • Mapeo con la información recibida (por ejemplo State Info o Servicios  de VKM)

  • Hoy hay un sólo VKM instalado en Pablo Nogués, pero evaluar si tendrá asociados una lista de nodos (origen o destino) sobre los cuales opera por default.

  • Además definir cuáles datos habría que parametrizar si hubiese más de un depósito (muchos hoy están en parameters.yml).

Alta de Envío

Se utilizará el mismo Webservice de VKM que actualmente se utiliza para el alta de envíos a Urbano: ObtenerViajesDespachadosWS. Dicho servicio será  consumido a través del comando app1:api:routes:vkm:get , el cual será descrito en una sección para tal fin.

Propuesta a validar:

  • Se definirán una serie de “Agencias” para cada Carrier, cada una debe porder configurar que se habilite/deshabilite si debe ir al WS de VKM (asegurar que una misma agencia no pueda estar activa en 2 carriers a la vez)

    • Consulta al Service:

      • Alternativa 1: el sistema toma todas las agencias habilitadas para ir a buscar secuencialmente al Service lo que hace ahora.

      • Alternativa 2: no se pase agencia (o se le pasará una lista de agencias y que traiga todo) y se evalúan los pedidos que coincidan con alguna agencia habilitada para incorporar y/o asociar Hoja de Ruta, el resto omitirlos (depende del volumen de elementos que tenga ese servicio y la proporción que incoproraría la API).

  • Agregar a IFLOW como Carrier con sus agencias y que al procesarlos lo asocie también a los Tramos (¿o ésto último no es necesario? Hoy sólo se cargan los Carriers externos)

  • Habrá una única HR por Step de API, si vienen 2 HR distintas con mismos Pedido, Origen y Destino, se crea nuevo Step, quedando 2 con los mismos Origen y Destino.

Procedimiento Inserción

Migracion v1.14

Los step que ya existían se han asociado con HR genericas. El step de colecta con una HR ID 1 que va desde Origen a Pablo Nogues. El step de reparto con una HR ID 2 que va desde Pablo Nogues a Destino.

Desde MELI o VUE

Se crea el Shipping y se crea un Step asociado a la HR genérica de Colecta ID 1 (desde Origen a Pablo Nogues).

Desde el proceso de OBTENERVIAJESDESPACHADOS (Webservice de troncales)

Para cada Hoja de Ruta que devuelve el Service de VKM:

  • Busca la Hoja de Ruta en la API, si no existe la crea. La retorna.

    Si viene desde StateInfo una HR que no tenemos, la creamos y la marcamos como “parcial”, dado que esta incompleta. Si luego esa HR viene desde el WS de trocanles, la hoja se actualiza y se marca como “completa”. Con este criterio, ya tenemos un método que pisa la info, por lo tanto, si se quisieran hacer updates de HR, podríamos, en función de algún parámetro (por ej, un campo mas en el WS que nos indiquen que hubo cambios y quieren actualizar la HR) forzar una actualización de la info.

  • Busca el pedido, si no existe lo crea. Lo retorna

  • Busca si el pedido ya tiene un Step Asociado a la Hoja, si no existe lo crea.

    Si existe un Step que no tiene Hoja (se creo por algún otro medio, y asumimos que habrá uno solo “suelto” por Shipping), tomamos ese y le seteamos la hoja. Lo devuelve.

  • Evalúa si el Shipping en cuestión no tiene ningún estado (en ninguno de los Step que tiene), en ese caso le asigna un estado inicial al primer Step de la secuencia.  Definir si es “Procesado” o se crea otro para ese fin. Como alternativa podría no crearse ninguno, pero quedaría el Shipping sin estado, lo cual no estaría bien.  Sacamos la creacion de todo estado inicial.

  • Asociar el Step al Carrier que correspondiera según la agencia (si se Incluye IFLOW como Carrier también, asegurar que una misma agencia no pueda estar activa en 2 carriers a la vez).

    Cuando se insertan HR en Shipping cuyos Steps estan asociados a HR genericas, se hace un reemplazo de la generica por la nueva. SI vuelve a venir otra HR parcial, no se reemplaza, sino que se agrega y se ordena en base a las HR existentes (al ser parcial no hay plan ni secuencia, que son los que nos dan el orden, asi que genero la POSITION en base al ultimo que me interesa).

Alta de Estados

Procesamiento de State Info

  • Obtiene la Hoja de Ruta (¿Si no existe se da el alta igual sin cargar Origen/Destino/Depósito/Operación (si es así es importante la actualización en el Alta)? ¿O lo marca para su posterior tratamiento una vez ingresado por WS?

  • Busca Step Correspondiente x la Hoja de Ruta, si no existe, Crea el Step (usando la misma función que en el Alta Envío)

Urbano Nuevo Estado

No tenemos la información de Hoja de Ruta como en State Info, ¿cómo aseguramos la correcta determinación de secuencia de Hojas de Ruta del Envío para determinar en cual agregar el estado? Considerando que al haber múltiples tramos y combinaciones, el mismo Carrier podría intervenir en más de un Tramo del envío.

Si mantenemos Etiqueta, obtener para HR por el último Step Urbano por fecha (EVALUAR COMPLICACIONES PRESENTAR AL HABER MÁS DE UN TRAMO)

Estados Manuales

  • Al momento de dar el alta manual, se pide además que indique a qué tramo quiere que sea insertado el estado (cosa que ahora calculaba sólo según Colecta/Reparto, pero que ya no será posible ante la multiplicidad de Tramos).

  • Agregar acción de Alta al ABM de Steps (Tramos), para que también puedan crear a mano tramos. Evaluar bien implicaciones del circuito:

  • Si se tienen que informar a algún lado (VKM por ejemplo)

  • Si le permite seleccionar la Hoja de Ruta o no. En caso que sí, si debe permitir también crear a mano las Hojas de Ruta.

  • Si admite edición (de todos los tramos o sólo de los manuales) y qué impacto podría tener a la hora de la auditoría interna y/o los mecanismos de sincronización que hubiese.

Estados de Carriers (nueva API)

Este servicio luego será utilizado para armar el entorno front para carriers (simil tracking de cliente)

  • Averiguar el mecanismo por el cual se enterarán ellos del alta de un pedido.

  • Impacta como state_info

  • Nos llega estado asociado a step_id (interno API).

  • Alternativa: Solicitar datos sueltos HR, Depósito, Origen, Destino.

  • Nos llega además ID_API de Estado y motivo (¿o código de ingreso en motivo y texto en estado?).

(Siendo servicios de la api, propongo que se utilicen los id propios, salvo que eso traiga algún inconveniente)

Estados de VKM

Determinar si vendrá la información de la HR o cómo identificaremos dónde aplicarlos con exactitud.

Hoy sólo viene por cada aviso: , , y

Listado de Tramos

 Permite a los Operadores obtener un listado de tramos (Step) que tienen asignados.

Tipo de solicitud: GET
Tipo de contenido de solicitud: application/json
URL: /api/v1/carrier/step

Encabezados de la solicitud

ClaveValor
content-typeapplication/json
AuthorizationBearer [token de autenticación]

Respuesta

Códigos de Estados de la solicitud

CódigoDescripción
200OK
204No content
400Bad request
500Internal error

Parámetros de respuesta de la solicitud

ParámetroTipoValoresDependencia
codeintegerCódigo de response HTTP
messagestringVacío / descripción del error si hubiese
countintegerCantidad de resultados
resultsobjectArray de objetos Tramocode: 200

Tramo

ParámetroTipoValoresDependencia
idintegerID del tramo
tracking_idstringCódigo de seguimiento de la Orden
shipment_idstringCódigo de seguimiento del Envío
orderstringID de orden del cliente
originstringNombre del nodo origen
destinationstringNombre del nodo destino
current_stateobjectObjeto Estado

Estado

ParámetroTipoValoresDependencia
idintegerID del Estado
namestringNombre del Estado
datestringFecha del Estado
reasonobjectObjeto Motivo | null

Motivo

ParámetroTipoValoresDependencia
idintegerID del Motivo
namestringNombre del Motivo

 Posibles Estados

IDNombre
6Procesado
7Planificado
8Retirado
10Descargado
25Entregado
26No entregado
27Listo
28Despachado
29Recibido en CD
30Despachado a Nodo Interno
31Arribo a nodo
33Devolución
34Entrega parcial
35Pedido en distribución
36No hubo tiempo
37Pactado
Posibles Motivos


ID             Nombre
1               CERRADO-AUSENTE
2               FUERA DE HORA
3               RECHAZADO MALAS CONDICIONES
4               SIN DINERO
5               NO PEDIDO
6               CORTE DE MERCADERIA
7               DIRECCION INEXISTENTE
8               TIENE STOCK
9               SIN ORDEN DE COMPRA
10             RECHAZO POR TEMPERATURA
11             SIN DOCUMENTACION
12             SE MUDO
13             FALLECIDO
14             FECHA CORTA
15             EXCESO DE DEMORA
16             INVERSION
17             SIN SISTEMA
18             DESCONOCIDO
19             NO SE UBICA DOMICILIO
20             PEDIDO REPETIDO
21             ERROR EN PEDIDO
22             SIN ABASTO
23             SIN CARGAR
24             DIRECCION INCOMPLETA
25             CASILLA DE CORREO
26             DE VIAJE FUERA DE LA CIUD
27             DEVOLUCION AL CLIENTE
28             DIRECCION INSUFICIENTE
29             DOCUMENTACION PENDIENTE
30             EMERGENCIA OPERATIVA
31             FUERA DE CONTRATO
32             MAL CODIFICADO
33             NO SE ECUENTRA PERSONA HA
34             NO TRABAJA MAS EN LA EMPRESA
35             PIEZA NO INGRESADA
36             REHUSA RECIBIR
37             RESCATE BANCARIO
38             RETENIDA POR INDICACION D
39             SOBRE EXTRAVIADO ROBADO
40             ZONA INTRANSITABLE
41             ZONA PELIGROSA
42             NO EXISTE CALLE
43             SIN PAQUETES
44             DIRECCIÓN INCORRECTA
45             ENTREGA A CENTRO OCASA
46             ENTREGA POR OTRO CARRIER
47             MISMO SELLER
48             NO COLECTÓ
49             PIDIÓ DE NO PASAR MÁS
50             SE MUDÓ
51             SIN PAQUETERÍA
52             VACACIONES
53             NO VISITÓ
54             INVERSIÓN DE CODIGO
55             FACTURA Y ORDEN DE COMPRA DIFIEREN
56             PROBLEMAS EN LA BOCA
57             RECHAZO TOTAL - DIFERENCIA EN PESO
61             Sin orden de compra

NOTA: se consideran como posibles estados los que están configurados en el backend con el flag de “Crea estado en Tracking” en SI.

Ejemplo

 Solicitud

 curl -X GET \

https://test-api.iflow21.com/api/v1/carrier/step \

-H ‘content-type: application/json’ \

-H ‘authorization: Bearer TOKEN

Respuesta

{
    "code": 200,
    "message": "",
    "count": 2,
    "results": [
    {
        "id": 20039,
        "tracking_id": "OR0001401171",
        "shipment_id": "T0000000010",
        "order": "ABC0001",
        "origin": "Pablo Nogues",
        "destination": "Rivadavia 123",
        "current_state": {
            "id":25,
            "name": "Entregado",
            "date": "2018-08-10 12:12:12",
            "reason": null
        }
    },
    {
        "id": 20040,
        "tracking_id": "OR0001401172",
        "shipment_id": "T0000000011",
        "order": "ABC0002",
        "origin": "Pablo Nogues",
        "destination": "San Martin 123",
        "current_state": {
            "id": 26,
            "name": "No entregado",
            "date": "2018-08-11 15:00:00",
            "reason": {
                "id": 19,
                "name": "NO SE UBICA DOMICILIO"
            }
        }
    }]
}

Alta de Estado

Permite a los Operadores informar un nuevo estado para un tramo (Step) asignado.

Tipo de solicitud: POST
Tipo de contenido de solicitud: application/json
URL: /api/v1/carrier/step_state

Encabezados de la solicitud

ClaveValor
content-typeapplication/json
AuthorizationBearer [token de autenticación]

Parámetros de la solicitud

ParámetroTipoRequeridoDescripción
step_idintegerSIID del tramo
state_idstringNOID del estado a insertar
reason_idintegerSIID del motivo a insertar
datedatetimeNOFecha del cambio de estado (formato ‘aaaa-mm-dd hh:mm:ss ’)

Respuesta

Codigos de Estados de la solicitud

CódigoDescripción
201Created
400Bad request
500Internal error

Parámetros de respuesta de la solicitud

ParámetroTipoValoresDependencia
codeintegerCódigo de response HTTP
messagestringDescripcion de la operación

Ejemplo

Solicitud

curl -X POST \
https://test-api.iflow21.com/api/v1/carrier/step_state \
-H 'content-type: application/json' \
-H 'authorization: Bearer TOKEN
-d '{
  "step_id": 20039,
  "state_id": 25,
  "date": "2018-08-08 12:45:00"
}'

Respuesta

{
  "code": 201,
  "message": "Se ha creado correctamente el elemento."
}

Cancelación de Orden

Mediante el siguiente request, los Clientes podrán indicar la cancelación de una Orden.

Tipo de solicitud: PUT
Tipo de contenido de solicitud: application/json
URL: /api/v1/client/order/{id}/cancel

Encabezados de la solicitud

ClaveValor
content-typeapplication/json
AuthorizationBearer [token de autenticación]

Parámetros de la solicitud

ClaveValor
idID de la Orden

Respuesta

Códigos de Estados de la solicitud

CódigoDescripción
200OK
204No content
400Bad request
500Internal error

Parámetros de respuesta de la solicitud

ParámetroTipoValoresDependencia
codeintegerCodigo de response HTTP
messagestringvacio / descripción del error si hubiese

Cancelación de Envío

Mediante el siguiente request, los Clientes podrán indicar la cancelación de una Orden.

Tipo de solicitud: PUT
Tipo de contenido de solicitud: application/json
URL: /api/v1/client/shipping/{id}/cancel

Encabezados de la solicitud

ClaveValor
content-typeapplication/json
AuthorizationBearer [token de autenticación]

Parámetros de la solicitud

ClaveValor
idID del Envío

Respuesta

Codigos de Estados de la solicitud

CódigoDescripción
200OK
204No content
400Bad request
500Internal error

Parámetros de respuesta de la solicitud

ParámetroTipoValoresDependencia
codeintegerCodigo de response HTTP
messagestringvacio / descripción del error si hubiese

Comandos

En esta sección se describirán los comandos definidos para satisfacer el flujo de troncales.

Consumo de servicios de depósitos (app1:api:routes:vkm:get )

Comando: app1:api:routes:vkm:get

Descripción:

    Se conecta a los depósitos para obtener las hojas de ruta a incorporar al sistema.

Uso:

 app1:api:routes:vkm:get [options] [--] <action>

Argumentos:

Action Identifica la acción a realizar:

             list: devuelve una lista de IDs de carriers con agencias activas listos para operar.

             execute: debe ser acompañado por el argumento ‘id’ del carrier que se desea utilizar .

Options:

            —id[=ID]          Parámetro de Id para la acción de execute.

            —desde[=DESDE]      Fecha inicial del request de Hojas de Ruta

            —hasta[=HASTA]        Fecha inicial del request de Hojas de Ruta

            —depot_id[=DEPOT_ID]  ID del Depósito a procesar

Ejemplos de invocación:

Terminal window
app/console app1:api:routes:vkm:get list


app/console app1:api:routes:vkm:get execute --id 40


app/console app1:api:routes:vkm:get execute --id 40 --depot_id 1