Items
-----

This API allows listing, retrieving, creating, updating,
and deleting items (products). Items are identified by their UUID.


List Items
..........

.. http:get:: /item/

   List all items.

   **Sample request**:

   .. sourcecode:: http

      GET /item/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Accept: application/json

   :query sortedBy:  Available sorting criteria: ``name``
   :query name: A filtering value for item name
   :query partNumber: A filtering value for partNumber
   :query taxable: A filtering value for taxable
   :query glAccount: A filtering value for glAccount
   :query archived: A filtering value for archived

   **Sample response**:

   .. sourcecode:: http

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

      {
        "count": 100,
        "items": [
          {
            "name": "Heaney Menvier screw",
            "partNumber": "5151191313252",
            "uuid": "003813d3f9164e19bf17d5f67ff4fa12",
            "archived": false,
            "link":
              {
                "rel": "detail",
                "url": "https://api.fieldaware.net/item/003813d3f9164e19bf17d5f67ff4fa12"
              }
          },
          {
            "name": "Beier Apollo drill",
            "partNumber": "8005385953623",
            "uuid": "00ff8f446aba4387b5b570d146ac1457",
            "archived": true,
            "link":
              {
                "rel": "detail",
                "url": "https://api.fieldaware.net/item/00ff8f446aba4387b5b570d146ac1457"
              }
          },
        ],
        "page": 0,
        "pageSize": 2,
        "sortedBy": []
      }

   :>json int count: total number of items
   :>json array items: array of JSON Objects - items
   :>json int page: page number
   :>json int pageSize: page size
   :>json array sortedBy:

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 401 AuthenticationError
      Content-Type: application/json

      {
        "error": {
          "name": "Error identifier",
          "message": "Error description",
        }
      }

   :statuscode 401: AuthenticationError. The client failed to authenticate, typically because the API token was either invalid or not included in the request.
   :statuscode 404: NotFoundError. A specified resource does not exist.
   :statuscode 400: BadRequest. The payload is syntactically malformed for example, the inputs are not encoded as JSON.
   :statuscode 422: APIValidationError. The query parameters and/or body is not valid for this request. This error captures violation of structural assumptions made on the inputs, as captured by the different schemas that are included in this documentation.


Get Item
........

.. http:get:: /item/(item_ref)

   Retrieve a given item.

   **Sample request**:

   .. sourcecode:: http

      GET /item/003813d3f9164e19bf17d5f67ff4fa12 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

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

      {
        "description": "",
        "glAccount": null,
        "markupType": "fixed",
        "markupValue": 52.0,
        "name": "PBeta",
        "partNumber": null,
        "taxable": true,
        "trackOnVan": false,
        "unitCost": 749.99,
        "unitPrice": 801.99,
        "uuid": "85f118098f0c4a0d8d8615a8f709a705",
        "customFields": {},
        "archived": false
      }

   :>json string description: Description of the item
   :>json string glAccount: Customer glAccount, string or null if the account is not set
   :>json string markupType: markup type
   :>json number markupValue: markup value
   :>json string partNumber: string or null if the part number is not set
   :>json string name: name of the product/item
   :>json string partNumber: string or null if the part number is not set
   :>json bool taxable: indicates if the product/item is taxable
   :>json bool trackOnVan: track on van TODO: add description
   :>json number unitCost: unit cost
   :>json number unitPrice: price of the product/item unit
   :>json string uuid: UUID number of the product/item
   :>json obj customFields: JSON Obj, custom fields of the item
   :>json bool archived: Archived status of the item


Create Item
...........

.. http:post:: /item/

   Create a new minimal item.

   **Sample request**:

   .. sourcecode:: http

      POST /item/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

      {
        "name": "Name of the item",
      }

   :<json string name: Name of the item (required).


   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 NO CONTENT


.. http:post:: /item/

   Create a new item.

   **Sample request**:

   .. sourcecode:: http

      POST /item/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

      {
        "name": "Drill",
        "description": "Drill",
        "partNumber": "SB-009/23",
        "trackOnVan": false,
        "unitCost": 10.23,
        "unitPrice": 10.23,
        "markupType": "fixed",
        "markupValue": 20.34,
        "taxable": false,
        "glAccount": "acc 009",
        "tax1": {
          "group": "taxGr2",
          "name": "tax-004"
        },
        "tax2": {
          "group": "taxGr1",
          "name": "tax-003"
        },
        "customFields": {
          "85f118098f0c4a0d8d8615a8f709a705": true
        },
      }

   :<json string name: Name of the item (required).
   :<json string description: Description of the item.
   :<json string partNumber: Part number of the item.
   :<json bool trackOnVan: Whether the item will be tracked on a van.
   :<json number unitCost: The unit cost of the item.
   :<json number unitPrice: The unit price of the item.
   :<json string markupType: The markup type of the item. One of ``fixed``, ``percentage``
   :<json number markupValue: The markup type of the item.
   :<json bool taxable: Whether the item is taxable.
   :<json string glAccount: General Ledger account of the item.
   :<json obj tax1: Only applicable when tax system of business is non-US.
   :<json obj tax2: Only applicable when tax system of business is non-US.
   :<json obj customFields: Mapping of declaration keys to values.


.. http:post:: /item/

   Attempt to create a new item without required parameters to perform calculations.

   **Sample request**:

   .. sourcecode:: http

      POST /item/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

      {
        "name": "Item 4299045093",
        "description": "Description 4c388c56c2c75e89575e",
        "partNumber": "part: 7bb9c463-f7f6-4858-a108-386e51f66d57",
        "trackOnVan": false,
        "taxable": false,
        "unitCost": 111.52
      }

   :<json string name: Name of the item (required).
   :<json string description: Description of the item
   :<json string partNUmber: Part number
   :<json boolean trackOnVan: Indicates if the item is tracked
   :<json boolean taxable: Indicates if the item is taxable
   :<json number unitCost: Cost of the unit item

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 409 CONFLICT
      Content-Type: application/json

      {
        "error": {
          "message": "Not enough values for calculation.",
          "name": "ConflictError"
        }
      }

   :statuscode 409: Indicates conflict error
   :>json obj error: JSON object with error message and error name

Update Item
...........

.. http:put:: /item/(item_ref)

   Update a given item.

   Archived items can not be updated. Attempts to update an archived item result in a HTTP 409 Conflict error.

   **Sample request**:

   .. sourcecode:: http

      PUT /item/85f118098f0c4a0d8d8615a8f709a705 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json

   Request body is the same as `Create Item`_, with all properties being optional.

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 No Content

   :statuscode 204: Indicates the item was updated successfully.

Archive Item
...........
.. http:put:: /item/(item_ref)

   Make a PUT request with data containing only the ``archived`` key to archive or unarchive a given item.

   **Sample request**:

   .. sourcecode:: http

      PUT /item/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

      {
        "archived": true
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 No Content

   :statuscode 204: Indicates the item was archived or unarchived successfully.

Delete Item
...........

.. http:delete:: /item/(item_ref)

   Delete a given item.

   **Sample request**:

   .. sourcecode:: http

      DELETE /item/85f118098f0c4a0d8d8615a8f709a705 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40

   :reqheader Authorization: Authorization token

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 No Content

   :statuscode 204: Indicates the item was deleted successfully.