API Integration Guide

User guide to integrate PULPO WMS via API to your ERP or another software

Simon avatar
Written by Simon
Updated over a week ago

Introduction

This document gives Pulpo WMS customers some guidelines to integrate ERP systems. For better understanding, it is necessary to know swagger documentation. (See Getting Started with Swagger UI for more information)

There are 2 different types of data transfers:

  • From ERP to Pulpo WMS via integration

  • From Pulpo WMS to ERP:

  • Via integration

  • Registering to a webhook from PulpoWMS to ERP (Real-time updates)

Entity Overview

The next diagram shows an overview of the most important entities in Pulpo WMS. Note that not all associations are shown.

General API integration

Description of how to authorize to PULPO WMS and be able to make further API calls.

Authorization

The authorization in Pulpo WMS is done with an Oauth token which is used in the headers of later API calls.

A token is valid for 1 hour. 

Please do not request a new token for each API call. The system will ban your IP for a certain time and it will misbehave.

Please implement a fallback strategy for failure scenarios

Example request

curl --location --request POST 'https://eu-show.pulpo.co/api/v1/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "password",
"username" : "someuser",
"password" : "somepassword",
"scope" : "default"
}'

Response

{
"access_token": "7qZxedjvemt5eZcfJvqNlHxyAkFnvFdjAs",
"expires_in": 43200,
"scope": "default",
"token_type": "bearer"
}

Usage

curl --location --request GET 'https://eu-show.pulpo.co/api/v1/setting' \
--header 'Authorization: Bearer 7qZxedjvemt5eZcfJvqNlHxyAkFnvFdjAs' \
--header 'Content-Type: application/json' \

Basic data

To be able to create most of the data, the API needs the tenant_id. To get this and other basic data, please use the following endpoint:

Notice that warehouses must be assigned to a user in order to execute operations in each warehouse.

Get information about one or multiple warehouses. 

To search for multiple values please use brackets.

For example this query searches for the products 1456 and 1457:

/api/v1/inventory/products?id[]=1456&id[]=1457

Data transfer from your ERP to Pulpo WMS

The following data is usually synchronized from the ERP system to Pulpo WMS.

We recommend the following implementation:

  • One regular job to synchronize products creating the suppliers on the fly

  • One regular job to synchronize purchase orders creating the suppliers on the fly

  • One regular job to synchronize sales orders creating customers on the fly

Third parties - Customers and Suppliers

Products

Sales Orders

Purchase Orders

Data transfer from Pulpo WMS to your ERP

The following data is usually synchronized from the PULPO WMS system to the ERP system

We recommend the following implementation for the standard process covered in PULPO:

We recommend the following implementation for the standard process covered in PULPO:

  • For stock synchronization register the following webhooks with the following functionality:

  • counting_task_finished: depending on the response whether add or reduce stock in your ERP system

  • incoming_good_created: increase stock in your ERP system

  • sales_order_finished: reduce stock in your ERP system

  • beware of validating which products left actually the warehouse

  • For order updates register the following webhooks with the following functionality:

  • sales_order_finished: update the status of the order and register serials or lots if needed

  • purchase_order_finished: update the status of the order and register serials or lots if needed

  • For label generation register the following webhooks with the following functionality:

  • packing_order_finished

  • query packing boxes to receive the information about the shipment

  • generate the labels in the external system

  • attach the labels and shipment_tracking to each box. Only one label is allowed per box

Note that depending on the individuality of your process, this recommendation must be modified.

Stock

API:

Webhooks

Through webhooks, you can get real-time data from Pulpo WMS to another system by registering an API that receives and processes a specific payload

API:

Implementation help - Magento Plugin for Pulpo WMS

Client Code Generation

To speed up the implementation swagger-codegen offers the automatic generation of clients from a swagger json definition in different languages. 

Pulpo’s swagger json can be found in:

The list of supported languages can be found in: https://generator.swagger.io/api/gen/clients

The tool documentation can be found in: README.md 

An example of how to generate a javascript client from a Mac computer from the console:

brew install swagger-codegen 2 3swagger-codegen generate -i https://eu-show.pulpo.co/api/v1/swagger/wms.json -l javascript


Known issues from other integrations:

This plugin for Magento 2.0 may guide and help to integrate the following data:

  • Products

  • Sales orders

Files containing implementation guides:

PulpoWms/Controller/Index/Index.php: listener for Pulpo WMS webhooks

PulpoWms/Cron: Cron jobs to send sales orders and products from Magento to Pulpo WMS

PulpoWms/Helper/Data.php: Helper for the authentication process

You can download the Magento plugin from the Magento plugin store for free. Whenever you have questions, feel free to contact us!

Did this answer your question?