Jobs

Placing an order

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
Request JSON Object:
 
  • uuids (string[]) – Array of uuids of product intentions for which orders need to be placed.
Response JSON Array of Objects:
 
  • uuid (string) – Product intention uuid this job is for.
  • job (object) – Object describing the created job. Has a uuid-field.
Status Codes:
  • 200 OK – yields a list of product intentions.
  • 400 Bad Request – when an invalid set of uuids was provided.

Example request:

POST /product_api/v1/jobs/order
Host: planviewer.nl
Accept: application/json
Content-Type: application/json
{
  "uuids": ["0fe30323-a86e-4048-a7e7-6d60c3365dcb"]
}

Example response:

[
  {
    "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 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:
HTTP/1.1 429 TOO MANY REQUESTS

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

Retrieving status

GET /product_api/v1/jobs/status

View the status of a set of jobs.

Parameters:
  • uuids[] (string) – Uuid of job.
Response JSON Array of Objects:
 
  • uuid (string) – Uuid of job.
  • status (string) – Status of job, either initial, in_progress, finished, waiting for user or error.
  • progress (object) – 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 Codes:
  • 200 OK – yields a list of jobs and their status.
  • 400 Bad Request – when an invalid set of uuids was provided.

Example request:

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

Example response:

[
  {
    "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 Waiting for user:

Retrieving result

GET /product_api/v1/jobs/retrieve/(string: uuid)

Retrieve the result of a job.

Parameters:
  • uuid (string) – Uuid of job.
Status Codes:
  • 200 OK – yields the result of the job as a downloadable file.
  • 403 Forbidden – you are not authorized to retrieve the result of this job.
  • 404 Not Found – job did not finish (successfully).

Example request:

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

Example response:

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"