Jobs
----

.. _placing-an-order:

Placing an order
^^^^^^^^^^^^^^^^
.. http:post:: /product_api/v1/jobs/order

    Place an order for a product intention, subsequently creating a job.

    .. note::
        Your account must have payment on account enabled. Without payment on account it will not be possible to order directly through Product API.
        Trying to place an order will result in the following response:

            HTTP/1.1 402 HTTP PAYMENT REQUIRED


    :<json string[] uuids: Array of uuids of product intentions for which orders need to be placed.

    :>jsonarr string uuid: Product intention uuid this job is for.
    :>jsonarr object job: Object describing the created job. Has a **uuid**-field.

    :status 200: yields a list of product intentions.
    :status 400: when an invalid set of uuids was provided.

    **Example request**:

    .. sourcecode:: http

      POST /product_api/v1/jobs/order
      Host: planviewer.nl
      Accept: application/json
      Content-Type: application/json

    .. sourcecode:: json

      {
        "uuids": ["0fe30323-a86e-4048-a7e7-6d60c3365dcb"]
      }

    **Example response**:

    .. sourcecode:: json

      [
        {
          "uuid": "0fe30323-a86e-4048-a7e7-6d60c3365dcb",
          "job": {
            "uuid": "9dee3afd-3079-47e0-91f1-ab6e1d58f11a"
          }
        }
      ]

    .. note::
        During integration please note that any costs Planviewer makes for products where we make use of a third party integration will be charged to the customers account.

    **Order Cap**:
    A mistake can easily be made and can have unwanted consequences. To prevent such mistakes with the Product API we have set a cap on the number of daily orders placed.
    This cap is set by default on 10 for the integration period and will be set to the expected usage (with extra margin) for production.

    The cap can be changed by `contacting <https://www.planviewer.nl/contact>`_ Planviewer.

    When you have reached your cap, you will be notified by e-mail.
    After this you can still place a few orders to give you some time to contact us and raise the cap.
    If you do reach the daily limit the order will not be placed and you will get another response:

     **Example response**:

    .. sourcecode:: http

      HTTP/1.1 429 TOO MANY REQUESTS

          [
            {
              "error": "true",
              "message": "You are trying to order more products than your daily limit allows"
            }
          ]




Retrieving status
^^^^^^^^^^^^^^^^^
.. _recievingStatus:
.. http:get:: /product_api/v1/jobs/status

    View the status of a set of jobs.

    :param string uuids[]: Uuid of job.

    :>jsonarr string uuid: Uuid of job.
    :>jsonarr string status: Status of job, either `initial`, `in_progress`, `finished`, `waiting for user` or `error`.
    :>jsonarr object progress: With fields **current** and **total**. Absolute number of steps until completion.
      Can be used to create a progress bar. Each step can take a variable amount of time. The number of steps and
      the time spent in each step varies for each product intention.

    :status 200: yields a list of jobs and their status.
    :status 400: when an invalid set of uuids was provided.

    **Example request**:

    .. sourcecode:: http

      GET /product_api/v1/jobs/status?uuids%5B%5D=9dee3afd-3079-47e0-91f1-ab6e1d58f11a
      Host: planviewer.nl
      Accept: application/json

    **Example response**:

    .. sourcecode:: json

      [
        {
          "uuid": "9dee3afd-3079-47e0-91f1-ab6e1d58f11a",
          "status": "finished",
          "progress": {
            "current": 6,
            "total": 6
          }
        }
      ]

    .. note::
        When you receive the status `waiting for user` there is an action required from the end-user to complete the order.
        See :ref:`Waiting for user <waitingforuser>`:

Retrieving result
^^^^^^^^^^^^^^^^^
.. _Retrieving result:

.. http:get:: /product_api/v1/jobs/retrieve/(string:uuid)

    Retrieve the result of a job.

    :param string uuid: Uuid of job.

    :status 200: yields the result of the job as a downloadable file.
    :status 403: you are not authorized to retrieve the result of this job.
    :status 404: job did not finish (successfully).

    **Example request**:

    .. sourcecode:: http

      GET /product_api/v1/jobs/retrieve/9dee3afd-3079-47e0-91f1-ab6e1d58f11a
      Host: planviewer.nl

    **Example response**:

    .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/pdf
      Content-Length: 1429793
      Content-Transfer-Encoding: binary
      Content-Disposition: attachment; filename="20180111_test_example_product_utrechtsestraat_61_6811lw_arnhem_nl_imro_0268_fbpparkeren_vg01.pdf"