Invoices -------- The API allows one or more invoices to created at a time for one or more jobs. A single invoice may cover multiple jobs. Creating an invoicing happens through the following steps: 1. First the job identifier or job identifiers of the jobs to be invoiced need to be obtained. The API allows access to a listing of uninvoiced jobs in the system (see list-uninvoiced-jobs). 2. The job identifier(s) can then be used to obtain *invoice templates* from the server, one for every invoice. An invoice template contains all the information an invoice contains, except for an invoice number and UUID 3. An actual invoice is created by sending the -- possibly amended -- invoice templates to the server. Once validated, the server assigns an invoice number and UUID and makes the invoice available for querying. Once an invoice is created, it may be updated or deleted. No job can be invoiced twice; attempt to do so will be flagged as an error. Any invoice generated through the web interface can be queried and updated through the API, and vice versa. An invoice is identified by UUID (for ex. ``cc848a85d0de4f4885b376f6b7268611``) or invoice number (for ex. ``00021657``). Wherever ``invoice_ref`` is mentioned below, it can be either of these. List Invoices ............. .. http:get:: /invoice/ List of all invoices, optionally filtered by given criteria. **Sample request**: .. sourcecode:: http GET /invoice/ HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript **Sample response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "count": 66, "items": [ { "createdOn": "2014-08-21T12:33:19+00:00", "customer": { "name": "twiba", "uuid": "a2e6e38e55e143d0b8c805dfd64deded" }, "invoiceNumber": "00000012", "jobUuids": [], "location": { "uuid": "09d77ff224d240218f8ab2473fff104a" }, "totalAmount": 165.0, "uuid": "032c8843e1ae479b995733d5d08519f4", "link": { "rel": "detail", "link": "https://api.fieldaware.net/invoice/032c8843e1ae479b995733d5d08519f4" } }, { "createdOn": "2014-08-29T12:33:19+00:00", "customer": { "name": "Cloudnico", "uuid": "27d4b97c4ff04e82868f737f37b8221c" }, "invoiceNumber": "00000022", "jobUuids": [], "location": { "uuid": "818ab504b7c24262bee851bffd9e2c16" }, "totalAmount": 85.0, "uuid": "099be0f45d094d98b80e8b1a2ab41483", "link": { "rel": "detail", "link": "https://api.fieldaware.net/invoice/099be0f45d094d98b80e8b1a2ab41483" } }, ], "page": 0, "pageSize": 3, "sortedBy": [] } :reqheader Authorization: Authorization token :statuscode 200: no error :query sortedBy: Available sorting criteria: ``invoiceNumber``, ``createdOn``, ``location``, ``totalAmount`` :query invoiceNumber: A filtering value for invoiceNumber :query createdOn: A filtering value for createdOn :query location: A filtering value for location :query start: A filtering value on ``createdOn``, defining the start of a date range. :query end: A filtering value on ``createdOn``, defining the end of a date range. :>json int count: Total number of invoices :>json array items: Invoices :>json int page: Page number :>json int pageSize: Page size :>json array sortedBy: Params for sorting Get Invoice Template .................... .. http:get:: /invoice/template/(jobs) Fetch a template for a new invoice. ``jobs`` a comma-separated list of job ID(s) or/and UUID(s) to use for filling the new invoice template. **Sample request**: .. sourcecode:: http GET /invoice/template/J54 HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :query string jobs: Single job with JobId = ``J54`` **Sample request**: .. sourcecode:: http GET /invoice/template/c4994b46a8c7401f9cca79f447e84a6e HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :query string jobs: Single job with Job UUID = ``c4994b46a8c7401f9cca79f447e84a6e`` **Sample request**: .. sourcecode:: http GET /invoice/template/J54,J55 HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :query string jobs: Multiple jobs with id = ``J54`` and id = ``J55`` **Sample request**: .. sourcecode:: http GET /invoice/template/c4994b46a8c7401f9cca79f447e84a6e,b630ca4294744cfda6cb4009771fd84e HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :query string jobs: Multiple jobs with UUIDs = ``c4994b46a8c7401f9cca79f447e84a6e`` and ``b630ca4294744cfda6cb4009771fd84e`` **Sample response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "comment": "", "contact": { "emailAddress": "sbeatty@hotmail.com", "name": "Shawna", "surname": "Beatty", "telno": null, "uuid": "082a0b1f46dc4ac39f33f703910a6b2a" }, "createdOn": "2014-09-08T13:46:32.330493+00:00", "currency": "USD", "customFields": {}, "customer": { "name": "Blingnet", "uuid": "bae4089185c0485d9a2af0ad5d8a199f" }, "internalComment": "\nJob J86: 78h,32min\n", "jobs": [ { "asset": { "name": "Bauch Pneumatic saw", "serialNumber": "466116U", "uuid": "76b0813f5ced407c93f374e0fb5088bc" }, "completedOn": "2014-09-08T13:43:32+00:00", "customFields": { "305cd64d606f4b67927e61badcfe1007": 10.3, "e18e4d73d7ce40cca5d93a44f1a01e54": "3eec017fa7604656bbf2fe2850a37c23" }, "jobId": "J86", "jobLead": "Damon Murray", "lineItems": [ { "cost": 117.83, "description": "", "note": null, "glAccount": null, "name": "Install Jenkins conventional callpoint", "price": 133.83, "quantity": 1, "taxes": [], "itemType: "Task", "entity": {"uuid": "82a4ec838f884c4bbfd90b7042bdafb7"} }, { "cost": 57.11, "description": "", "note": null, "glAccount": null, "name": "\tHowell Loop sign", "price": 93.11, "quantity": 2, "taxes": [], "itemType: "Task", "entity": {"uuid": "55f200ae2b8049189b68008666bd4610"} }, { "cost": None, "description": "A lot of work", "note": None, "glAccount": null, "name": "John's Labor", "price": 100.0, "quantity": 1.09 "taxes": [{"rate": 8.25, "agency": "", "name": "Dallas", "glAccount": ""}], "itemType": "Labor", "entity": None, } ], "location": { "country": "United States", "locality": "South Burdette", "name": "Blingnet Offices", "postcode": null, "region": "OK", "streetName": "6328 Reanna Station Suite 074", "uuid": "80b67eca44c941fe9fbec13f2a8d499e" }, "uuid": "3eec017fa7604656bbf2fe2850a37c23" } ], "location": null, "totals": { "netAmount": 3469.98, "netLaborAmount": 0.0, "totalAmount": 3469.98, "totalTax": 0.0 } } :>json string coment: Comment :>json obj contact: Contact :>json string createdOn: Date in ISO format :>json string currency: Currency of the invoice :>json obj customFields: Custom fields :>json obj customer: Customer :>json string internalComment: Internal comment of the invoice :>json array jobs: A list of json objects - invoiced jobs :>json string location: Location :>json obj totals: A dict with calculated totals Get Invoice Templates ..................... .. http:get:: /invoice/template/?(jobs) Fetch a template for multiple invoices in a single request. A comma-separated list of job ``ID``(s) or/and ``UUID``(s) to use for filling the new invoice template. The parameter can be specified multiple times to request multiple invoice templates. **Examples**:: # single invoice, single job by job id /invoice/template?jobs=J54 # single invoice, single job by UUID /invoice/template?jobs=c4994b46a8c7401f9cca79f447e84a6e # single invoice, multiple jobs by job id /invoice/template?jobs=J54,J55 # single invoice, multiple jobs by UUID /invoice/template?jobs=c4994b46a8c7401f9cca79f447e84a6e,b630ca4294744cfda6cb4009771fd84e # multiple invoices with 1 and 3 jobs respectively /invoice/template?jobs=J54&jobs=J55,J56,J57 **Sample request**: .. sourcecode:: http GET /invoice/template/?jobs=J54 HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :qparam string jobId: Example JobId = ``J54`` **Sample request**: .. sourcecode:: http GET /invoice/template/?jobs=c4994b46a8c7401f9cca79f447e84a6e HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :qparam string UUID: Example job UUID = ``c4994b46a8c7401f9cca79f447e84a6e`` **Sample request**: .. sourcecode:: http GET /invoice/template/?jobs=J54,J55 HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :qparam string jobs: Jobs with ids ``J54`` and ``J55`` **Sample request**: .. sourcecode:: http GET /invoice/template/?jobs=c4994b46a8c7401f9cca79f447e84a6e,b630ca4294744cfda6cb4009771fd84e HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :qparam string jobs: Jobs with UUIDs: ``c4994b46a8c7401f9cca79f447e84a6e`` and ``b630ca4294744cfda6cb4009771fd84e`` **Sample request**: .. sourcecode:: http GET /invoice/template/?jobs=J51&jobs=J55,J56,J57 HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :qparam string jobs: Jobs with IDs: ``J51``, ``J55``, ``J56``, ``J57`` **Sample response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "templates": [ { "customer": { "name": "iqa", "uuid": "d3c45b8f06064c199c6ab43c622aca9a" }, "location": { "uuid": "6d6b036dbcdc4e8aafb469a57ec843d6" } "comment": "", "contact": { "emailAddress": "xhills@yahoo.com", "telno": null, "surname": "Hills", "uuid": "68e4000d7a434723ac482293d2e205c1", "name": "Xavier" }, "jobs": [ { "uuid": "36976156807c426e9bf5cd25ad953e0c", "jobId": "J82", "location": { "uuid": "6d6b036dbcdc4e8aafb469a57ec843d6", "locality": "South Gloria", "country": "United States", "region": "AK", "postcode": null, "streetName": "8274 Shields Trail Ave.", "name": "iqa Headquarters" }, "jobLead": "Marco Cummerata", "customFields": { "Job Random String": "36976156807c426e9bf5cd25ad953e0c", "Discount": 92.8 }, "lineItems": [ { "cost": 366.78000, "name": "Replace Rosenbaum manual lights", "glAccount": null, "price": 388.78680, "quantity": 1, "taxes": [], "description": "", "note": "sockets show heavy wear; may need to be replaced soon", "itemType: "Task", "entity": {"uuid": "82a4ec838f884c4bbfd90b7042bdafb7"} }, { "cost": 857.06000, "name": "Remove Mann manual filter", "glAccount": null, "price": 896.06000, "quantity": 1, "taxes": [], "description": "", "note": null, "itemType: "Task", "entity": {"uuid": "55f200ae2b8049189b68008666bd4610"} } { "cost": None, "name": "John's Labor", "glAccount": null, "price": 100.0, "quantity": 1.09 "taxes": [{"rate": 8.25, "agency": "", "name": "Dallas", "glAccount": ""}], "description": "A lot of work", "note": None, "itemType": "Labor", "entity": None, } ], "completedDatetime": null, "asset": { "serialNumber": "102931G", "uuid": "6e342da5a09d4fdf8db47268e0ac8a2d", "name": "McKenzie Hyper core" } } ], "currency": "USD", "internalComment": "\nJob J82: 0h,0min\n", "createdOn": "2013-08-29T19:06:47.373405+00:00", "totals": { "totalTax": 0.00, "netAmount": 2473.07, "totalAmount": 2473.07, "netLaborAmount": 0.00 } }, { "customer": { "name": "Plurchi", "uuid": "4ba8f84142a242d1ad984b818e1763b1" }, "comment": "", "contact": { "emailAddress": "rwelch@hotmail.com", "telno": null, "surname": "Welch", "uuid": "cb3740e0cdf54099afd1e308364b157a", "name": "Rosamond" }, "jobs": [ { "uuid": "c6249da48e604394a95f6f669cc8d883", "jobId": "J71", "location": { "uuid": "f35df45db4864df1bfbe888a58994137", "locality": "Port Arnoldoton", "country": "United States", "region": "LA", "postcode": null, "streetName": "326 Jacey Cove ", "name": "Plurchi Headquarters" }, "jobLead": "Logan Block", "customFields": { "Job Random String": "c6249da48e604394a95f6f669cc8d883", "Discount": 19.200000000000000000000000000000 }, "lineItems": [ { "cost": 690.72000, "name": "Remove Hegmann manual callpoint", "glAccount": null, "price": 704.53440, "quantity": 1, "taxes": [], "description": "", "note": null, "itemType: "Task", "entity": {"uuid": "55f200ae2b8049189b68008666bd4610"} }, { "cost": 349.94000, "name": "Remove Hettinger heat filter", "glAccount": null, "price": 395.43220, "quantity": 1, "taxes": [], "description": "", "note": null, "itemType: "Task", "entity": {"uuid": "82a4ec838f884c4bbfd90b7042bdafb7"} } ], "completedDatetime": null, "asset": { "serialNumber": "107470J", "uuid": "4005103c2f6045f58f52ea78ee00d6d2", "name": "Cruickshank Pneumatic detector" } } ], "currency": "USD", "internalComment": "\nJob J71: 0h,0min\n", "createdOn": "2013-08-29T19:06:47.427706+00:00", "totals": { "totalTax": 0.00, "netAmount": 1572.03, "totalAmount": 1572.03, "netLaborAmount": 0.00 } } ], "errors": [ { "message": "Job(s) are not found: j77", "name": "NotFoundError" } ] } :>json array templates: A list of templates :>json array errors: A list of errors Get Invoice ........... .. http:get:: /invoice/(invoice_ref) Retrieve a given invoice. **Sample request**: .. sourcecode:: http GET /invoice/4005103c2f6045f58f52ea78ee00d6xx HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json, text/javascript :qparam string invoice_ref: Invoice UUID **Sample response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "comment": "An Invoice", "contact": null, "createdOn": "2014-09-06T07:33:19+00:00", "currency": "USD", "customFields": {}, "customer": { "name": "Cloudnico", "uuid": "27d4b97c4ff04e82868f737f37b8221c" }, "internalComment": null, "invoiceNumber": "00000013", "jobs": [ { "lineItems": [ { "cost": 18.0, "description": null, "note": null, "glAccount": null, "name": "Replace Sounder [Vantage Sounder]", "price": null, "quantity": 1, "taxes": [], "itemType: "Task", "entity": {"uuid": "82a4ec838f884c4bbfd90b7042bdafb7"} }, { "cost": 24.0, "description": null, "note": null, "glAccount": null, "name": "Replace Sounder [Spatial Sounder]", "price": null, "quantity": 1, "taxes": [], "itemType: "Task", "entity": {"uuid": "55f200ae2b8049189b68008666bd4610"} } ] } ], "location": { "uuid": "82c511452acd4dc7b7027fc7e3c9da3a" }, "totals": { "netAmount": 42.0, "netLaborAmount": 0.0, "totalAmount": 42.0, "totalTax": 0.0 }, "uuid": "4f371e6397564dcfb41284f23124bf94" } :>json string comment: Comment :>json obj contact: Contact details (JSON Obj) or null if no contact provided :>json string createdOn: Date the invoice was created (in ISO format) :>json string currency: Currency :>json obj customFields: Custom fields (JSON Obj) :>json obj customer: Customer (JSON Obj) :>json string internalComment: Comment, null or string :>json string invoiceNumber: Invoice number :>json array jobs: A list of Jobs (JSON Obj) :>json obj location: Location UUID :>json obj totals: Calculated totals :>json string uuid: UUID of the invoice Create Invoice .............. .. http:post:: /invoice/ Create a new invoice. **Sample request**: .. sourcecode:: http POST /invoice/ HTTP/1.1 Host: api.fieldaware.net Authorization: Token 9dcae3660ec84eac94bb506e09a9af40 Content-Type: application/json Accept: application/json { "createdOn": "datetime obj", "comment": "Invoice description", "internalComment": "invoice description", "customer": { "uuid": "uuid of the customer", }, "contact": { "uuid": "uuid of the contact", }, "jobs": [ { "uuid": "UUID of the job (string, required)", "lineItems": [ { "name": "Name of the invoiced task, product or person (string, required)", "description": "Optional description for the invoiced task or product (string)", "note": "Optional note (string)", "price": "Unit price (number, required)", "cost": "Unit cost (number, required)", "quantity": "Item quantity, 1.0 if it is a Task, duration in hours if it is labor (number, required)", "itemType": "Product", "glAccount": "General Ledger account (string)", "taxes": [ { "name": "Tax name (string, required)", "rate": "Tax rate (number, required)", } ] } ] } ], "totals": { "netAmount": 0.0, "netLaborAmount": 0.0, "totalTax": 00.0, "totalAmount": 0.0, } } :