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

373
openapi/api-docs.yaml
View File

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

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'

133
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,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'

169
openapi/paths/locations.yaml
View File

@ -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'
$ref: '#/components/responses/default'