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 REQUIREDRequest 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
orerror
. - 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"