Search 1.9 billion lines of Odoo code on GitHub
stock_3pl_api
| Author: | Akretion,Odoo Community Association (OCA) |
|---|---|
| License: | AGPL-3 |
| Branch: | 12.0-add-stock-3pl-api |
| Repository: | akretion/stock-logistics-workflow |
| Dependencies: | auth_api_key, base_rest, base_rest_datamodel, component, datamodel, and delivery |
| Languages: | HTML (502, 35.2%), Python (595, 41.7%), XML (7, 0.5%), and reStructuredText (323, 22.6%) |
<h1 class="title">Stock 3PL Api</h1>
<p><a class="reference external" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/licence-AGPL--3-blue.png" /></a> <a class="reference external" href="https://github.com/OCA/stock-logistics-workflow/tree/12.0/stock_3pl_api"><img alt="OCA/stock-logistics-workflow" src="https://img.shields.io/badge/github-OCA%2Fstock--logistics--workflow-lightgray.png?logo=github" /></a> <a class="reference external" href="https://translation.odoo-community.org/projects/stock-logistics-workflow-12-0/stock-logistics-workflow-12-0-stock_3pl_api"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external" href="https://runbot.odoo-community.org/runbot/154/12.0"><img alt="Try me on Runbot" src="https://img.shields.io/badge/runbot-Try%20me-875A7B.png" /></a></p>
<a name="introduction"></a>
<h2>Introduction</h2>
<p>Third-party logistics (abbreviated as 3PL, or TPL) in logistics and supply chain management
is an organization's use of third-party businesses to outsource elements of its distribution,
warehousing, and fulfillment services. (Wikipedia)</p>
<p>This module exposes the convenient Odoo stock operations to a 3PL partner with a
<strong>REST API</strong>.
It means the 3PL partner should implement a <strong>REST API client</strong> in order to get Odoo
reflect the stock operations he does physically.
The OCA/wms/shopfloor module has been a source of inspiration. However this
module is simpler as it focuses on higher level operations compared to Shopfloor.</p>
<p>The service uses an <strong>API key</strong> in the HTTP header to authenticate the API user.
An API key is created in the Demo data (for development), using the Demo user.
This demo key to use in the HTTP header API-KEY is: 42D144F7BE780EBD</p>
<p>The API key is associated to an Odoo user and its permissions. You may take
advantage of this in the case of a multi-company set up.</p>
<p>The API exposes 1 main endpoint for consulting the catalog and the inventory:</p>
<ul class="simple">
<li>GET /stock-3pl-api/product</li>
</ul>
<p>and 4 main endpoints for consulting the pickings and processing them:</p>
<ul class="simple">
<li>GET /stock-3pl-api/picking</li>
<li>GET /stock-3pl-api/picking/<id></li>
<li>POST /stock-3pl-api/picking/<id>/done</li>
<li>POST /stock-3pl-api/picking/<id></li>
</ul>
<p>The usage of these endpoints is explained in the following sections.</p>
<p><strong>Table of contents</strong></p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#usage" id="id1">Usage</a></li>
</ul>
</div>
<a name="usage"></a>
<h3><a class="toc-backref" href="#id1">Usage</a></h3>
<a name="catalog-and-inventory"></a>
<h2>Catalog and Inventory</h2>
<p>First the 3PL partner can import the catalog and inventory from Odoo with the</p>
<dl class="docutils">
<dt>Product list endpoint::</dt>
<dd>GET /stock-3pl-api/product</dd>
<dt>Curl example::</dt>
<dd>curl -H "API-KEY: 42D144F7BE780EBD" <a class="reference external" href="http://localhost:8069/stock-3pl-api/product">http://localhost:8069/stock-3pl-api/product</a></dd>
</dl>
<p>The 3PL partner can typically use this to ensure that the Odoo stock levels
are consistent with its own inventory and warn you otherwise.</p>
<p>TODO what about an API point to warn Odoo about a stock level error?</p>
<dl class="docutils">
<dt>You can also consult a specific product with its id::</dt>
<dd>GET /stock-3pl-api/product/<id></dd>
<dt>Curl example::</dt>
<dd>curl -H "API-KEY: 42D144F7BE780EBD" <a class="reference external" href="http://localhost:8069/stock-3pl-api/product/10">http://localhost:8069/stock-3pl-api/product/10</a></dd>
</dl>
<p>You can also specify a specific stock_location_name to get the stock levels at
a specific location in case you have a more sophisticated multi-locations usage.
TODO document.</p>
<a name="purchase-orders-incoming-pickings"></a>
<h2>Purchase Orders / Incoming Pickings</h2>
<p>This module is mostly used to manage your product expeditions. But the 3PL partner
might also inform Odoo about the received products.
Reception works a bit the same as expedition but in fact it is simpler, so let's start talking
about the product reception API (or purchase orders).</p>
<p>The validation of an Odoo purchase orders in Odoo will create an incoming stock.picking
that we can import with the 3PL API:</p>
<a name="getting-the-list-of-receptions"></a>
<h3>Getting the list of receptions</h3>
<dl class="docutils">
<dt>picking list endpoint::</dt>
<dd>GET /picking</dd>
<dt>Curl example::</dt>
<dd>curl -H "API-KEY: 42D144F7BE780EBD" "<a class="reference external" href="http://localhost:8069/stock-3pl-api/picking">http://localhost:8069/stock-3pl-api/picking</a>?picking_type_name=Receipts&states=confirmed|assigned"</dd>
</dl>
<a name="stock-picking-filters"></a>
<h3>stock.picking filters</h3>
<p>You can filter these incoming pickings using the following parameters:</p>
<ul class="simple">
<li>picking_type_name: use 'Receipts' for reception but in fact you could manage any Odoo picking operation</li>
<li>states: a string with the value of the Odoo state picking field, or a list of values separated with |</li>
<li>date_from</li>
<li>date_to</li>
<li>id_3pl: use false to filter only the stock pickings with no id_3pl yet. Eventually you will later write an id_3pl in some pickings to help you filter</li>
</ul>
<dl class="docutils">
<dt>You can also consult a specific picking with::</dt>
<dd>GET /stock-3pl-api/picking/<id></dd>
</dl>
<a name="processing-a-stock-picking"></a>
<h3>Processing a stock.picking</h3>
<p>When the products are received, you can simply set the picking to the 'done'
state with all the planed quantities with the:</p>
<dl class="docutils">
<dt>set to done picking endpoint::</dt>
<dd>POST /stock-3pl-api/picking/<id>/done?force_reserved_quantities=true</dd>
</dl>
<p>If you don't specify force_reserved_quantities=true, only the reserved quantities
will be processed, see later how you can inform these reserved quantities with
the API.</p>
<dl class="docutils">
<dt>Curl example::</dt>
<dd>curl -X POST -H "API-KEY: 42D144F7BE780EBD" <a class="reference external" href="http://localhost:8069/stock-3pl-api/picking/9/done?force_reserved_quantities=true">http://localhost:8069/stock-3pl-api/picking/9/done?force_reserved_quantities=true</a></dd>
</dl>
<p>You can ensure in the response that the picking state is 'done'.</p>
<p>But instead you might likely want to inform the processed quantities and eventually
leave a back order to process later.
For this you should first consult the id of the planed stock.move of the picking
in order to inform the done quantity for each move. The field with the list of
planed moves is called 'move_ids_without_package'.</p>
<p>You can consult these move ids either from the picking list either with:</p>
<dl class="docutils">
<dt>The picking detail endpoint::</dt>
<dd>GET /stock-3pl-api/picking/<id></dd>
</dl>
<p>So suppose you you have a single move an id 36 and with a planed move quantity of 35.
If you want to inform you processed only 30 products, you can use:</p>
<dl class="docutils">
<dt>set to done picking endpoint with detailed quantities::</dt>
<dd>POST /stock-3pl-api/picking/<id>/done --data '{"moves":[{"id":<move_id>, "quantity_done": <move_qty>}, ...]}'</dd>
<dt>Curl example::</dt>
<dd>curl -X POST -H "API-KEY: 42D144F7BE780EBD" --header "Content-Type: application/json" --data '{"moves":[{"id":36, "quantity_done": 30}]}' "<a class="reference external" href="http://localhost:8069/stock-3pl-api/picking/26/done">http://localhost:8069/stock-3pl-api/picking/26/done</a>"</dd>
</dl>
<p>See the API specification detail in Swagger or Postman for all the options.</p>
<p>With such a command you will leave a backorder open for later reception,
after setting the picking to done, you will get the list of open backorder ids
in the <strong>backorder_ids</strong> response parameter.</p>
<p>If instead you don't want to leave any open backorder, you can pass the
cancel_backorder=true parameter. In this case you may still have a backorder
after processing a picking, but its state will be "cancel" so it won't be
active.</p>
<p>Updating reserved quantity or other picking information without actually
processing the picking can be achieved using the update endpoint that
accepts similar parameters as the the done endpoint.</p>
<dl class="docutils">
<dt>update endpoint::</dt>
<dd>POST /stock-3pl-api/picking/<id></dd>
<dt>Curl example::</dt>
<dd>curl -X POST -H "API-KEY: 42D144F7BE780EBD" --header "Content-Type: application/json" --data '{"moves":[{"id":31, "quantity_done": 30}]}' "<a class="reference external" href="http://localhost:8069/stock-3pl-api/picking/21">http://localhost:8069/stock-3pl-api/picking/21</a>"</dd>
</dl>
<p>See the API specification detail for all the options.
You can then use the "/POST done" endpoint to process the picking in this case
you don't need to repeat the moves details when setting the picking to done.</p>
<a name="sale-orders-outgoing-pickings"></a>
<h2>Sale Orders / Outgoing Pickings</h2>
<p>Managing the product expeditions is very similar to managing the product reception
as explained in the previous section, except it is more complex because of
the packages and tracking information.</p>
<p>the validation of sale orders in Odoo will create outgoing stock.picking that
we can import in 3PL using the <strong>GET /picking endpoint</strong>.</p>
<dl class="docutils">
<dt>Curl example::</dt>
<dd>curl -H "API-KEY: 42D144F7BE780EBD" "<a class="reference external" href="http://localhost:8069/stock-3pl-api/picking?picking_type_name=Delivery&states=assigned">http://localhost:8069/stock-3pl-api/picking?picking_type_name=Delivery&states=assigned</a>"</dd>
</dl>
<p><strong>filters</strong>: you can use the same filters as for the incoming pickings described
in the previous section. Notice that for delivery we use <strong>picking_type_name=Delivery</strong>.
If you filter using states=assigned you will get only deliveries with enough stock
to be processed. Instead you can use states=confirmed|assigned if you want also
the confirmed pickings with not enough stock.</p>
<p>Another filter you may want to use is <strong>id_3pl=false</strong> to get only the new
deliveries for which you have not assigned any id_3pl yet.</p>
<p>You can simply process the delivery pickings with the <strong>/done and /update endpoints</strong>
just like for incoming pickings.</p>
<a name="packaging-and-tracking-information"></a>
<h3>Packaging and tracking information</h3>
<p>But one important thing you can do is set packages and tracking information
if you need.</p>
<p>To do this you should not simply pass the quantity done for each picking move,
but you should instead detail for each move, the list of packages,
with the package ref, quantity, weight and tracking_url eventually.</p>
<p>For instance::
curl -X POST -H "API_KEY: 42D144F7BE780EBD" --header "Content-Type: application/json" --data '{"moves":[{"id":11, "lines":[{"quantity": 5, "package": {"ref": "box1"}}, {"quantity": 10, "package": {"ref": "box2"}}]}]}' "<a class="reference external" href="http://localhost:8069/stock-3pl-api/picking/1/done">http://localhost:8069/stock-3pl-api/picking/1/done</a>"</p>
<p>TODO picture links</p>
<p>And also you can use /update endpoint instead to update the picking detail without
actually processing it yet. And you can process it later using /done.
See the API specification for the details.</p>
<p>backorders are handled the same way as for incoming pickings.</p>
<a name="bug-tracker"></a>
<h3>Bug Tracker</h3>
<p>Bugs are tracked on <a class="reference external" href="https://github.com/OCA/stock-logistics-workflow/issues">GitHub Issues</a>.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us smashing it by providing a detailed and welcomed
<a class="reference external" href="https://github.com/OCA/stock-logistics-workflow/issues/new?body=module:%20stock_3pl_api%0Aversion:%2012.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**">feedback</a>.</p>
<p>Do not contact contributors directly about support or help with technical issues.</p>
<a name="credits"></a>
<h3>Credits</h3>
<a name="authors"></a>
<h2>Authors</h2>
<ul class="simple">
<li>Akretion</li>
</ul>
<a name="contributors"></a>
<h2>Contributors</h2>
<ul class="simple">
<li>Raphaël Valyi <<a class="reference external" href="mailto:raphael.valyi@akretion.com.br">raphael.valyi@akretion.com.br</a>></li>
</ul>
<a name="maintainers"></a>
<h2>Maintainers</h2>
<p>This module is maintained by the OCA.</p>
<a class="reference external image-reference" href="https://odoo-community.org"><img alt="Odoo Community Association" src="https://odoo-community.org/logo.png" /></a>
<p>OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.</p>
<p>Current <a class="reference external" href="https://odoo-community.org/page/maintainer-role">maintainer</a>:</p>
<p><a class="reference external" href="https://github.com/rvalyi"><img alt="rvalyi" src="https://github.com/rvalyi.png?size=40px" /></a></p>
<p>This module is part of the <a class="reference external" href="https://github.com/OCA/stock-logistics-workflow/tree/12.0/stock_3pl_api">OCA/stock-logistics-workflow</a> project on GitHub.</p>
<p>You are welcome to contribute. To learn how please visit <a class="reference external" href="https://odoo-community.org/page/Contribute">https://odoo-community.org/page/Contribute</a>.</p>