.. _quotes:

Quotes
------

Conceptually, there are two types of quotes: Web Quotes and Field Quotes.  The
main difference is that only Field Quotes are capable of being scheduled and
thus only Field Quotes API accepts fields pertaining to scheduling.

Except where otherwise stated (e.g. state field/parameter), all the fields
names and semantics correspond to that of jobs API endpoint.

Currently, Quotes API does not provide facilities for:

 - Accepting/rejecting a quote
 - Invoicing a quote
 - Cloning a quote
 - Converting a quote into a job

List Web Quotes
...............

.. http:get:: /webquote/

    **Sample Request**

    .. sourcecode:: http

        GET /webquote/?pageSize=2 HTTP/1.1
        Accept: */*
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

    :query start: starting date
    :query end: end date
    :query sortedBy: Available sorting criteria: ``createdOn``
    :query location: filtered by ``location``
    :query state: Available filtering criteria: ``pending``, ``accepted``, ``rejected``

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 200 OK
        Content-Length: 491
        Content-Type: application/json
        Date: Wed, 18 May 2016 09:43:28 GMT
        Link: <https://api.fieldaware.net/webquote/?page=0&pageSize=2>; rel=first,<https://api.fieldaware.net/webquote/?page=2&pageSize=2>; rel=last,<https://api.fieldaware.net/webquote/?page=1&pageSize=2>; rel=next
        Server: Werkzeug/0.9.4 Python/2.7.8

        {
            "count": 4,
            "items": [
                {
                    "completedOn": null,
                    "createdOn": "2016-05-18T09:21:49+00:00",
                    "location": {
                        "uuid": "0b94677f78704798b09a9881811c7e24"
                    },
                    "startedOn": null,
                    "state": "rejected",
                    "uuid": "f883546a755947769e631a681ca56b32",
                    "link": {
                        "rel": "detail",
                        "url": "https://api.fieldaware.com/webquote/f883546a755947769e631a681ca56b32",
                    }
                },
                {
                    "completedOn": null,
                    "createdOn": "2016-05-18T09:21:48+00:00",
                    "location": {
                        "uuid": "aa06f520fded4211badd4da9151b16b3"
                    },
                    "startedOn": null,
                    "state": "accepted",
                    "uuid": "699c2c10bbfc442ba615915ebc5be690",
                    "link": {
                        "rel": "detail",
                        "url": "https://api.fieldaware.com/webquote/699c2c10bbfc442ba615915ebc5be690",
                    }
                }
            ],
            "page": 0,
            "pageSize": 2,
            "sortedBy": [
                "-createdOn"
            ]
        }

    :statuscode 200: no error


Get a Web Quote
...............

.. http:get:: /webquote/(webquote_ref)

    **Sample Request**

    .. sourcecode:: http

        GET /webquote/f883546a755947769e631a681ca56b32 HTTP/1.1
        Accept: */*
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 200 OK
        Content-Length: 4281
        Content-Type: application/json
        Date: Wed, 18 May 2016 09:57:29 GMT
        Server: Werkzeug/0.9.4 Python/2.7.8

        {
            "completedOn": null,
            "contact": {
                "emailAddress": "treichel@gmail.com",
                "name": "Tyrese",
                "surname": "Reichel",
                "telno": null,
                "uuid": "6f130c2a040c4d6196f5b41459d87579"
            },
            "createdOn": "2016-05-18T09:21:49+00:00",
            "customFields": {
                "22a84f64c520459ea8cd8adcd45d1197": "f883546a755947769e631a681ca56b32",
                "457546ab958b4bbe8c9d4e0ca5207a21": 73.9
            },
            "customer": {
                "customerId": 2,
                "name": "SmugYou",
                "uuid": "8e2fcdd94cc848f0ab714a1f7cd68bec"
            },
            "description": "",
            "estDuration": null,
            "invoice": null,
            "location": {
                "country": "United States",
                "locality": "South Roy",
                "name": "SmugYou Depot",
                "postcode": null,
                "region": "NV",
                "streetName": "42884 Ralph Ranch",
                "uuid": "0b94677f78704798b09a9881811c7e24"
            },
            "pre_signature": null,
            "quoteId": "Q4",
            "revenue": 2040.7562,
            "signature": null,
            "startedOn": null,
            "state": "rejected",
            "tasks": [
                {
                    "asset": null,
                    "assignee": null,
                    "attachments": [],
                    "done": false,
                    "items": [
                        {
                            "item": {
                                "description": "Curabitur aliquam ante ut nulla mattis tempor. Quisque risus sem. Unicode: Ä",
                                "name": "Dickinson Vantage heads",
                                "uuid": "32617ac6ce244db1873a56b24556c191"
                            },
                            "quantity": 1,
                            "unitCost": 22.31,
                            "unitPrice": 25.8796,
                            "uuid": "ab1f550b540a4c2eb09674e3ee732223"
                        },
                        {
                            "item": {
                                "description": "Curabitur aliquam ante ut nulla mattis tempor. Quisque risus sem. Unicode: Ä",
                                "name": "Cremin Turbo bulb",
                                "uuid": "11017876d7254ddca495b0515d70a8f5"
                            },
                            "quantity": 2,
                            "unitCost": 0.0,
                            "unitPrice": 0.0,
                            "uuid": "b7e81ed3bfec461d81c6f820eb3a3a03"
                        }
                    ],
                    "note": null,
                    "task": {
                        "description": "eum hic suscipit facere iure nobis numquam repudiandae qui eius est deleniti culpa qui laborum repellat nostrum dolore quis aut ut eum illum assumenda distinctio aut dignissimos nulla consectetur quaerat blanditiis atque nihil ut rerum voluptas vel vel qu",
                        "name": "Remove Schuster heat detector",
                        "uuid": "b206c4f5acde4233b057e95d513ffe56"
                    },
                    "unitCost": 590.13,
                    "unitPrice": 631.13,
                    "uuid": "427201bbd50e480fa4a3931bd72c6138"
                },
                {
                    "asset": null,
                    "assignee": null,
                    "attachments": [],
                    "done": true,
                    "items": [
                        {
                            "item": {
                                "description": "Mauris non felis erat, eget porta quam. Aenean lobortis, urna Unicode: Î",
                                "name": "Boyle Apollo sign",
                                "uuid": "97d2552ed8764d34b829f63bd68fe2d5"
                            },
                            "quantity": 1,
                            "unitCost": 42.38,
                            "unitPrice": 46.618,
                            "uuid": "0ab9abe4241d45e684f5cdd105787a11"
                        },
                        {
                            "item": {
                                "description": "Fusce dignissim adipiscing porta. In convallis lacus hendrerit enim convallis. Unicode: Ê",
                                "name": "Spinka Advanced sign",
                                "uuid": "3afb74e220804345aa788ae99691e66c"
                            },
                            "quantity": 1,
                            "unitCost": 0.0,
                            "unitPrice": 0.0,
                            "uuid": "95fb5e78317840eeb34d91ab43f03e58"
                        }
                    ],
                    "note": null,
                    "task": {
                        "description": "dolorem et sed dolores omnis neque harum quidem voluptatibus molestiae quas rerum quo fuga enim ut voluptatum error id provident sint incidunt eum velit doloremque est dolor dolorum hic dolores vel labore doloribus facilis fugit maxime et iusto sunt eius ",
                        "name": "Install Wisozk bulkhead panel",
                        "uuid": "5147a568baa34641a62af13c93eeecf5"
                    },
                    "unitCost": 221.84,
                    "unitPrice": 231.84,
                    "uuid": "63e8cd59e926401d9206a5e3b12a58d2"
                },
                {
                    "asset": null,
                    "assignee": null,
                    "attachments": [],
                    "done": true,
                    "items": [
                        {
                            "item": {
                                "description": "Phasellus at ipsum at lectus sagittis porta sit amet vel. Unicode: Æ",
                                "name": "Volkman Vagnor driver",
                                "uuid": "a999c06e2b9b4364a18074599a4d2578"
                            },
                            "quantity": 2,
                            "unitCost": 0.0,
                            "unitPrice": 0.0,
                            "uuid": "1276c0fca3424d2ca8baec00480a9bc9"
                        },
                        {
                            "item": {
                                "description": "Vestibulum a nulla quam! Integer eget est est. Suspendisse felis. Unicode: È",
                                "name": "Kub Vantage tool",
                                "uuid": "d844d63a5ca04aeba8012391526cf8f1"
                            },
                            "quantity": 1,
                            "unitCost": 57.74,
                            "unitPrice": 67.5558,
                            "uuid": "a20a6196381f4e7dba7efe1503a49a3e"
                        }
                    ],
                    "note": null,
                    "task": {
                        "description": "aut perspiciatis aperiam qui omnis eos omnis consequatur perferendis dolor aut qui enim accusantium quis deleniti tenetur est est et error velit quis aut eligendi hic ipsa dolore aut similique quaerat harum inventore laudantium delectus ut eveniet nobis i",
                        "name": "Remove Raynor emergency filter",
                        "uuid": "d489db66b0934fe6b2995acacd8ce452"
                    },
                    "unitCost": 997.82,
                    "unitPrice": 1037.7328,
                    "uuid": "ab852098bee848bb80312026963ca9ca"
                }
            ],
            "uuid": "f883546a755947769e631a681ca56b32"
        }

    :statuscode 200: no error
    :statuscode 404: resource not found


