Envío de albaranes por API

Otros

Descarga en PDF la integración de envío de albaranes por API

Integración de albaranes por API

La importación de contenido mediante API requiere de la creación por parte del usuario de un token de acceso. Este token es un string que identifica a un usuario dentro de una aplicación o servicio, para realizar llamadas a la API.

1. Creación del token

Para obtener este token de acceso tendrá que tener un usuario creado en nuestra plataforma con el rol de técnico. En el momento de la creación de la cuenta en Polpoo se creará automáticamente un usuario técnico. Las credenciales de dicho usuario serán enviadas en el correo de bienvenida. En caso de querer crear otra cuenta de usuario de tipo técnico, hay que ir a la sección de Gestión y en la pestaña de Usuarios clicar en + Crear usuario y rellenar todos los campos; indicando el rol de usuario como técnico.

Los parámetros de conexión de la conexión API son los siguientes:

URL: https://restapi.polpoo.com/api/oauth/token_integrator

MÉTODO: POST

CONTENIDO: application/json

Para obtener el token de acceso se deberá hacer una petición API con el siguiente esquema de código

2. Enviar Albaranes

Para enviar albaranes tendrá  que tener un token de acceso y tener un usuario creado en nuestra plataforma con el rol de técnico. En el momento de la creación de la cuenta en Polpoo se creará automáticamente un usuario técnico. 


Los parámetros de conexión de la conexión API son los siguientes:

URL: https://restapi.polpoo.com/api/route_planning/route/assign_products_global

MÉTODO: POST

CONTENIDO: application/json

{

 "client_id": 1,
 "client_secret": "tT96kecNtYVf92dvRfQ1Ikj6sjsx5tKZzaCCpHun",
 "username":  "integration@company.com",
 "password":  "secret_password",
 "grant_type": "password"
}

Los campos client_id, client_secret y grant_type son constantes, es decir, no deben modificarse en ningún caso. Por otra parte, los campos username y password sí que son modificables, y deberán rellenarse con los datos del usuario creado anteriormente como técnico. Este usuario os lo facilitará Polpoo.

3. Respuesta de la API

Una vez establecida la conexión y hecha la petición a la API, se recibirá la respuesta por parte de nuestro sistema con el token de acceso.

{

 "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiI",
 "refresh_token": "def50200388a50a45925d65",
 "expires_in": 86400,
 "token_type": "Bearer",
 "username": "integration@company.com"
}

4. Especificaciones de los campos

En un mismo fichero tienen que venir toda la información de todos los albaranes.

Si un cliente tiene más de un albarán, se tiene que añadir como nuevo registro en el array «deliveryNotes». Si por ejemplo, se entregan 5 recibos en un mismo destino, se tiene que añadir un único registro de ese cliente cliente con 5 recibos.

Es importante que la información de los campos no contenga comillas dobles (p.e: «Frutería «El sol»»), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial es aceptado.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el json.

 

*La información recomendada está marcada en azul. No son obligatorios para la estructura del fichero, pero sí recomendable para el correcto funcionamiento de Polpoo.

 

id string – obligatorio
Identificador único del cliente.

 

 

deliveryNotes.deliveryNoteCode string – obligatorio
Número o código del albarán.

 

deliveryNotes.kg float   recomendado

Carga en kilos del albarán.

 

 

deliveryNotes.volumen float   recomendado

Carga en metros cúbicos del albarán.

 

 

deliveryNotes.package integer   recomendado

Número de bultos del albarán.

 

 

deliveryNotes.deliveryNoteObservation string   recomendado
Observaciones del albarán.

 

 

 

deliveryNotes.deliveryNoteOrderCode string   recomendado
Número del pedido referente al albarán.

 

 

deliveryNotes.promptPayDiscountPercent float   recomendado
Porcentaje de descuento a aplicar en el precio total del albarán.

 

 

deliveryNotes.isDevolution boolean   recomendado
Marca si el albarán es de entrega o recogida. En caso de ser «True» será de recogida y en caso de ser «False» o no mandar la información, será de entrega.

 

 

deliveryNotes.products.code string – obligatorio
Identificador del producto.

 

 

 

deliveryNotes.products.name string – obligatorio
Nombre del producto.

 

 

 

deliveryNotes.products.quantity float – obligatorio
Cantidad del producto.

 

 

 

deliveryNotes.products.price float – obligatorio
Precio del producto por medida.

 

 

 

deliveryNotes.products.taxPercent integer – obligatorio
Impuesto sobre el Valor Añadido (IVA) del producto.

 

 

deliveryNotes.products.measure string – obligatorio
Formato del producto.

 

 

deliveryNotes.palets integer

Número de palets del albarán.

 

 

