Waiting for user
----------------

.. _waitingforuser:

Some KIK API products may require clarification on locations in order to generate the correct product.
In this cases the product will return a `waiting for user` status.
When this status occurs we require that a choice is made between 2 or more locations that have a relation to the original location.

For example when ordering `eigendomsinformatie` for a certain address it is possible to receive this status. In this example 2 percelen
are part of this address. in order to complete the order a perceel has to be chosen to continue.

When receiving `waiting for user` status please retrieve the location list to start the clarification process

status: waiting for user >> :ref:`Waiting for user location list <waitingforuserlist>`: >> :ref:`Post chosen location <postlocation>`: >> :ref:`status order <recievingStatus>`: >> :ref:`Download completed order <Retrieving result>`:


Waiting for user location list
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _waitingforuserlist:
.. http:get:: product_api/v1/kik/waiting/(string:uuid)

    View the list of related locations.

    :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/kik/waiting/e0ff72f8-ed75-44f8-8bff-d31a7088acc2
      Host: planviewer.nl

    **Example response**:

    .. sourcecode:: http

      {
        "locaties": {
            "1": "Hoogkerk A 100 Dorpsweg 8 a 9999AA Groningen t.n.v. J. Jansen",
            "2": "Hoogkerk A 101 Dorpsweg 8 9999AA Groningen t.n.v. Jo. de Jong"
        },
        "message": "Which of the found locations must be used to complete te order?"
      }

    .. note::
        The example above uses non-existent locations



Post chosen location
^^^^^^^^^^^^^^^^^^^^
.. _postLocation:
.. http:post:: product_api/v1/kik/select/(string:uuid)

    Post index of selected location

    :param string uuid: Uuid of job.
    :<json integer[] select: index of the location chosen from the :ref:`locations list<waitingforuserlist>`:.

    **Example request**:

    .. sourcecode:: http

      POST /product_api/v1/kik/select/e0ff72f8-ed75-44f8-8bff-d31a7088acc2
      Host: planviewer.nl
      Accept: application/json
      Content-Type: application/json

    .. sourcecode:: json

      {
        "select":2
      }


    **Example response**:

    .. sourcecode:: json

      {
        "uuid": "e0ff72f8-ed75-44f8-8bff-d31a7088acc2",
        "message": "Generation resumed with new location. use status with this uuid to check progress and completion"
      }

    .. note::
        in the example above the end-user choice the location with index 2
        *[see example waiting for user location list]*

            "1": "Hoogkerk A 100 Dorpsweg 8 a 9999AA Groningen t.n.v. J. Jansen",

            **"2": "Hoogkerk A 101 Dorpsweg 8 9999AA Groningen t.n.v. Jo. de Jong"**


    .. note::
        Once the chosen location has been passed the order will automatically continue being generated.
        User :ref:`status order call <recievingStatus>`: to check on generation progress.