Create a Web Quote
..................

.. http:post:: /webquote/

    **Sample Request**

    .. sourcecode:: http

        POST /webquote/ HTTP/1.1
        Accept: application/json
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Content-Length: 72
        Content-Type: application/json
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

        {
            "location": {
                "uuid": "03f0b3502f954e2e82a2b9d6189a10be"
            }
        }

    :<json obj location: JSON object representing the location for the quote (required).
    :<json string description: Textual description of the quote.
    :<json integer estDuration: The estimated duration of the work in minutes.
    :<json obj contact: JSON object representing the contact person for the quote.
    :<json obj asset: JSON object representing what asset is needed, if any.
    :<json array tasks: A list of JSON objects representing tasks.
    :<json obj task: Each object in tasks array has this form
    :<json obj task.task: JSON object defining the uuid of a task
    :<json string task.note: A note
    :<json obj task.assignee: JSON object defining the uuid of the task assignee. Must be an existing crew member.
    :<json number task.unitCost: The unitary cost of the task
    :<json number task.unitPrice: The unitary price of the task
    :<json obj task.customFields: Mapping of declaration keys to values (see :ref:`Create Job <create-job>`)
    :<json boolean done: The status of the task
    :<json obj customFields: A JSON objects representing custom fields, see :ref:`Custom Fields <custom-fields>`

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 201 CREATED
        Content-Length: 754
        Content-Type: application/json
        Date: Wed, 18 May 2016 10:44:50 GMT
        Location: https://api.fieldaware.net/webquote/2e1be725032a491f99948e800b3fc6b7
        Server: Werkzeug/0.9.4 Python/2.7.8

        {
            "completedOn": null,
            "contact": null,
            "createdOn": "2016-05-18T10:44:50.552214+00:00",
            "customFields": {},
            "customer": {
                "customerId": 5,
                "name": "Twimo Systems",
                "uuid": "4141b44ce8e44c25a9ba6c46c05f67e9"
            },
            "description": "",
            "estDuration": null,
            "invoice": null,
            "link": {
                "rel": "detail",
                "url": "https://api.fieldaware.net/webquote/2e1be725032a491f99948e800b3fc6b7"
            },
            "location": {
                "country": "United States",
                "locality": "Andersontown",
                "name": "Twimo Systems Offices",
                "postcode": null,
                "region": "WA",
                "streetName": "4122 Ellis Plain Ave.",
                "uuid": "03f0b3502f954e2e82a2b9d6189a10be"
            },
            "pre_signature": null,
            "quoteId": "Q5",
            "revenue": 0,
            "signature": null,
            "startedOn": null,
            "state": "pending",
            "tasks": [],
            "uuid": "2e1be725032a491f99948e800b3fc6b7"
        }

    :statuscode 201: created sucessfully
    :statuscode 409: request could not be full filled because state of resource does not allow payload to be applied