deliveryNotes.sendDeliveryNoteCompanyId integer
Id de la compañía donde irá la información de los albaranes. *Sólo para multialmacén.

 

 

deliveryNotes.showDeliveryNotePrice boolean 
Si aparecerá el albarán con precios o sin precios.

 

 

deliveryNotes.managementCost float
Coste de gestión del albarán.

 

 

deliveryNotes.scannedCode string – sólo con el módulo Paquetería
Código de escaneo del albarán.

 

 

deliveryNotes.isBill boolean 
Si es true, esta información pasará a ser de factura. Si es false o no se envío este campo, será un albarán.

 

 

deliveryNotes.billType integer
En caso de que isBill sea true y este campo contenga un 11,  la factura se tendrá que cobrar, de lo contrario, la factura solo se tendrá que firmar.

 

 

deliveryNotes.date date
Fecha que aparecerá en el albarán.

 

 

deliveryNotes.barCode string
Imagen en base64 del código de barras que aparecerá en el albarán.

 

 

deliveryNotes.deliveryIdentifier string
Identificador de la entrega para asignación correcta del albarán. Vinculación con el mismo campo en rutas.

 

 

deliveryNotes.documentStore string 
Almacén del documento (sólo informativo).

 

 

deliveryNotes.documentType string 
Tipo de documento (sólo informativo).

 

 

deliveryNotes.documentSeries string 
Serie del documento (sólo informativo).

 

 

deliveryNotes.documentExercise string 
Ejercicio del documento (sólo informativo).

 

 

deliveryNotes.companyAssociated.code string – obligatorio si factura a compañía asociada
Código de la compañía asociada.

 

 

deliveryNotes.companyAssociated.name string – obligatorio si factura a compañía asociada
Nombre de la compañía asociada.

 

 

deliveryNotes.companyAssociated.nif string – obligatorio si factura a compañía asociada
NIF de la compañía asociada.

 

 

deliveryNotes.companyAssociated.streetAddress string – obligatorio si factura a compañía asociada
Dirección de la compañía asociada.

 

 

deliveryNotes.companyAssociated.city string – obligatorio si factura a compañía asociada
Ciudad de la compañía asociada.

 

 

deliveryNotes.companyAssociated.province string – obligatorio si factura a compañía asociada
Provincia de la compañía asociada.

 

 

deliveryNotes.companyAssociated.zipCode string – obligatorio si factura a compañía asociada
Código postal de la compañía asociada.

 

 

deliveryNotes.companyAssociated.phone string – obligatorio si factura a compañía asociada
Número de teléfono de la compañía asociada.

 

 

deliveryNotes.companyAssociated.billingAddress string – obligatorio si factura a compañía asociada
Correo de facturación de la compañía asociada.

 

 

deliveryNotes.products.lotCode string   recomendado
Identificador del lote al que pertenece el producto.

 

 

deliveryNotes.products.discountPercent float   recomendado
Descuento en porcentaje del producto.

 

 

deliveryNotes.products.measureQuantity float
Cantidad del producto referente a la medida.

 

 

deliveryNotes.products.equivalencePercent float
Porcentaje del recargo de equivalencia del producto.

 

 

deliveryNotes.products.grossMass float
Peso bruto del producto.

 

 

deliveryNotes.products.tare float
Tara del producto.

 

 

deliveryNotes.products.netMass float
Peso neto del producto.

 

 

deliveryNotes.products.observation string
Observaciones del producto.

 

 

deliveryNotes.products.scannedCode string – sólo con el módulo Paquetería
Código de escaneo del bulto.

 

 

deliveryNotes.products.supplierReference string
Proveedor del producto.    

5. Ejemplos y descargables

{
	"deliveryPoints": [
		{
			"id": "1050",
			"deliveryNotes": [
				{
					"deliveryNoteCode": "73289236432",
					"deliveryNoteObservation": "10-04",
					"showDeliveryNotePrice": true,
					"isBill": false,
					"kg": 150.0,
					"volumen": 2.5,
					"package": 10,
					"deliveryNoteOrderCode": "ORD-123456",
					"promptPayDiscountPercent": 5.0,
					"isDevolution": false,
					"products": [
						{
							"code": "101-ECO.7",
							"name": "NARANJA Eco",
							"quantity": 3,
							"price": 1.25,
							"measureQuantity": 30,
							"lotCode": "Lote/s:50934952 50934953 50934954",
							"taxPercent": 4,
							"measure": "KGS",
							"grossMass": 2.1,
							"tare": 0.3,
							"netMass": 1.8
						}
					]
					
				}
			]
		}
	],
	"dateDeliveryStart": "2024-04-10"
}

6. Albaranes sin productos

Para enviar albaranes sin productos, deberás configurar tu cuenta Polpoo de la siguiente manera:

