Cómo integrar el servicio de entrega a través de la API

Copiar enlace al artículo

Copiado

En desarrollo

Historial de cambios

28.04.2019

Se agregó el campo integrationModule[integrations][delivery][settings] a los métodos GET / api / v5 / integration-modules / {code} , POST / api / v5 / integration-modules / {code} / edit ... Le permite obtener o actualizar la configuración de entrega de integración.

04/03/2019

En el método Callback POST {integrationModule["baseUrl"]}/{configuration["actions"]["calculate"]} (referencia al método ) en el objeto RequestCalculate se agregó la transferencia del contenido del paquete calculate[packages][][items][].

Se han agregado los siguientes campos al objeto PackageItem: externalId - ID de oferta comercial en la tienda, xmlId - ID de oferta comercial en el sistema de almacén. El objeto PackageItem se usa en los métodos: Callback POST {integrationModule["baseUrl"]}/{configuration["actions"]["calculate"]} (referencia de método ]) y Callback POST {integrationModule["baseUrl"]}/{configuration["actions"]["save"]} ([referencia de método [[TRANSLATE_PLACEHOLDER_3015]

14/11/2017

En el método POST / api / v5 / integration-modules / {code} / edit , se ha agregado la matriz integrationModule[integrations][delivery][shipmentDataFieldList][]: una lista de campos adicionales que se utilizan para crear una solicitud de envío.

Se agregaron métodos de devolución de llamada para trabajar con el envío de pedidos al servicio de entrega:

• POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentSave"]} (referencia de método ) crear / editar solicitud de envío
• POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentDelete"]} (enlace al método ) eliminar la solicitud de envío

Para poder trabajar con estos métodos, es necesario en el método POST / api / v5 / integration-modules / {code} / edit en el parámetro integrationModule[integrations][delivery][actions][] para pasar las rutas para el [[TRANSLATE_PLACEHOLDER_3020OLDER_30]] y [TRANSLATE_PLACEHOLDER_3020OLDER_30 ]].

27.09.2017

En el objeto Configuration en la lista de campos obligatorios requiredFields, es posible especificar el campo requerido "Terminal de embarque", para esto agregar el valor integrationDeliveryData.shipmentpointName a la lista.

09.06.2017

Se agregó la transferencia de tasas de IVA al RequestSave objeto de la solicitud de entrega: save[packages][][items][][vatRate] - Tasa de IVA para los productos en el pedido. save[delivery][vatRate]: tasa de IVA para el servicio de entrega. Ambos campos pueden tomar el valor none, lo que significa que el producto / servicio de entrega no está sujeto al IVA.

22/03/2017

Se ha añadido un campo booleano opcional rateDeliveryCost a Configuration (de forma predeterminada true). El valor false es necesario si el servicio de entrega no calcula el costo de envío y el método calculate solo devuelve información sobre las tarifas disponibles. También se agregó la capacidad de no especificar la ruta para el método calculate (la ruta para el método save tampoco debe especificarse). En este caso, la integración le permite rellenar manualmente el número de envío y sincronizar los estados de entrega.

Se ha añadido una matriz opcional availableShipmentCountries a Configuration; contiene una lista de países desde los que se puede realizar el envío. De forma predeterminada, la matriz está vacía, lo que significa que no hay restricciones en los países de envío.

Al registrar la entrega en un punto de recogida mediante el método save, ahora, además del código de recogida, se transmite la dirección de entrega.

En respuesta a la solicitud del método calculate, se agregó el campo extraDataAvailable: una matriz de códigos de campo de la lista configuration["deliveryDataFieldList"] que se pasó en la solicitud de configuración de entrega. Al elegir una tarifa en la tarjeta de pedido, se ocultarán todos los campos que no estén en la matriz extraDataAvailable.

01/03/2017

Se ha agregado un campo de texto opcional description a Configuration; se puede usar para transferir la descripción de la integración, incluso para determinar a qué cuenta del servicio de entrega pertenece la integración. El valor pasado se muestra en la configuración de integración y en la lista de integraciones disponibles en la tarjeta de tipo de entrega;

Se ha agregado un campo opcional a Configuration deliveryConfigurationUrl - contiene la URL mediante la cual el usuario puede ir a la página de configuración de integración en el lado del servicio de entrega;

En la solicitud para crear / editar la configuración de integración en el objeto DeliveryDataField, se ha agregado un campo de texto opcional hint - en él puede enviar una explicación al usuario de cómo y cuándo usar este campo. Se muestra en la tarjeta de pedido debajo del campo correspondiente;

En los objetos RequestCalculate y RequestSave se agregó el campo currency que contiene el código de moneda;

En el objeto RequestSave, se han agregado el campo siteName (nombre de la tienda) y el opcional legalEntity (nombre de la entidad legal del vendedor);

Se agregó el campo offerId a la solicitud de registro de entrega en el objeto PackageItem - identificador de oferta en el sistema

En respuesta a una solicitud para recibir formularios imprimibles del servicio de entrega, ahora puede enviar un archivo zip, para esto, el encabezado de respuesta ContentType debe tomar el valor application/zip.

Opciones de integración

La API del sistema permite:

1. Calcule el costo de envío de acuerdo con los datos del pedido a solicitud del usuario del sistema.
2. Entregue al usuario del sistema el conjunto de terminales relevantes para el pedido dado.
3. Forme diferentes paquetes dentro de una orden de entrega
4. Formular un pedido para la entrega, transfiriendo la información necesaria sobre el pedido al servicio de entrega.
5. Edite y elimine una orden de entrega en ciertos estados a petición del usuario del sistema.
6. Actualización masiva de estados para pedidos sin terminar
7. Enviar documentos para imprimir en pedidos de servicios de entrega a solicitud del usuario.
8. Crear, editar y eliminar pedidos para la recogida de productos por parte del servicio de entrega.

Trabajar con la API se realiza de acuerdo con las reglas para trabajar con API ]. Para la integración, utilice los métodos de API de la sección Entrega e integración.

Para la integración necesita:

1. USER Solicita una clave API al usuario para acceder al sistema
2. API Registre un nuevo módulo de integración de envío
3. USER Realice la configuración necesaria en la página de configuración de integración del sistema
4. USER Cree un tipo de envío asociado con un nuevo envío de integración
5. SYSTEM El sistema iniciará las solicitudes relacionadas con la creación y el cambio de órdenes de entrega durante el trabajo del usuario.
6. API Envíe datos actualizados sobre los estados de entrega

Las etapas marcadas con USER son ​​etapas en las que el usuario proporciona o completa los datos. Las etapas marcadas como API se realizan a través de solicitudes de API del servicio de entrega a través de la API del sistema. La etapa marcada SYSTEM implica solicitudes realizadas por el sistema al servicio de entrega, teniendo en cuenta la configuración especificada durante el registro.

Si se produce un error durante una solicitud de API al servicio de entrega, debe devolver una respuesta (estado HTTP 200) en el formato:

{
 "success": false,
 "errorMsg": "Texto de error" // Mensaje de error. Se mostrará al usuario en la ficha del pedido.
}

Si, en respuesta a una solicitud para calcular el costo de entrega o en respuesta a una solicitud de datos de pedido del servidor del servicio de entrega, se devolvió una respuesta no válida, la información al respecto se registrará en el Registro de acciones , tipo de registro "Entregas de integración".

Para identificar regiones, ciudades y calles, además de los nombres de texto, se transmiten identificadores del servicio Geohelper .

Configuración del servicio de registro y entrega

El registro de una nueva entrega, tanto como el cambio de la configuración de una existente, se realiza atravez del método POST / api / v5 / integration-modules / {code} / edit . Si el módulo de integración con el código code ya existe, el método cambia sus parámetros, de lo contrario se crea un nuevo módulo. Al registrar una entrega, se transmite un código único integrationModule[clientId], que permitirá al servicio de entrega identificar la cuenta del sistema.

Opciones:

• apiKey: clave de API del sistema
• integrationModule - json que contiene la descripción del módulo de integración
• integrationModule[integrations][delivery]: ajustes de configuración para la integración con el servicio de entrega

El campo integrationModule[integrations][delivery][actions] como una matriz asociativa ("Código de método": "Ruta") especifica las rutas a métodos específicos. Lista de métodos:

• calculate: método de cálculo del costo de envío
• save - Método de creación / edición de envío
• get: método de recuperación de datos de entrega.
• delete - Método para eliminar / cancelar la entrega. Se llama si el pedido ha sido cancelado o si se ha cambiado el tipo de entrega del pedido.
• print - Método para imprimir documentos.
• shipmentPointList - Método para obtener una lista de terminales de envío.
• shipmentSave - Método para crear / editar una solicitud de envío.
• shipmentDelete: método para eliminar una solicitud de envío.

Algunos métodos son opcionales. Si no son necesarios para la integración, se pueden omitir en la matriz actions. Los métodos save, get, print, shipmentSave, shipmentDelete son ​​opcionales. Si no se pasa el método save, las solicitudes de entrega no se envían. Si no se aprueba el método shipmentDelete, la capacidad de editar y eliminar la solicitud de envío no estará disponible. El método delete es opcional a menos que se utilice el método save. El método calculate es opcional a menos que se utilice el método save. Si el método calculate no está implementado, la integración solo permite especificar manualmente el número de envío en la tarjeta de pedido y realizar el seguimiento. El método shipmentPointList es opcional si "selfShipmentAvailable": false. No está permitido pasar los mismos valores para diferentes métodos.

El campo integrationModule[integrations][delivery][requiredFields] contiene una serie de campos que deben ser obligatorios para esta entrega. Valores posibles:

• lastName: apellido del comprador
• patronymic: segundo nombre del comprador
• phone: número de teléfono del comprador
• email: correo electrónico del comprador
• length - Longitud
• width - Ancho
• height: altura
• shipmentDate: fecha de envío
• deliveryTime.from - Inicio del intervalo de tiempo de entrega
• deliveryTime.to - Fin del intervalo de tiempo de entrega
• manager - Administrador de pedidos
• deliveryAddress.regionId: al elegir una región, debe seleccionar una región de la lista desplegable. Este campo contendrá el identificador de región en el servicio geohelper (http://geohelper.info/es/doc/api#get--api-v1-regions)
• deliveryAddress.cityId - Al elegir una ciudad, es obligatorio seleccionar una ciudad de la lista desplegable. Este campo contendrá el identificador de la ciudad en el servicio geohelper (http://geohelper.info/es/doc/api#get--api-v1-cities)
• deliveryAddress.street: nombre de la calle de entrega
• deliveryAddress.streetId - Al elegir una calle, es obligatorio seleccionar una calle de la lista desplegable. Este campo contendrá el identificador de la calle en el servicio geohelper (http://geohelper.info/es/doc/api#get--api-v1-streets)
• deliveryAddress.flat - Apartamento
• deliveryAddress.index - Código postal
• integrationDeliveryData.shipmentpointName - Terminal de envío

En el campo integrationModule[integrations][delivery][payerType] puede especificar una serie de posibles tipos de pagadores para la entrega. En el caso de entrega contra reembolso, dependiendo del tipo de pagador, existen 2 opciones de pago por entrega:

1. Remitente del pagador sender: el pago contra reembolso incluye el costo de envío y el costo de los productos. Los servicios de entrega los paga la tienda.
2. Pagador - destinatario receiver - solo el costo de los productos en el pedido se incluye en el pago contra reembolso. El costo de envío es siempre 0. Se entiende que el servicio de entrega deberá tomar del comprador la cantidad transferida de contra reembolso a favor de la tienda y por separado el costo de entrega a su favor.

El parámetro integrationModule[integrations][delivery][selfShipmentAvailable] le permite activar el trabajo con terminales de envío. Si se pasa el valor true, aparecerá un campo en la ficha del pedido donde puede seleccionar una terminal de envío de la lista obtenida por el método shipmentPointList. Además, en la configuración de integración, el usuario puede configurar terminales de envío predeterminados para cada uno de sus almacenes. Al calcular el costo y registrar la entrega, la dirección del almacén de envío especificada en la ficha del pedido generalmente se envía como la dirección de envío. En el caso de que se seleccione el terminal de envío para el pedido, solo se envía el código del terminal de envío seleccionado en los datos de la dirección de envío.

Responder:

{
 "code": "generic.delivery-service-code",
 "success": true
}

Soporte para múltiples cuentas

El servicio de entrega debe permitir la posibilidad de conectar varias cuentas de clientes. Para hacer esto, antes de enviar una solicitud de registro del módulo de integración de entrega, utilice el método obtener información sobre el módulo de integración . Si la integración ya está registrada y clientId no coincide con el actual, entonces debes pasar el código del servicio de entrega al parámetro integrationModule[code] con un sufijo que asegura la unicidad del código (integrationModule[integrationCode] debe permanecer sin cambios) ... En este caso, se crea un nuevo módulo de integración y el cliente podrá trabajar con cualquier número de cuentas en el servicio de entrega, que se presentarán como diferentes tipos de entrega. También se recomienda transmitir una descripción en el campo integrationModule[integrations][delivery][description] que ayudará a distinguir al usuario de varias integraciones idénticas con diferentes cuentas (por ejemplo, puede transferir los últimos dígitos del número de contrato o el número de cuenta de usuario "Número de contrato -***42").

Formación de campos adicionales

La integración le permite transferir la configuración para producir un conjunto arbitrario de campos. El campo integrationModule[integrations][delivery][deliveryDataFieldList] enumera los campos que se mostrarán en la tarjeta de pedido. Si editable=true - los datos de los campos editados se transmitirán al formar la entrega. Si el parámetro es affectsCost=true, estos campos se transmitirán al calcular el costo de envío. El campo integrationModule[integrations][delivery][shipmentDataFieldList] contiene un conjunto de campos que se utilizan cuando se trabaja con el envío. El formato de los elementos de la lista shipmentDataFieldList es completamente idéntico al formato de los elementos deliveryDataFieldList.

Campo de texto editable opcional:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "textField",
 "label": "Campo de texto",
 "type": "text",
 "required": false,
 "affectsCost": false,
 "editable": true
 }
 ]
}

Cuadro de texto informativo:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "textField",
 "label": "Importe del seguro",
 "hint": "Usar solo para envíos internacionales",
 "type": "text",
 "required": false,
 "affectsCost": false,
 "editable": false
 }
 ]
}

