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 quantity 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 limit is not 0 the total_results will be null

Parameters:

  • limit

    • the limit sets the amount of records that will be shown in the response

  • offset

    • the offset sets the count record as first element of the list in the response

Response parameters

The response parameters modifies the JSON response

parameters:

  • sort_by - The result of 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 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 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 grather 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 grather than or equal 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 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 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 start 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 end with the text specified in 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 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 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 was 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 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 which are not part of the resources but are related. Those special attributes could be added as query parameter to extend the search with dinamic 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

Did this answer your question?