Update a Web Quote
..................

.. http:post:: /webquote/(webquote_ref)

    **Sample Request**

    .. sourcecode:: http

        POST /webquote/2e1be725032a491f99948e800b3fc6b7 HTTP/1.1
        Accept: application/json
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Content-Length: 72
        Content-Type: application/json
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

        {
            "location": {
                "uuid": "0b94677f78704798b09a9881811c7e24"
            }
        }

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 204 NO CONTENT
        Content-Length: 0
        Date: Wed, 18 May 2016 10:51:15 GMT
        Server: Werkzeug/0.9.4 Python/2.7.8

    :statuscode 204: quote updated successfully
    :statuscode 404: resource not found
    :statuscode 409: request could not be full filled because state of resource does not allow payload to be applied


Delete a Web Quote
..................

.. http:delete:: /webquote/(webquote_ref)

    **Sample Request**

    .. sourcecode:: http

        DELETE /webquote/2e1be725032a491f99948e800b3fc6b7 HTTP/1.1
        Accept: */*
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Content-Length: 0
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 204 NO CONTENT
        Content-Length: 0
        Date: Wed, 18 May 2016 10:53:52 GMT
        Server: Werkzeug/0.9.4 Python/2.7.8

    :statuscode 204: quote deleted successfully
    :statuscode 404: resource not found


List Field Quotes
.................

.. http:get:: /fieldquote/?start=<start date>&end=<end date>

    **Sample Request**

    .. sourcecode:: http

        GET /fieldquote/?pageSize=2&start=2000-01-01&end=2040-01-01 HTTP/1.1
        Accept: */*
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

    :query start: starting date (required)
    :query end: end date (required)
    :query sortedBy: Available sorting criteria: ``createdOn``
    :query location: filtered by ``location``
    :query state: Available filtering criteria: ``pending``, ``accepted``, ``rejected``

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 200 OK
        Content-Length: 346
        Content-Type: application/json
        Date: Wed, 18 May 2016 11:03:13 GMT
        Link: <https://api.fieldaware.net/fieldquote/?start=2000-01-01&end=2040-01-01&page=0&pageSize=2>; rel=first,<https://api.fieldaware.net/fieldquote/?start=2000-01-01&end=2040-01-01&page=0&pageSize=2>; rel=last
        Server: Werkzeug/0.9.4 Python/2.7.8

        {
            "count": 1,
            "items": [
                {
                    "completedOn": null,
                    "createdOn": "2016-05-18T10:58:09+00:00",
                    "jobLead": null,
                    "location": {
                        "uuid": "03f0b3502f954e2e82a2b9d6189a10be"
                    },
                    "scheduledOn": "2013-08-21T14:30:00+00:00",
                    "startedOn": null,
                    "state": "pending",
                    "uuid": "fe5057f4f21b4e9dba677cceaa12600a",
                    "link": {
                        "rel": "detail",
                        "url": "https://api.fieldaware.com/fieldquote/fe5057f4f21b4e9dba677cceaa12600a",
                    }
                }
            ],
            "page": 0,
            "pageSize": 2,
            "sortedBy": [
                "-scheduledOn"
            ]
        }

    :statuscode 200: no error


