Overview

This guide shows some specifications for GET endpoints to search resources. Usually, a search endpoint in Pulpo WMS has the following structure

GET pulpo.co/api/v1/resource ? query_param1=value1 & query_param2=value2 & limit=100 & offset=0

the result has the following structure:

1 {
2    "resource": [
3        {
4            "attribute1": "value",
5            "another_attribute": "another_value"
6        }
7    ],
8    "total_results": 1
9 }

total_results

will show the number of total records in the query.

Query parameters

A query parameter could be:

Pagination parameter
Response parameter
Attribute parameter
Dinamic filter parameter

Pagination parameter

By default, all the search endpoints will be paginated if limit and offset are not set as query params:

If limit or offset are not specified the value for limit will be 10 and offset 0 and the total_results in the response will be the amount of total resources
if the limit is not 0 the total_results will be null

Parameters:

limit
- the limit sets the number of records that will be shown in the response
offset
- the offset sets the count record as the first element of the list in the response

Response parameters

The response parameters modify the JSON response

parameters:

sort_by - The result of the query will be sorted by the specified attribute in the resource.
- Support asc and desc as prefix
- Example GET all products and sort by sku /api/v1/inventory/products ? sort_by=sku:asc
view_attributes - Specifies the fields to be shown in the response
- Syntax: the attributes should be separated by a comma
  - view_attributes=attr1,attr2,attr3
- Endpoints: Only the following endpoints support view_attributes
  - search packing orders GET /api/v1/packing/orders
  - search picking orders GET /api/v1/picking/orders
  - search sales orders GET /api/v1/sales/orders
- Example GET all packing orders but only show sequence_number, id, and state in the response
  - /api/v1/packing/orders ? view_attributes=sequence_number,id,state
```
1 {
2    "packing_orders": [
3        {
4            "id": 23486,
5            "sequence_number": "PA-0000015",
6            "state": "closed"
7        },
8        {
9            "id": 23423,
10            "sequence_number": "PA-0000010",
11            "state": "queue"
12        },
13        {
14            "id": 23483,
15            "sequence_number": "PA-0000012",
16            "state": "closed"
17        }
18    ],
19    "total_results": 52
20 }
```

Attribute parameters

A query parameter could be an attribute of the resource and act as a filter by the value itself

Example

GET all products which the sku matches with “1734“
- GET /api/v1/inventory/products ? sku=1734

prefixes

some operations could be added as prefixes to match the records with attributes, the following are the prefixes supported by Pulpo

to_list - Filters the parameter by the match within a provided list of values. It behaves like IN clause
- Example
  - GET all products which the sku matches with the list “1734“, “1735”, “1736”
    GET /api/v1/inventory/products ? sku=to_list:1734,1735,1736

gt - filters the attribute to a value greater than the specified number value
- Example
  - GET all products which unit per sales package greater than 2
    GET /api/v1/inventory/products ? unit_per_sales_package=gt:2

gte - filters the attribute to a value greater than or equal to the specified number value
- Example
  - GET all products which unit per sales package greater or equal than 2
    GET /api/v1/inventory/products ? unit_per_sales_package=gte:2

lt - filters the attribute to a value lower than the specified number value
- Example: GET all products which unit per sales package lower than 2
  - GET /api/v1/inventory/products ? unit_per_sales_package=lt:2

lte - filters the attribute to a value lower than or equal to the specified number value
- Example: GET all products which unit per sales package lower or equal than 2
  - GET /api/v1/inventory/products ? unit_per_sales_package=lte:2

between - filters the attributes to a specified range of numeric values,
- Example: GET all products which unit per sales package lower between 3 and 6
  - GET /api/v1/inventory/products ? unit_per_sales_package=between:3,6

contains - filters the attribute to a record that contains the text specified in the value
- Example: GET all third parties which name contains Doe
  - GET /api/v1/iam/third_parties ? name=contains:Doe

starts_with - filters the attribute to a record that starts with the text specified in value
- GET all third parties which name starts with John
  - GET /api/v1/iam/third_parties ? name=starts_with:John

ends_with - filter the attribute to a record that ends with the text specified in the value
- Example: GET all third parties which name starts with Doe
  - GET /api/v1/iam/third_parties ? name=ends_with:Doe

like - filter the attribute to a record that contains the text specified in the value
- Example: GET all third parties which identifier number is like 7777
  - GET /api/v1/iam/third_parties ? identifier_number=like:77777

Dinamic filter parameters

A dynamic filter groups multiple attribute parameters and can be joined by AND/OR clause group by group. As a group of attribute parameters, dynamic filters are using static nomenclature in values.

The number of parameters and a number of values provided in the group should match exactly. E.G. ?__search=param_1,param2|value_1 will raise an exception due 2 parameters were provided and just only 1 value

parameters

__search - Group all static filters in the group with AND clauses. The whole group joins WHERE clause with AND clause.
- Example for GET all movements with state queue and type manual
- GET api/v1/replenishment/orders ? __search=state,type|queue,manual

__or_search - Group all static filters in the group with OR clauses. The whole group joins WHERE clause with OR clause
- Example GET all movements with state queue or type manual
  - GET api/v1/replenishment/orders ? __or_search=state,type|queue,manual

Queriable virtual attributes

There are some virtual attributes that are not part of the resources but are related. Those special attributes could be added as a query parameters to extend the search with dynamic filters.

The queriable virtual attributes supported are:

counter_name in counting task resource
event_status in event log resource
event_type in event log resource
owner_name in incoming goods
priority in picking order resource
product_name in stock thresholds resource
product_sku in stock thresholds resource
owner_name in replenishment orders

cart_box_barcode in packing order resource
duration in packing order resource
sales_order_num in packing order resource
origin_location_code in packing order resource
owner_name in packing order resource
third_party_name in packing order resource
third_party_name in purchase order resource

third_party_name in sales order resource
shipping_method_name in sales order resource
sales_order_num in shipping order resource
shipping_location_code in shipping order resource
third_party_id in shipping order resource
third_party_name in shipping order resource

Example: GET all packing orders performed by user “John Doe”

GET api/v1/packing/orders ? __search=owner_name|John Doe

Open mode endpoints

Some endpoints in API documentation are specified with the words “open mode”. Search in open mode means that all attribute params included as filter will act as an OR clause, in other words, the response will include every record that matches with any filter in the query params.

Endpoints in open-mode search

Search products in open mode GET /inventory/products/open

Example

GET all products which the name matches with “product_a” or matches with sku “p1234“
- GET /api/v1/inventory/products/open ? sku=p1234 & name=product_a

API Integration Guide

Assign attributes to products

User profiles in PULPO WMS

POS Integration

Statistics Dashboard