El campo se muestra en la ficha del pedido. Se puede completar al recibir una respuesta a una solicitud de generación de entrega o al actualizar el estado de la entrega.

Campo numérico editable obligatorio. Porque affectsCost=true: se considera que el campo afecta el costo de envío y el valor del campo se envía en la solicitud para calcular el costo de envío:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "integerField",
 "label": "Numero de plazas",
 "type": "integer",
 "required": true,
 "affectsCost": true
 }
 ]
}

Caja:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "checkboxField",
 "label": "cambiar",
 "type": "checkbox",
 "required": false,
 "affectsCost": true
 }
 ]
}

Campo de opción múltiple:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "services",
 "label": "servicio de entrega",
 "type": "choice",
 "multiple": true,
 "choices": [
 {
 "value": "ER3",
 "label": "inspección"
 }
 {
 "value": "RQW",
 "label": "Entrega de fin de semana"
 }
 ],
 "affectsCost": true
 }
 ]
}

Campo de autocompletar. Para usarlo, debe implementar un método para recibir sugerencias y pasar la URL del método:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "types",
 "label": "Tipo de carga",
 "type": "autocomplete",
 "autocompleteUrl": "http://selivery.service.com/api/autocomplete/types"
 }
 ]
}

Campo de fecha:

{
 ...
 "deliveryDataFieldList": [
 {
 "code": "dateSimple",
 "label": "fecha de entrega",
 "type": "date"
 }
 ]
}