Get a Field Quote
.................

.. http:get:: /fieldquote/(webquote_ref)

    **Sample Request**

    .. sourcecode:: http

        GET /fieldquote/fe5057f4f21b4e9dba677cceaa12600a HTTP/1.1
        Accept: */*
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 200 OK
        Content-Length: 753
        Content-Type: application/json
        Date: Wed, 18 May 2016 11:05:16 GMT
        Server: Werkzeug/0.9.4 Python/2.7.8

        {
            "asset": null,
            "completedOn": null,
            "contact": null,
            "createdOn": "2016-05-18T10:58:09+00:00",
            "crew": [],
            "customFields": {},
            "customer": {
                "customerId": 5,
                "name": "Twimo Systems",
                "uuid": "4141b44ce8e44c25a9ba6c46c05f67e9"
            },
            "description": "",
            "estDuration": null,
            "invoice": null,
            "jobLead": null,
            "labor": [],
            "location": {
                "country": "United States",
                "locality": "Andersontown",
                "name": "Twimo Systems Offices",
                "postcode": null,
                "region": "WA",
                "streetName": "4122 Ellis Plain Ave.",
                "uuid": "03f0b3502f954e2e82a2b9d6189a10be"
            },
            "pre_signature": null,
            "quoteId": "Q6",
            "revenue": 0.0,
            "scheduledOn": "2013-08-21T14:30:00+00:00",
            "signature": null,
            "startedOn": null,
            "state": "pending",
            "tasks": [],
            "uuid": "fe5057f4f21b4e9dba677cceaa12600a"
        }

    :statuscode 200: no error
    :statuscode 404: resource not found


Create a Field Quote
....................

.. http:post:: /fieldquote/

    **Sample Request**

    .. sourcecode:: http

        POST /fieldquote/ HTTP/1.1
        Accept: application/json
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Content-Length: 114
        Content-Type: application/json
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

        {
            "location": {
                "uuid": "03f0b3502f954e2e82a2b9d6189a10be"
            },
            "scheduledOn": "2013-08-21T14:30:00"
        }

    :<json obj location: JSON object representing the location for the quote (required).
    :<json datetime scheduledOn: When the quote is scheduled (required).
    :<json integer notificationDelta: When present, a deferred quote is created and will be dispatched at time (scheduledOn - notificationDelta)
    :<json string description: Textual description of the quote.
    :<json integer estDuration: The estimated duration of the work in minutes.
    :<json obj contact: JSON object representing the contact person for the quote.
    :<json obj asset: JSON object representing what asset is needed, if any.
    :<json obj jobLead: Who is the lead member for this quote.
    :<json array crew: A list of JSON objects representing crew members.
    :<json array tasks: A list of JSON objects representing tasks.
    :<json obj task: Each object in tasks array has this form
    :<json obj task.task: JSON object defining the uuid of a task
    :<json string task.note: A note
    :<json obj task.assignee: JSON object defining the uuid of the task assignee. Must be an existing crew member.
    :<json number task.unitCost: The unitary cost of the task
    :<json number task.unitPrice: The unitary price of the task
    :<json obj task.customFields: Mapping of declaration keys to values (see :ref:`Create Job <create-job>`)
    :<json boolean done: The status of the task
    :<json obj customFields: A JSON objects representing custom fields, see :ref:`Custom Fields <custom-fields>`
    :<json array labor: A list of JSON labor objects
    :<json object labor: Each object in labor array has this form
    :<json obj labor.user: JSON object representing a user
    :<json integer labor.quantity: How many minutes spent on the quote.
    :<json object labor.rate: a rate object (Details below)
    :<json string labor.rate.name: A descriptive name for the rate, used for displaying (required)
    :<json number labor.rate.rate:  Price per hour to be charged (required)
    :<json number labor.rate.cost: Internal cost associated with unit (defaults to 0)
    :<json number labor.rate.taxable: Whether tax is to be applied to this on invoice generation (defaults to False)
    :<json array labor.rate.taxes: an array of tax objects

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 201 CREATED
        Content-Length: 857
        Content-Type: application/json
        Date: Wed, 18 May 2016 10:58:09 GMT
        Location: https://api.fieldaware.net/fieldquote/fe5057f4f21b4e9dba677cceaa12600a
        Server: Werkzeug/0.9.4 Python/2.7.8

        {
            "asset": null,
            "completedOn": null,
            "contact": null,
            "createdOn": "2016-05-18T10:58:09.372725+00:00",
            "crew": [],
            "customFields": {},
            "customer": {
                "customerId": 5,
                "name": "Twimo Systems",
                "uuid": "4141b44ce8e44c25a9ba6c46c05f67e9"
            },
            "description": "",
            "estDuration": null,
            "invoice": null,
            "jobLead": null,
            "labor": [],
            "link": {
                "rel": "detail",
                "url": "https://api.fieldaware.net/fieldquote/fe5057f4f21b4e9dba677cceaa12600a"
            },
            "location": {
                "country": "United States",
                "locality": "Andersontown",
                "name": "Twimo Systems Offices",
                "postcode": null,
                "region": "WA",
                "streetName": "4122 Ellis Plain Ave.",
                "uuid": "03f0b3502f954e2e82a2b9d6189a10be"
            },
            "pre_signature": null,
            "quoteId": "Q6",
            "revenue": 0,
            "scheduledOn": "2013-08-21T14:30:00+00:00",
            "signature": null,
            "startedOn": null,
            "state": "pending",
            "tasks": [],
            "uuid": "fe5057f4f21b4e9dba677cceaa12600a"
        }

    :statuscode 201: created sucessfully
    :statuscode 409: request could not be full filled because state of resource does not allow payload to be applied


Update a Field Quote
....................

.. http:post:: /fieldquote/(fieldquote_ref)

    **Sample Request**

    .. sourcecode:: http

        POST /fieldquote/fe5057f4f21b4e9dba677cceaa12600a HTTP/1.1
        Accept: application/json
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Content-Length: 114
        Content-Type: application/json
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

        {
            "location": {
                "uuid": "0b94677f78704798b09a9881811c7e24"
            },
            "scheduledOn": "2013-08-21T14:30:00"
        }

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 204 NO CONTENT
        Content-Length: 0
        Date: Wed, 18 May 2016 11:08:56 GMT
        Server: Werkzeug/0.9.4 Python/2.7.8

    :statuscode 204: quote updated successfully
    :statuscode 404: resource not found
    :statuscode 409: request could not be full filled because state of resource does not allow payload to be applied


Delete a Field Quote
....................

.. http:delete:: /fieldquote/(fieldquote_ref)

    **Sample Request**

    .. sourcecode:: http

        DELETE /fieldquote/fe5057f4f21b4e9dba677cceaa12600a HTTP/1.1
        Accept: */*
        Accept-Encoding: gzip, deflate
        Authorization: Token cdbfc7efe67e4407aa79d147b682430f
        Connection: keep-alive
        Content-Length: 0
        Host: api.fieldaware.net
        User-Agent: HTTPie/0.9.3

    **Sample Response**

    .. sourcecode:: http

        HTTP/1.0 204 NO CONTENT
        Content-Length: 0
        Date: Wed, 18 May 2016 11:12:53 GMT
        Server: Werkzeug/0.9.4 Python/2.7.8

    :statuscode 204: quote deleted successfully
    :statuscode 404: resource not found