diff --git a/app/Jobs/Subscription/CleanStaleInvoiceOrder.php b/app/Jobs/Subscription/CleanStaleInvoiceOrder.php index 85dcfd5c29..9efbe2ca26 100644 --- a/app/Jobs/Subscription/CleanStaleInvoiceOrder.php +++ b/app/Jobs/Subscription/CleanStaleInvoiceOrder.php @@ -54,6 +54,7 @@ class CleanStaleInvoiceOrder implements ShouldQueue ->cursor() ->each(function ($invoice) use ($repo) { $invoice->is_proforma = false; + $invoice->save(); $repo->delete($invoice); }); @@ -162,6 +163,7 @@ class CleanStaleInvoiceOrder implements ShouldQueue ->cursor() ->each(function ($invoice) use ($repo) { $invoice->is_proforma = false; + $invoice->save(); $repo->delete($invoice); }); diff --git a/openapi/api-docs.yaml b/openapi/api-docs.yaml index fb9b24ee04..af31ec8d3a 100644 --- a/openapi/api-docs.yaml +++ b/openapi/api-docs.yaml @@ -9109,26 +9109,43 @@ paths: tags: - locations summary: 'List locations' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("your_token"); + $invoices = $ninja->locations->all([]); + - lang: curl + label: curl + source: | + curl --request GET \ + --url 'https://demo.invoiceninja.com/api/v1/locations?per_page=10&page=1&sort=name&sort_dir=asc' \ + --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \ + --header 'Accept: application/json' description: | - When retrieving a list of locations you can chain query parameters to filter the dataset. For example: - - ``` - /api/v1/locations?name=warehouse* - ``` - - You can also sort the results: - - ``` - /api/v1/locations?sort=name|desc - ``` + ## GET /api/v1/locations - For pagination, use per_page and page parameters: - - ``` - /api/v1/locations?per_page=15&page=2 - ``` + Locations are additional addresses that are applicable to a client. This is useful when a client has multiple addresses for shipping, billing, etc. - The default per_page value is 20. + When retrieving a list of locations you can chain query parameters to filter the dataset. For example: + + ```html + /api/v1/locations?name=warehouse* + ``` + + You can also sort the results: + + ```html + /api/v1/locations?sort=name|desc + ``` + + For pagination, use per_page and page parameters: + + ```html + /api/v1/locations?per_page=15&page=2 + ``` + + The default per_page value is 20. operationId: getLocations parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -9171,7 +9188,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Location' + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Location' 401: $ref: '#/components/responses/401' 403: @@ -9187,7 +9209,57 @@ paths: tags: - locations summary: 'Create location' - description: 'Adds a location to a company' + description: | + ## POST /api/v1/locations + + Adds a location to a company + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + + $client = $ninja->locations->create([ + 'name' => 'A unique client location name', + 'address1' => '123 Main St', + 'address2' => 'Apt 1', + 'city' => 'New York', + 'state' => 'NY', + 'postal_code' => '10001', + 'country_id' => '1', + 'custom_value1' => 'Custom field value 1', + 'custom_value2' => 'Custom field value 2', + 'custom_value3' => 'Custom field value 3', + 'custom_value4' => 'Custom field value 4', + 'is_deleted' => false, + 'is_shipping_location' => true, + 'client_id' => 'x2fd23', + 'vendor_id' => 'jd78Dhjs' + ]); + - lang: curl + label: curl + source: | + curl -X POST https://demo.invoiceninja.com/api/v1/locations \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "Content-Type: application/json" \ + -H "X-Requested-With: XMLHttpRequest" \ + -d '{ + "name": "A unique location name", + "address1": "123 Main St", + "address2": "Apt 1", + "city": "New York", + "state": "NY", + "postal_code": "10001", + "country_id": "1", + "custom_value1": "Custom field value 1", + "custom_value2": "Custom field value 2", + "custom_value3": "Custom field value 3", + "custom_value4": "Custom field value 4", + "is_deleted": false, + "is_shipping_location": true, + "client_id": "x2fd23", + "vendor_id": "jd78Dhjs" + }' operationId: storeLocation parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -9230,7 +9302,10 @@ paths: tags: - locations summary: 'Show location' - description: 'Displays a location by id' + description: | + ## GET /api/v1/locations/{id} + + Displays a location by id operationId: showLocation parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -9268,12 +9343,28 @@ paths: $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $location = $ninja->locations->show("D2J234DFA"); + - lang: curl + label: curl + source: | + curl --request GET \ + --url 'https://demo.invoiceninja.com/api/v1/locations/D2J234DFA' \ + --header 'X-API-TOKEN: YOUR-TOKEN' \ + --header 'Accept: application/json' put: tags: - locations summary: 'Update location' - description: 'Handles the updating of a location by id' + description: | + ## PUT /api/v1/locations/{id} + + Handles the updating of a location by id operationId: updateLocation parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -9318,12 +9409,37 @@ paths: $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $location = $ninja->locations->update("D2J234DFA", [ + 'name' => 'Updated Location Name', + 'address1' => '456 New Street', + 'city' => 'Los Angeles' + ]); + - lang: curl + label: curl + source: | + curl -X PUT https://demo.invoiceninja.com/api/v1/locations/D2J234DFA \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "Content-Type: application/json" \ + -H "X-Requested-With: XMLHttpRequest" \ + -d '{ + "name": "Updated Location Name", + "address1": "456 New Street", + "city": "Los Angeles" + }' delete: tags: - locations summary: 'Delete location' - description: 'Handles the deletion of a location by id' + description: | + ## DELETE /api/v1/locations/{id} + + Handles the deletion of a location by id operationId: deleteLocation parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -9356,13 +9472,29 @@ paths: $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $ninja->locations->delete("D2J234DFA"); + - lang: curl + label: curl + source: | + curl -X DELETE \ + --url 'https://demo.invoiceninja.com/api/v1/locations/D2J234DFA' \ + --header 'X-API-TOKEN: YOUR-TOKEN' \ + --header 'Accept: application/json' /api/v1/locations/create: get: tags: - locations summary: 'Blank Location' - description: 'Returns a blank object with default values' + description: | + ## GET /api/v1/locations/create + + Returns a blank object with default values operationId: getLocationsCreate parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -9392,6 +9524,19 @@ paths: $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $location = $ninja->locations->model(); + - lang: curl + label: curl + source: | + curl --request GET \ + --url 'https://demo.invoiceninja.com/api/v1/locations/create' \ + --header 'X-API-TOKEN: YOUR-TOKEN' \ + --header 'Accept: application/json' /api/v1/locations/bulk: post: @@ -9399,6 +9544,8 @@ paths: - locations summary: 'Bulk location actions' description: | + ## POST /api/v1/locations/bulk + Bulk actions allow to make changes to multiple locations in a single request. The following actions are supported: - archive @@ -9408,6 +9555,26 @@ paths: All of these actions require an array of location ids to perform the requested action on ie. "ids":['id1','id2'] + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $ninja->locations->bulk([ + 'action' => 'archive', + 'ids' => ['locationId1', 'locationId2'] + ]); + - lang: curl + label: curl + source: | + curl -X POST https://demo.invoiceninja.com/api/v1/locations/bulk \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "Content-Type: application/json" \ + -H "X-Requested-With: XMLHttpRequest" \ + -d '{ + "action": "archive", + "ids": ["locationId1", "locationId2"] + }' operationId: bulkLocations parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -9444,6 +9611,7 @@ paths: $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + /api/v1/recurring_invoices: get: tags: @@ -13115,7 +13283,8 @@ paths: get: tags: - clients - summary: 'List clients' + summary: | + List clients x-codeSamples: - lang: php label: php @@ -13135,31 +13304,32 @@ paths: --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \ --header 'Accept: application/json' description: | - When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000:\ + ## GET /api/v1/clients + When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000 ``` /api/v1/clients?balance=gt:1000 ``` - You can also sort the results by adding a sort parameter. The following example will sort the results by the client name in descending order:\ + You can also sort the results by adding a sort parameter. The following example will sort the results by the client name in descending order ``` /api/v1/clients?sort=name|desc ``` - You can also combine multiple filters together. The following example will return clients that have a balance greater than 1000 and are not deleted and have a name that starts with "Bob":\ + You can also combine multiple filters together. The following example will return clients that have a balance greater than 1000 and are not deleted and have a name that starts with "Bob" ``` /api/v1/clients?balance=gt:1000&name=Bob* ``` - If you wish to retrieve child relations, you can also combine the query parameter `?include=` with a comma separated list of relationships:\ + If you wish to retrieve child relations, you can also combine the query parameter `?include=` with a comma separated list of relationships ``` /api/v1/clients?include=activities,ledger,system_logs' ``` - The per_page and page variables allow pagination of the list of clients. The following example will return the second page of clients with 15 clients per page:\ + The per_page and page variables allow pagination of the list of clients. The following example will return the second page of clients with 15 clients per page ``` /api/v1/clients?per_page=15&page=2 @@ -13347,10 +13517,12 @@ paths: - clients summary: 'Create client' description: | - Adds a client to a company - - > 🚨 Important - When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation. + + ## POST /api/v1/clients + Adds a client to a company + + > 🚨 Important + When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation. x-codeSamples: - lang: php label: php @@ -13387,7 +13559,8 @@ paths: "first_name": "John", "last_name": "Smith", "email": "john@example.com", - "phone": "555-0123" + "phone": "555-0123", + "send_email": true } ], "address1": "123 Main St", @@ -13403,7 +13576,6 @@ paths: - $ref: '#/components/parameters/index' - $ref: '#/components/parameters/client_include' requestBody: - description: Client object that needs to be added to the company required: true content: application/json: @@ -13438,7 +13610,11 @@ paths: tags: - clients summary: 'Show client' - description: 'Displays a client by id' + description: | + ## GET /api/v1/clients/{id} + + Displays a client by id + x-codeSamples: - lang: php label: php @@ -13495,6 +13671,8 @@ paths: - clients summary: 'Update client' description: | + ## PUT /api/v1/clients/{id} + Handles the updating of a client by id > 🚨 Important @@ -13583,12 +13761,17 @@ paths: - clients summary: 'Delete client' description: | + ## DELETE /api/v1/clients/{id} + Handles the deletion of a client by id > ❗ Note Deleting a client does not purge the client from the system. The delete action will remove the clients data from all - views in the application but keep it all on file. A Client can be laterrestored reversing this action. To permanently wipe a client and - all of their records from the system, use the /purge route + views in the application but keep it on file in case it needs to be restored. + + A Client can be later restored reversing this action. + + To permanently wipe a client and all of their records from the system, use the [/purge route](/#tag/clients/POST/api/v1/clients/{id}/purge) x-codeSamples: - lang: php @@ -13642,7 +13825,21 @@ paths: tags: - clients summary: 'Edit Client' - description: 'Displays a client by id, essentially an alias of the show route' + description: | + ## GET /api/v1/clients/{id}/edit + Displays a client by id, essentially an alias of the show route + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $client = $ninja->clients->show('clientId123'); + - lang: curl + label: php + source: | + curl -X GET https://demo.invoiceninja.com/api/v1/clients/clientId123 \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "X-Requested-With: XMLHttpRequest" operationId: editClient parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -13686,7 +13883,23 @@ paths: tags: - clients summary: 'Blank Client' - description: 'Returns a blank object with default values' + description: | + ## GET /api/v1/clients/create + + Returns a blank object with default values + + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $client = $ninja->clients->model(); + - lang: curl + label: php + source: | + curl -X GET https://demo.invoiceninja.com/api/v1/clients/create \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "X-Requested-With: XMLHttpRequest" operationId: getClientsCreate parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -13723,6 +13936,8 @@ paths: - clients summary: 'Bulk client actions' description: | + ## POST /api/v1/clients/bulk + Bulk actions allow to make changes to multiple clients in a single request the following actions are supported - archive @@ -13730,7 +13945,7 @@ paths: - delete - template _requires template,template_id properties also_ - assign_group _requires group_settings_id also_ - - bulk_update _ requires column,new_value also_ + - bulk_update _requires column,new_value also_ All of these actions require an array of client ids to perform the requested action on ie. @@ -13744,7 +13959,7 @@ paths: - assign_group - Allows the setting of multiple clients to a single group + Allows setting multiple clients to a single group - bulk_update @@ -13822,7 +14037,11 @@ paths: tags: - clients summary: 'Add client document' - description: 'Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST' + description: | + ## POST /api/v1/clients/{id}/upload + + Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST + x-codeSamples: - lang: php label: php @@ -13910,11 +14129,13 @@ paths: - clients summary: 'Purge client' description: | - Handles purging a client. + ## POST /api/v1/clients/{id}/purge - > ❗ Note - This is a destructive action. - This action will remove all data associated with the client and cannot be undone. + Handles purging a client. + + > ❗ Note + This is a destructive action. + This action will remove all data associated with the client and cannot be undone. x-codeSamples: - lang: php label: php @@ -13968,15 +14189,17 @@ paths: - clients summary: 'Merge client' description: | - Handles merging 2 clients + ## POST /api/v1/clients/{id}/{mergeable_client_hashed_id}/merge - The id parameter is the client that will be the primary client after the merge has completed. + Handles merging 2 clients - The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client. + The id parameter is the client that will be the primary client after the merge has completed. - > 🚨 **Important** - This action requires elevated permissions, please note the X-API-PASSWORD header requirements for this route. - + The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client. + + > 🚨 **Important** + This action requires elevated permissions, please note the X-API-PASSWORD header requirements for this route. + x-codeSamples: - lang: php label: php @@ -14038,7 +14261,11 @@ paths: tags: - clients summary: 'Client statement PDF' - description: 'Return a PDF of the client statement' + description: | + ## POST /api/v1/client_statement + + Return a PDF of the client statement + operationId: clientStatement x-codeSamples: - lang: php @@ -14128,7 +14355,11 @@ paths: tags: - clients summary: 'Removes email suppression of a user in the system' - description: 'Emails are suppressed by PostMark, when they receive a Hard bounce / Spam Complaint. This endpoint allows you to remove the suppression and send emails to the user again.' + description: | + ## POST /api/v1/reactivate_email/{bounce_id} + + Emails are suppressed by PostMark, when they receive a Hard bounce / Spam Complaint. This endpoint allows you to remove the suppression and send emails to the user again. + operationId: reactivateEmail parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -14172,7 +14403,11 @@ paths: tags: - clients summary: 'Update tax data' - description: 'Updates the clients tax data - if their address has changed' + description: | + ## POST /api/v1/clients/{client}/updateTaxData + + Updates the clients tax data - if their address has changed + operationId: updateClientTaxData parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -21589,6 +21824,7 @@ components: Optionally, instead of the country_id you can pass either the iso_3166_2 or iso_3166_3 country code into the country_code property. type: number format: integer + $ref: '#/components/schemas/CountryType' example: '1' custom_value1: description: 'A custom field for storing additional information' @@ -21701,49 +21937,44 @@ components: type: object ClientContactRequest: properties: - id: - description: 'The hashed if of the contact' - type: string - example: Opnel5aKBz - readOnly: true first_name: description: 'The first name of the contact' type: string - example: John + example: Sarah last_name: description: 'The last name of the contact' type: string - example: Doe + example: Johnson phone: description: 'The phone number of the contact' type: string - example: 555-152-4524 + example: '+1-555-123-4567' custom_value1: description: 'A Custom field value' type: string - example: '' + example: 'Preferred Customer' custom_value2: description: 'A Custom field value' type: string - example: '' + example: 'West Region' custom_value3: description: 'A Custom field value' type: string - example: '' + example: 'Referral: Jane Smith' custom_value4: description: 'A Custom field value' type: string - example: '' + example: 'Account #12345' email: description: 'The email of the contact' type: string - example: '' + example: 'sarah.johnson@example.com' password: description: 'The hashed password of the contact' type: string - example: '*****' + example: '$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi' send_email: - description: 'Boolean value determines is this contact should receive emails' + description: 'Boolean flag that determines if this contact should receive emails' type: boolean example: true type: object diff --git a/openapi/components/schemas/client_contact_request.yaml b/openapi/components/schemas/client_contact_request.yaml index 52abaf09c0..8a278d653a 100644 --- a/openapi/components/schemas/client_contact_request.yaml +++ b/openapi/components/schemas/client_contact_request.yaml @@ -1,48 +1,43 @@ ClientContactRequest: properties: - id: - description: 'The hashed if of the contact' - type: string - example: Opnel5aKBz - readOnly: true first_name: description: 'The first name of the contact' type: string - example: John + example: Sarah last_name: description: 'The last name of the contact' type: string - example: Doe + example: Johnson phone: description: 'The phone number of the contact' type: string - example: 555-152-4524 + example: '+1-555-123-4567' custom_value1: description: 'A Custom field value' type: string - example: '' + example: 'Preferred Customer' custom_value2: description: 'A Custom field value' type: string - example: '' + example: 'West Region' custom_value3: description: 'A Custom field value' type: string - example: '' + example: 'Referral: Jane Smith' custom_value4: description: 'A Custom field value' type: string - example: '' + example: 'Account #12345' email: description: 'The email of the contact' type: string - example: '' + example: 'sarah.johnson@example.com' password: description: 'The hashed password of the contact' type: string - example: '*****' + example: '$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi' send_email: - description: 'Boolean value determines is this contact should receive emails' + description: 'Boolean flag that determines if this contact should receive emails' type: boolean example: true type: object \ No newline at end of file diff --git a/openapi/components/schemas/client_request.yaml b/openapi/components/schemas/client_request.yaml index 51f589125c..d57160eac2 100644 --- a/openapi/components/schemas/client_request.yaml +++ b/openapi/components/schemas/client_request.yaml @@ -64,6 +64,7 @@ Optionally, instead of the country_id you can pass either the iso_3166_2 or iso_3166_3 country code into the country_code property. type: number format: integer + $ref: '#/components/schemas/CountryType' example: '1' custom_value1: description: 'A custom field for storing additional information' diff --git a/openapi/paths/clients.yaml b/openapi/paths/clients.yaml index f14af99668..ef653a0f6f 100644 --- a/openapi/paths/clients.yaml +++ b/openapi/paths/clients.yaml @@ -2,7 +2,8 @@ get: tags: - clients - summary: 'List clients' + summary: | + List clients x-codeSamples: - lang: php label: php @@ -22,31 +23,32 @@ --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \ --header 'Accept: application/json' description: | - When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000:\ + ## GET /api/v1/clients + When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000 ``` /api/v1/clients?balance=gt:1000 ``` - You can also sort the results by adding a sort parameter. The following example will sort the results by the client name in descending order:\ + You can also sort the results by adding a sort parameter. The following example will sort the results by the client name in descending order ``` /api/v1/clients?sort=name|desc ``` - You can also combine multiple filters together. The following example will return clients that have a balance greater than 1000 and are not deleted and have a name that starts with "Bob":\ + You can also combine multiple filters together. The following example will return clients that have a balance greater than 1000 and are not deleted and have a name that starts with "Bob" ``` /api/v1/clients?balance=gt:1000&name=Bob* ``` - If you wish to retrieve child relations, you can also combine the query parameter `?include=` with a comma separated list of relationships:\ + If you wish to retrieve child relations, you can also combine the query parameter `?include=` with a comma separated list of relationships ``` /api/v1/clients?include=activities,ledger,system_logs' ``` - The per_page and page variables allow pagination of the list of clients. The following example will return the second page of clients with 15 clients per page:\ + The per_page and page variables allow pagination of the list of clients. The following example will return the second page of clients with 15 clients per page ``` /api/v1/clients?per_page=15&page=2 @@ -234,10 +236,12 @@ - clients summary: 'Create client' description: | - Adds a client to a company - - > 🚨 Important - When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation. + + ## POST /api/v1/clients + Adds a client to a company + + > 🚨 Important + When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation. x-codeSamples: - lang: php label: php @@ -274,7 +278,8 @@ "first_name": "John", "last_name": "Smith", "email": "john@example.com", - "phone": "555-0123" + "phone": "555-0123", + "send_email": true } ], "address1": "123 Main St", @@ -290,7 +295,6 @@ - $ref: '#/components/parameters/index' - $ref: '#/components/parameters/client_include' requestBody: - description: Client object that needs to be added to the company required: true content: application/json: @@ -325,7 +329,11 @@ tags: - clients summary: 'Show client' - description: 'Displays a client by id' + description: | + ## GET /api/v1/clients/{id} + + Displays a client by id + x-codeSamples: - lang: php label: php @@ -382,6 +390,8 @@ - clients summary: 'Update client' description: | + ## PUT /api/v1/clients/{id} + Handles the updating of a client by id > 🚨 Important @@ -470,12 +480,17 @@ - clients summary: 'Delete client' description: | + ## DELETE /api/v1/clients/{id} + Handles the deletion of a client by id > ❗ Note Deleting a client does not purge the client from the system. The delete action will remove the clients data from all - views in the application but keep it all on file. A Client can be laterrestored reversing this action. To permanently wipe a client and - all of their records from the system, use the /purge route + views in the application but keep it on file in case it needs to be restored. + + A Client can be later restored reversing this action. + + To permanently wipe a client and all of their records from the system, use the [/purge route](/#tag/clients/POST/api/v1/clients/{id}/purge) x-codeSamples: - lang: php @@ -529,7 +544,21 @@ tags: - clients summary: 'Edit Client' - description: 'Displays a client by id, essentially an alias of the show route' + description: | + ## GET /api/v1/clients/{id}/edit + Displays a client by id, essentially an alias of the show route + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $client = $ninja->clients->show('clientId123'); + - lang: curl + label: php + source: | + curl -X GET https://demo.invoiceninja.com/api/v1/clients/clientId123 \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "X-Requested-With: XMLHttpRequest" operationId: editClient parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -573,7 +602,23 @@ tags: - clients summary: 'Blank Client' - description: 'Returns a blank object with default values' + description: | + ## GET /api/v1/clients/create + + Returns a blank object with default values + + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $client = $ninja->clients->model(); + - lang: curl + label: php + source: | + curl -X GET https://demo.invoiceninja.com/api/v1/clients/create \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "X-Requested-With: XMLHttpRequest" operationId: getClientsCreate parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -610,6 +655,8 @@ - clients summary: 'Bulk client actions' description: | + ## POST /api/v1/clients/bulk + Bulk actions allow to make changes to multiple clients in a single request the following actions are supported - archive @@ -617,7 +664,7 @@ - delete - template _requires template,template_id properties also_ - assign_group _requires group_settings_id also_ - - bulk_update _ requires column,new_value also_ + - bulk_update _requires column,new_value also_ All of these actions require an array of client ids to perform the requested action on ie. @@ -631,7 +678,7 @@ - assign_group - Allows the setting of multiple clients to a single group + Allows setting multiple clients to a single group - bulk_update @@ -709,7 +756,11 @@ tags: - clients summary: 'Add client document' - description: 'Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST' + description: | + ## POST /api/v1/clients/{id}/upload + + Handles the uploading of a document to a client, please note due to a quirk in REST you will need to use a _method parameter with value of POST + x-codeSamples: - lang: php label: php @@ -797,11 +848,13 @@ - clients summary: 'Purge client' description: | - Handles purging a client. + ## POST /api/v1/clients/{id}/purge - > ❗ Note - This is a destructive action. - This action will remove all data associated with the client and cannot be undone. + Handles purging a client. + + > ❗ Note + This is a destructive action. + This action will remove all data associated with the client and cannot be undone. x-codeSamples: - lang: php label: php @@ -855,15 +908,17 @@ - clients summary: 'Merge client' description: | - Handles merging 2 clients + ## POST /api/v1/clients/{id}/{mergeable_client_hashed_id}/merge - The id parameter is the client that will be the primary client after the merge has completed. + Handles merging 2 clients - The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client. + The id parameter is the client that will be the primary client after the merge has completed. - > 🚨 **Important** - This action requires elevated permissions, please note the X-API-PASSWORD header requirements for this route. - + The mergeable_client_hashed_id is the client that will be merged into the primary client, this clients records will be updated and associated with the primary client. + + > 🚨 **Important** + This action requires elevated permissions, please note the X-API-PASSWORD header requirements for this route. + x-codeSamples: - lang: php label: php @@ -925,7 +980,11 @@ tags: - clients summary: 'Client statement PDF' - description: 'Return a PDF of the client statement' + description: | + ## POST /api/v1/client_statement + + Return a PDF of the client statement + operationId: clientStatement x-codeSamples: - lang: php @@ -1015,7 +1074,11 @@ tags: - clients summary: 'Removes email suppression of a user in the system' - description: 'Emails are suppressed by PostMark, when they receive a Hard bounce / Spam Complaint. This endpoint allows you to remove the suppression and send emails to the user again.' + description: | + ## POST /api/v1/reactivate_email/{bounce_id} + + Emails are suppressed by PostMark, when they receive a Hard bounce / Spam Complaint. This endpoint allows you to remove the suppression and send emails to the user again. + operationId: reactivateEmail parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -1059,7 +1122,11 @@ tags: - clients summary: 'Update tax data' - description: 'Updates the clients tax data - if their address has changed' + description: | + ## POST /api/v1/clients/{client}/updateTaxData + + Updates the clients tax data - if their address has changed + operationId: updateClientTaxData parameters: - $ref: '#/components/parameters/X-API-TOKEN' diff --git a/openapi/paths/locations.yaml b/openapi/paths/locations.yaml index 7f74c59764..8e58372719 100644 --- a/openapi/paths/locations.yaml +++ b/openapi/paths/locations.yaml @@ -3,26 +3,43 @@ tags: - locations summary: 'List locations' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("your_token"); + $invoices = $ninja->locations->all([]); + - lang: curl + label: curl + source: | + curl --request GET \ + --url 'https://demo.invoiceninja.com/api/v1/locations?per_page=10&page=1&sort=name&sort_dir=asc' \ + --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \ + --header 'Accept: application/json' description: | - When retrieving a list of locations you can chain query parameters to filter the dataset. For example: - - ``` - /api/v1/locations?name=warehouse* - ``` - - You can also sort the results: - - ``` - /api/v1/locations?sort=name|desc - ``` + ## GET /api/v1/locations - For pagination, use per_page and page parameters: - - ``` - /api/v1/locations?per_page=15&page=2 - ``` + Locations are additional addresses that are applicable to a client. This is useful when a client has multiple addresses for shipping, billing, etc. - The default per_page value is 20. + When retrieving a list of locations you can chain query parameters to filter the dataset. For example: + + ```html + /api/v1/locations?name=warehouse* + ``` + + You can also sort the results: + + ```html + /api/v1/locations?sort=name|desc + ``` + + For pagination, use per_page and page parameters: + + ```html + /api/v1/locations?per_page=15&page=2 + ``` + + The default per_page value is 20. operationId: getLocations parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -65,7 +82,12 @@ content: application/json: schema: - $ref: '#/components/schemas/Location' + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Location' 401: $ref: '#/components/responses/401' 403: @@ -81,7 +103,10 @@ tags: - locations summary: 'Create location' - description: 'Adds a location to a company' + description: | + ## POST /api/v1/locations + + Adds a location to a company x-codeSamples: - lang: php label: php @@ -171,7 +196,10 @@ tags: - locations summary: 'Show location' - description: 'Displays a location by id' + description: | + ## GET /api/v1/locations/{id} + + Displays a location by id operationId: showLocation parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -209,12 +237,28 @@ $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $location = $ninja->locations->show("D2J234DFA"); + - lang: curl + label: curl + source: | + curl --request GET \ + --url 'https://demo.invoiceninja.com/api/v1/locations/D2J234DFA' \ + --header 'X-API-TOKEN: YOUR-TOKEN' \ + --header 'Accept: application/json' put: tags: - locations summary: 'Update location' - description: 'Handles the updating of a location by id' + description: | + ## PUT /api/v1/locations/{id} + + Handles the updating of a location by id operationId: updateLocation parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -259,12 +303,37 @@ $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $location = $ninja->locations->update("D2J234DFA", [ + 'name' => 'Updated Location Name', + 'address1' => '456 New Street', + 'city' => 'Los Angeles' + ]); + - lang: curl + label: curl + source: | + curl -X PUT https://demo.invoiceninja.com/api/v1/locations/D2J234DFA \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "Content-Type: application/json" \ + -H "X-Requested-With: XMLHttpRequest" \ + -d '{ + "name": "Updated Location Name", + "address1": "456 New Street", + "city": "Los Angeles" + }' delete: tags: - locations summary: 'Delete location' - description: 'Handles the deletion of a location by id' + description: | + ## DELETE /api/v1/locations/{id} + + Handles the deletion of a location by id operationId: deleteLocation parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -297,13 +366,29 @@ $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $ninja->locations->delete("D2J234DFA"); + - lang: curl + label: curl + source: | + curl -X DELETE \ + --url 'https://demo.invoiceninja.com/api/v1/locations/D2J234DFA' \ + --header 'X-API-TOKEN: YOUR-TOKEN' \ + --header 'Accept: application/json' /api/v1/locations/create: get: tags: - locations summary: 'Blank Location' - description: 'Returns a blank object with default values' + description: | + ## GET /api/v1/locations/create + + Returns a blank object with default values operationId: getLocationsCreate parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -333,6 +418,19 @@ $ref: '#/components/responses/429' default: $ref: '#/components/responses/default' + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $location = $ninja->locations->model(); + - lang: curl + label: curl + source: | + curl --request GET \ + --url 'https://demo.invoiceninja.com/api/v1/locations/create' \ + --header 'X-API-TOKEN: YOUR-TOKEN' \ + --header 'Accept: application/json' /api/v1/locations/bulk: post: @@ -340,6 +438,8 @@ - locations summary: 'Bulk location actions' description: | + ## POST /api/v1/locations/bulk + Bulk actions allow to make changes to multiple locations in a single request. The following actions are supported: - archive @@ -349,6 +449,26 @@ All of these actions require an array of location ids to perform the requested action on ie. "ids":['id1','id2'] + x-codeSamples: + - lang: php + label: php + source: | + $ninja = new InvoiceNinja("YOUR-TOKEN"); + $ninja->locations->bulk([ + 'action' => 'archive', + 'ids' => ['locationId1', 'locationId2'] + ]); + - lang: curl + label: curl + source: | + curl -X POST https://demo.invoiceninja.com/api/v1/locations/bulk \ + -H "X-API-TOKEN: YOUR-TOKEN" \ + -H "Content-Type: application/json" \ + -H "X-Requested-With: XMLHttpRequest" \ + -d '{ + "action": "archive", + "ids": ["locationId1", "locationId2"] + }' operationId: bulkLocations parameters: - $ref: '#/components/parameters/X-API-TOKEN' @@ -384,4 +504,5 @@ 429: $ref: '#/components/responses/429' default: - $ref: '#/components/responses/default' \ No newline at end of file + $ref: '#/components/responses/default' + \ No newline at end of file