Sultan
/
invoiceninja
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve locations api documentation

This commit is contained in:
David Bomba 2025-03-24 09:04:25 +11:00
parent 4710376f75
commit 644e4b7d08
6 changed files with 560 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
app/Jobs/Subscription/CleanStaleInvoiceOrder.php
View File

@ -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);
});

315
openapi/api-docs.yaml
View File

@ -9109,22 +9109,39 @@ 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: |
## GET /api/v1/locations
Locations are additional addresses that are applicable to a client. This is useful when a client has multiple addresses for shipping, billing, etc.
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
```
@ -9171,6 +9188,11 @@ paths:
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Location'
401:
$ref: '#/components/responses/401'
@ -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,6 +13517,8 @@ paths:
- clients
summary: 'Create client'
description: |
## POST /api/v1/clients
Adds a client to a company
> 🚨 Important
@ -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,6 +14129,8 @@ paths:
- clients
summary: 'Purge client'
description: |
## POST /api/v1/clients/{id}/purge
Handles purging a client.
> ❗ Note
@ -13968,6 +14189,8 @@ paths:
- clients
summary: 'Merge client'
description: |
## POST /api/v1/clients/{id}/{mergeable_client_hashed_id}/merge
Handles merging 2 clients
The id parameter is the client that will be the primary client after the merge has completed.
@ -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

25
openapi/components/schemas/client_contact_request.yaml
View File

@ -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

1
openapi/components/schemas/client_request.yaml
View File

@ -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'

105
openapi/paths/clients.yaml
View File

@ -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,6 +236,8 @@
- clients
summary: 'Create client'
description: |
## POST /api/v1/clients
Adds a client to a company
> 🚨 Important
@ -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,6 +848,8 @@
- clients
summary: 'Purge client'
description: |
## POST /api/v1/clients/{id}/purge
Handles purging a client.
> ❗ Note
@ -855,6 +908,8 @@
- clients
summary: 'Merge client'
description: |
## POST /api/v1/clients/{id}/{mergeable_client_hashed_id}/merge
Handles merging 2 clients
The id parameter is the client that will be the primary client after the merge has completed.
@ -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'

137
openapi/paths/locations.yaml
View File

@ -3,22 +3,39 @@
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: |
## GET /api/v1/locations
Locations are additional addresses that are applicable to a client. This is useful when a client has multiple addresses for shipping, billing, etc.
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
```
@ -65,6 +82,11 @@
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Location'
401:
$ref: '#/components/responses/401'
@ -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'
@ -385,3 +505,4 @@
$ref: '#/components/responses/429'
default:
$ref: '#/components/responses/default'