.. _bin-locations-api:

Bin Locations API
=================

The ``/api/binLocations`` endpoint exposes the :ref:`Bin Location Model <bin-location-model>` as a resource. Bin locations represent individually identifiable shelf spaces or boxes within a warehouse which can hold product stock.

.. http:get:: /api/binLocations

    Query all bin locations or a subset of bin locations according to a set of criteria. This endpoint returns a plain
    representation of bin locations which does not include the mapping of products to the bin locations and their
    associated stock quantities. To retrieve this type of information, the :ref:`single-bin-location endpoint <get-bin-location>`
    must be used instead.

    :query integer start: the starting offset into the result list (default: 0)
    :query integer limit: the maximum number of results (default: 1000)
    :query object filter: a search filter (see :ref:`filter_and_sort_query_parameters`), with property names prefixed
        by ``binLocation.``, for example ``binLocation.code``
    :query object sort: a sorting specification (see :ref:`filter_and_sort_query_parameters`), with property names
        prefixed by ``binLocation.``, for example ``binLocation.code``

    :>json boolean success: whether the operation was successful
    :>json integer total: the total number of bin locations which matched the query
    :>json array data: an array of bin locations
    :>json integer data[*].id: the database ID of the bin location
    :>json integer data[*].warehouseId: the database ID of the warehouse this bin location is located within
    :>json string data[*].code: the shorthand code of the bin location

    **Example request**:

    .. http:example:: curl wget httpie

        GET /api/binLocations?filter%5B0%5D%5Bproperty%5D=binLocation.code&filter%5B0%5D%5Bvalue%5D=A01 HTTP/1.1
        Host: localhost
        Accept: application/json

    **Example response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "success": true,
            "data": [
                {
                    "id": 12,
                    "warehouseId": 1,
                    "code": "A01"
                }
            ],
            "total": 1
        }

.. _get-bin-location:

.. http:get:: /api/binLocations/{id}

    Fetch a single bin location by its database ID as well as any product stock mapped to it.

    :param integer id: the database ID of the bin location to fetch

    :>json boolean success: whether the operation was successful
    :>json object data: the bin location with the given ID
    :>json integer data.id: the database ID of the bin location
    :>json integer data.warehouseId: the database ID of the warehouse this bin location is located within
    :>json string data.code: the shorthand code of the bin location
    :>json array data.articleDetailBinLocationMappings: an array of article detail (product) mappings for this bin
        location
    :>json integer data.articleDetailBinLocationMappings[*].id: the database ID of the bin location mapping
    :>json integer data.articleDetailBinLocationMappings[*].binLocationId: the database ID of the bin location
    :>json integer data.articleDetailBinLocationMappings[*].articleDetailId: the database ID of the article detail
        (product) being mapped to this bin location
    :>json integer data.articleDetailBinLocationMappings[*].stock: the number of pieces of the mapped article detail
        (product) which currently reside on this bin location
    :>json boolean data.articleDetailBinLocationMappings[*].defaultMapping: whether this is the default bin location
        for this article detail (product)
    :>json integer data.articleDetailBinLocationMappings[*].reservedStock: the number of pieces of the mapped article
        detail (product) which reside on this bin location, but are reserved for ongoing picking processes
    :>json timestamp data.articleDetailBinLocationMappings[*].lastStockTake: the timestamp of the last time the stock
        quantity of the mapped article detail (product) was manually verified on this bin location

    **Example request**:

    .. http:example:: curl wget httpie

        GET /api/binLocations/12 HTTP/1.1
        Host: localhost
        Accept: application/json

    **Example response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "success": true,
            "data": {
                "id": 12,
                "warehouseId": 1,
                "code": "A-01",
                "articleDetailBinLocationMappings": [
                    {
                        "id": 56,
                        "binLocationId": 12,
                        "articleDetailId": 34,
                        "stock": 50,
                        "defaultMapping": false,
                        "reservedStock": 0,
                        "lastStockTake": "2019-01-03T14:23:12+0200"
                    }
                ]
            }
        }

.. http:post:: /api/binLocations

    Create a new bin location.

    :<json integer warehouseId: the database ID of the warehouse this bin location should be created in
    :<json string code: the shorthand code of the bin location. This must be unique within the warehouse and must not be ``pickware_null_bin_location``.

    **Example request**:

    .. http:example:: curl wget httpie

        POST /api/binLocations HTTP/1.1
        Content-Type: application/json
        Host: localhost

        {
            "warehouseId": 1,
            "code": "A01-A01"
        }

    **Example response**:

    .. code-block:: http

        HTTP/1.1 201 Created
        Content-Type: application/json

        {
            "success": true,
            "data": {
                "id": 12,
                "location": "https://localhost/api/binLocations/12"
            }
        }

.. http:put:: /api/binLocations/{id}

    Update the bin location with the given database ID using the data in the request body.

    :param integer id: the database ID of the bin location to update

    :<json string code: the shorthand code of the bin location. This must be unique within the warehouse and must not be
        ``pickware_null_bin_location``.

    **Example request**:

    .. http:example:: curl wget httpie

        PUT /api/binLocations/12 HTTP/1.1
        Content-Type: application/json
        Host: localhost

        {
            "code": "A01-A02"
        }

    **Example response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "success": true
        }

.. http:delete:: /api/binLocations/{id}

    Delete the bin location with the given database ID.

    :param integer id: the database ID of the bin location to delete
    :statuscode 400: if the bin location cannot be deleted because it still has stock or it is the default bin location
        for a product

    **Example request**:

    .. http:example:: curl wget httpie

        DELETE /api/binLocations/12 HTTP/1.1
        Host: localhost

    **Example response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "success": true
        }