En Configuración > Seguimiento de viajes > Albarán y factura >  Permitir enviar albarán por integración sin el detalle de los productos (activar la opción).

7. Especificaciones de los campos

En un mismo fichero tienen que venir toda la información de todos los albaranes .

Si un cliente tiene más de un albarán, se tiene que añadir como nuevo registro en el array «deliveryNotes». Si por ejemplo, se entregan 5 recibos en un mismo destino, se tiene que añadir un único registro de ese cliente cliente con 5 recibos.

Es importante que la información de los campos no contenga comillas dobles (p.e: «Frutería «El sol»»), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial es aceptado.

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el json.

 

*La información recomendada está marcada en azul. No son obligatorios para la estructura del fichero, pero sí recomendable para el correcto funcionamiento de Polpoo.

id string – obligatorio
Identificador único del cliente.


deliveryNotes.deliveryNoteCode string – obligatorio
Número o código del albarán.


deliveryNotes.totalPrice float – recomendado
Precio de la suma de todos los productos.


deliveryNotes.kg float – recomendado

Carga en kilos del albarán.


deliveryNotes.volumen float – recomendado

Carga en metros cúbicos del albarán.


deliveryNotes.package integer – recomendado

Número de bultos del albarán.


deliveryNotes.deliveryNoteObservation string – recomendado
Observaciones del albarán.


deliveryNotes.deliveryNoteOrderCode string – recomendado
Número del pedido referente al albarán.


deliveryNotes.promptPayDiscountPercent float – recomendado
Porcentaje de descuento a aplicar en el precio total del albarán.


deliveryNotes.isDevolution boolean – recomendado
Marca si el albarán es de entrega o recogida. En caso de ser «True» será de recogida y en caso de ser «False» o no mandar la información, será de entrega.


deliveryNotes.isBill boolean 
Si es true, esta información pasará a ser de factura. Si es false o no se envío este campo, será un albarán.


deliveryNotes.billType integer
En caso de que isBill sea true y este campo contenga un 11,  la factura se tendrá que cobrar, de lo contrario, la factura solo se tendrá que firmar.


deliveryNotes.showDeliveryNotePrice boolean
Si aparecerá el albarán con precios o sin precios.


deliveryNotes.palets integer

Número de palets del albarán.


deliveryNotes.sendDeliveryNoteCompanyId integer
Id de la compañía donde irá la información de los albaranes. *Sólo para multialmacén.


deliveryNotes.managementCost float
Coste de gestión del albarán.


deliveryNotes.scannedCode string – sólo con el módulo Paquetería
Código de escaneo del albarán.


deliveryNotes.date date
Fecha que aparecerá en el albarán.


deliveryNotes.barCode string
Imagen en base64 del código de barras que aparecerá en el albarán.


deliveryNotes.deliveryIdentifier string
Identificador de la entrega para asignación correcta del albarán. Vinculación con el mismo campo en rutas.


deliveryNotes.documentStore string 
Almacén del documento (sólo informativo).


deliveryNotes.documentType string 
Tipo de documento (sólo informativo).


deliveryNotes.documentSeries string 
Serie del documento (sólo informativo).


deliveryNotes.documentExercise string 
Ejercicio del documento (sólo informativo).


deliveryNotes.companyAssociated.code string – obligatorio si factura a compañía asociada
Código de la compañía asociada.


deliveryNotes.companyAssociated.name string – obligatorio si factura a compañía asociada
Nombre de la compañía asociada.


deliveryNotes.companyAssociated.nif string – obligatorio si factura a compañía asociada
NIF de la compañía asociada.


deliveryNotes.companyAssociated.streetAddress string – obligatorio si factura a compañía asociada
Dirección de la compañía asociada.


deliveryNotes.companyAssociated.city string – obligatorio si factura a compañía asociada
Ciudad de la compañía asociada.


deliveryNotes.companyAssociated.province string – obligatorio si factura a compañía asociada
Provincia de la compañía asociada.


deliveryNotes.companyAssociated.zipCode string – obligatorio si factura a compañía asociada
Código postal de la compañía asociada.


deliveryNotes.companyAssociated.phone string – obligatorio si factura a compañía asociada
Número de teléfono de la compañía asociada.


deliveryNotes.companyAssociated.billingAddress string – obligatorio si factura a compañía asociada
Correo de facturación de la compañía asociada. 

8. Ejemplos y descargables

{
   "deliveryPoints":[
      {
         "id":"1050",
         "deliveryNotes":[
            {
               "deliveryNoteCode":"73289236431",
               "deliveryNoteObservation":"25-11",
               "showDeliveryNotePrice":true,
               "isBill": false,
               "kg":20,
               "volumen":100,
               "palets": 5,
               "packages": 6,
               "totalPrice":22.5
            }
         ]
      }     
         ]
      }