Ajustes configurados por el módulo

La integración le permite transferir un conjunto de ajustes en la configuración. El campo integrationModule[integrations][delivery][settings] enumera los campos configurados por el módulo. Se recomienda dar la oportunidad de configurar todos los parámetros en el lado del módulo y transferirlos al sistema a través de este campo. La configuración transferida se ocultará en la configuración de integración del módulo en el sistema.

Configuraciones:

• defaultPayerType: pagador de envío predeterminado
• costCalculateBy: costo de envío predeterminado (posibles valores automáticos | manuales)
• nullDeclaredValue: valor declarado cero de forma predeterminada
• lockedByDefault: de forma predeterminada, no envía datos al servicio de entrega
• paymentTypes - Métodos de pago (Directorio de objetos )
• shipmentPoints - Almacenes (Directorio de objetos )
• statuses - Correspondencia de estados (directorio de objetos )
• deliveryExtraData: valores de campo de envío predeterminados adicionales
• shipmentExtraData: valores de campo de envío predeterminados adicionales

Un ejemplo de configuración de la configuración:

{
 "defaultPayerType": "sender",
 "costCalculateBy": "auto",
 "nullDeclaredValue": true,
 "lockedByDefault": true,
 "paymentTypes": [
 {
 "code": "cash",
 "active": true,
 "cod": true

}
 ],
 "shipmentPoints": [
 {
 "code": "online",
 "shipmentPointId": "1234",
 "shipmentPointLabel": "Test"

}
 ],
 "statuses": [
 
{

 "code": "new",
 "trackingStatusCode": "new"

}
 ],
 "deliveryExtraData": {
 "passport": "0000 000000"
 },
 "shipmentExtraData": {
 "count": "5"
 }
}

Obtén la configuración de integración

El método le permite obtener los datos del módulo de integración del servicio de entrega GET / api / v5 / integration-modules / {code} .

Cálculo de los gastos de envío

Para calcular el costo de envío, el sistema inicia una llamada POST al método especificado en la configuración integrationModule[integrations][delivery][actions]["calculate"].

El costo se calcula cuando abre una ventana emergente con una lista de métodos de entrega.

Si no hay suficientes datos transmitidos para algunas tarifas, es posible que el servicio de entrega no transmita el parámetro cost para la tarifa, pero envíe un mensaje al usuario en el parámetro description. En este caso, la tarifa no estará disponible para su selección, pero se mostrará en la lista de tarifas. Si el servicio de entrega no tiene la capacidad de calcular el costo de entrega, al configurar la integración se puede pasar el parámetro integrationModule[integrations][delivery][rateDeliveryCost] con el valor false, en este caso, no es necesario transmitir el costo de envío y el costo se determina de acuerdo con las reglas especificadas en el tipo de entrega en el lado sistemas.