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() ->cursor()
->each(function ($invoice) use ($repo) { ->each(function ($invoice) use ($repo) {
$invoice->is_proforma = false; $invoice->is_proforma = false;
$invoice->save();
$repo->delete($invoice); $repo->delete($invoice);
}); });
@ -162,6 +163,7 @@ class CleanStaleInvoiceOrder implements ShouldQueue
->cursor() ->cursor()
->each(function ($invoice) use ($repo) { ->each(function ($invoice) use ($repo) {
$invoice->is_proforma = false; $invoice->is_proforma = false;
$invoice->save();
$repo->delete($invoice); $repo->delete($invoice);
}); });

313
openapi/api-docs.yaml
View File

@ -9109,22 +9109,39 @@ paths:
tags: tags:
- locations - locations
summary: 'List 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: | 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: When retrieving a list of locations you can chain query parameters to filter the dataset. For example:
``` ```html
/api/v1/locations?name=warehouse* /api/v1/locations?name=warehouse*
``` ```
You can also sort the results: You can also sort the results:
``` ```html
/api/v1/locations?sort=name|desc /api/v1/locations?sort=name|desc
``` ```
For pagination, use per_page and page parameters: For pagination, use per_page and page parameters:
``` ```html
/api/v1/locations?per_page=15&page=2 /api/v1/locations?per_page=15&page=2
``` ```
@ -9171,6 +9188,11 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Location' $ref: '#/components/schemas/Location'
401: 401:
$ref: '#/components/responses/401' $ref: '#/components/responses/401'
@ -9187,7 +9209,57 @@ paths:
tags: tags:
- locations - locations
summary: 'Create location' 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 operationId: storeLocation
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -9230,7 +9302,10 @@ paths:
tags: tags:
- locations - locations
summary: 'Show location' summary: 'Show location'
description: 'Displays a location by id' description: |
## GET /api/v1/locations/{id}
Displays a location by id
operationId: showLocation operationId: showLocation
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -9268,12 +9343,28 @@ paths:
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/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: put:
tags: tags:
- locations - locations
summary: 'Update location' 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 operationId: updateLocation
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -9318,12 +9409,37 @@ paths:
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/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: delete:
tags: tags:
- locations - locations
summary: 'Delete location' 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 operationId: deleteLocation
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -9356,13 +9472,29 @@ paths:
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/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: /api/v1/locations/create:
get: get:
tags: tags:
- locations - locations
summary: 'Blank Location' 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 operationId: getLocationsCreate
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -9392,6 +9524,19 @@ paths:
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/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: /api/v1/locations/bulk:
post: post:
@ -9399,6 +9544,8 @@ paths:
- locations - locations
summary: 'Bulk location actions' summary: 'Bulk location actions'
description: | description: |
## POST /api/v1/locations/bulk
Bulk actions allow to make changes to multiple locations in a single request. The following actions are supported: Bulk actions allow to make changes to multiple locations in a single request. The following actions are supported:
- archive - archive
@ -9408,6 +9555,26 @@ paths:
All of these actions require an array of location ids to perform the requested action on ie. All of these actions require an array of location ids to perform the requested action on ie.
"ids":['id1','id2'] "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 operationId: bulkLocations
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -9444,6 +9611,7 @@ paths:
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/default' $ref: '#/components/responses/default'
/api/v1/recurring_invoices: /api/v1/recurring_invoices:
get: get:
tags: tags:
@ -13115,7 +13283,8 @@ paths:
get: get:
tags: tags:
- clients - clients
summary: 'List clients' summary: |
List clients
x-codeSamples: x-codeSamples:
- lang: php - lang: php
label: php label: php
@ -13135,31 +13304,32 @@ paths:
--header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \ --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
--header 'Accept: application/json' --header 'Accept: application/json'
description: | 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 /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 /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* /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' /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 /api/v1/clients?per_page=15&page=2
@ -13347,6 +13517,8 @@ paths:
- clients - clients
summary: 'Create client' summary: 'Create client'
description: | description: |
## POST /api/v1/clients
Adds a client to a company Adds a client to a company
> 🚨 Important > 🚨 Important
@ -13387,7 +13559,8 @@ paths:
"first_name": "John", "first_name": "John",
"last_name": "Smith", "last_name": "Smith",
"email": "john@example.com", "email": "john@example.com",
"phone": "555-0123" "phone": "555-0123",
"send_email": true
} }
], ],
"address1": "123 Main St", "address1": "123 Main St",
@ -13403,7 +13576,6 @@ paths:
- $ref: '#/components/parameters/index' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
requestBody: requestBody:
description: Client object that needs to be added to the company
required: true required: true
content: content:
application/json: application/json:
@ -13438,7 +13610,11 @@ paths:
tags: tags:
- clients - clients
summary: 'Show client' summary: 'Show client'
description: 'Displays a client by id' description: |
## GET /api/v1/clients/{id}
Displays a client by id
x-codeSamples: x-codeSamples:
- lang: php - lang: php
label: php label: php
@ -13495,6 +13671,8 @@ paths:
- clients - clients
summary: 'Update client' summary: 'Update client'
description: | description: |
## PUT /api/v1/clients/{id}
Handles the updating of a client by id Handles the updating of a client by id
> 🚨 Important > 🚨 Important
@ -13583,12 +13761,17 @@ paths:
- clients - clients
summary: 'Delete client' summary: 'Delete client'
description: | description: |
## DELETE /api/v1/clients/{id}
Handles the deletion of a client by id Handles the deletion of a client by id
> ❗ Note > ❗ Note
Deleting a client does not purge the client from the system. The delete action will remove the clients data from all 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 views in the application but keep it on file in case it needs to be restored.
all of their records from the system, use the /purge route
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: x-codeSamples:
- lang: php - lang: php
@ -13642,7 +13825,21 @@ paths:
tags: tags:
- clients - clients
summary: 'Edit Client' 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 operationId: editClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -13686,7 +13883,23 @@ paths:
tags: tags:
- clients - clients
summary: 'Blank Client' 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 operationId: getClientsCreate
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -13723,6 +13936,8 @@ paths:
- clients - clients
summary: 'Bulk client actions' summary: 'Bulk client actions'
description: | description: |
## POST /api/v1/clients/bulk
Bulk actions allow to make changes to multiple clients in a single request the following actions are supported Bulk actions allow to make changes to multiple clients in a single request the following actions are supported
- archive - archive
@ -13744,7 +13959,7 @@ paths:
- assign_group - assign_group
Allows the setting of multiple clients to a single group Allows setting multiple clients to a single group
- bulk_update - bulk_update
@ -13822,7 +14037,11 @@ paths:
tags: tags:
- clients - clients
summary: 'Add client document' 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: x-codeSamples:
- lang: php - lang: php
label: php label: php
@ -13910,6 +14129,8 @@ paths:
- clients - clients
summary: 'Purge client' summary: 'Purge client'
description: | description: |
## POST /api/v1/clients/{id}/purge
Handles purging a client. Handles purging a client.
> ❗ Note > ❗ Note
@ -13968,6 +14189,8 @@ paths:
- clients - clients
summary: 'Merge client' summary: 'Merge client'
description: | description: |
## POST /api/v1/clients/{id}/{mergeable_client_hashed_id}/merge
Handles merging 2 clients Handles merging 2 clients
The id parameter is the client that will be the primary client after the merge has completed. The id parameter is the client that will be the primary client after the merge has completed.
@ -14038,7 +14261,11 @@ paths:
tags: tags:
- clients - clients
summary: 'Client statement PDF' 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 operationId: clientStatement
x-codeSamples: x-codeSamples:
- lang: php - lang: php
@ -14128,7 +14355,11 @@ paths:
tags: tags:
- clients - clients
summary: 'Removes email suppression of a user in the system' 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 operationId: reactivateEmail
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -14172,7 +14403,11 @@ paths:
tags: tags:
- clients - clients
summary: 'Update tax data' 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 operationId: updateClientTaxData
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $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. 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 type: number
format: integer format: integer
$ref: '#/components/schemas/CountryType'
example: '1' example: '1'
custom_value1: custom_value1:
description: 'A custom field for storing additional information' description: 'A custom field for storing additional information'
@ -21701,49 +21937,44 @@ components:
type: object type: object
ClientContactRequest: ClientContactRequest:
properties: properties:
id:
description: 'The hashed if of the contact'
type: string
example: Opnel5aKBz
readOnly: true
first_name: first_name:
description: 'The first name of the contact' description: 'The first name of the contact'
type: string type: string
example: John example: Sarah
last_name: last_name:
description: 'The last name of the contact' description: 'The last name of the contact'
type: string type: string
example: Doe example: Johnson
phone: phone:
description: 'The phone number of the contact' description: 'The phone number of the contact'
type: string type: string
example: 555-152-4524 example: '+1-555-123-4567'
custom_value1: custom_value1:
description: 'A Custom field value' description: 'A Custom field value'
type: string type: string
example: '' example: 'Preferred Customer'
custom_value2: custom_value2:
description: 'A Custom field value' description: 'A Custom field value'
type: string type: string
example: '' example: 'West Region'
custom_value3: custom_value3:
description: 'A Custom field value' description: 'A Custom field value'
type: string type: string
example: '' example: 'Referral: Jane Smith'
custom_value4: custom_value4:
description: 'A Custom field value' description: 'A Custom field value'
type: string type: string
example: '' example: 'Account #12345'
email: email:
description: 'The email of the contact' description: 'The email of the contact'
type: string type: string
example: '' example: 'sarah.johnson@example.com'
password: password:
description: 'The hashed password of the contact' description: 'The hashed password of the contact'
type: string type: string
example: '*****' example: '$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi'
send_email: 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 type: boolean
example: true example: true
type: object type: object

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

@ -1,48 +1,43 @@
ClientContactRequest: ClientContactRequest:
properties: properties:
id:
description: 'The hashed if of the contact'
type: string
example: Opnel5aKBz
readOnly: true
first_name: first_name:
description: 'The first name of the contact' description: 'The first name of the contact'
type: string type: string
example: John example: Sarah
last_name: last_name:
description: 'The last name of the contact' description: 'The last name of the contact'
type: string type: string
example: Doe example: Johnson
phone: phone:
description: 'The phone number of the contact' description: 'The phone number of the contact'
type: string type: string
example: 555-152-4524 example: '+1-555-123-4567'
custom_value1: custom_value1:
description: 'A Custom field value' description: 'A Custom field value'
type: string type: string
example: '' example: 'Preferred Customer'
custom_value2: custom_value2:
description: 'A Custom field value' description: 'A Custom field value'
type: string type: string
example: '' example: 'West Region'
custom_value3: custom_value3:
description: 'A Custom field value' description: 'A Custom field value'
type: string type: string
example: '' example: 'Referral: Jane Smith'
custom_value4: custom_value4:
description: 'A Custom field value' description: 'A Custom field value'
type: string type: string
example: '' example: 'Account #12345'
email: email:
description: 'The email of the contact' description: 'The email of the contact'
type: string type: string
example: '' example: 'sarah.johnson@example.com'
password: password:
description: 'The hashed password of the contact' description: 'The hashed password of the contact'
type: string type: string
example: '*****' example: '$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi'
send_email: 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 type: boolean
example: true example: true
type: object 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. 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 type: number
format: integer format: integer
$ref: '#/components/schemas/CountryType'
example: '1' example: '1'
custom_value1: custom_value1:
description: 'A custom field for storing additional information' description: 'A custom field for storing additional information'

103
openapi/paths/clients.yaml
View File

@ -2,7 +2,8 @@
get: get:
tags: tags:
- clients - clients
summary: 'List clients' summary: |
List clients
x-codeSamples: x-codeSamples:
- lang: php - lang: php
label: php label: php
@ -22,31 +23,32 @@
--header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \ --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
--header 'Accept: application/json' --header 'Accept: application/json'
description: | 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 /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 /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* /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' /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 /api/v1/clients?per_page=15&page=2
@ -234,6 +236,8 @@
- clients - clients
summary: 'Create client' summary: 'Create client'
description: | description: |
## POST /api/v1/clients
Adds a client to a company Adds a client to a company
> 🚨 Important > 🚨 Important
@ -274,7 +278,8 @@
"first_name": "John", "first_name": "John",
"last_name": "Smith", "last_name": "Smith",
"email": "john@example.com", "email": "john@example.com",
"phone": "555-0123" "phone": "555-0123",
"send_email": true
} }
], ],
"address1": "123 Main St", "address1": "123 Main St",
@ -290,7 +295,6 @@
- $ref: '#/components/parameters/index' - $ref: '#/components/parameters/index'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
requestBody: requestBody:
description: Client object that needs to be added to the company
required: true required: true
content: content:
application/json: application/json:
@ -325,7 +329,11 @@
tags: tags:
- clients - clients
summary: 'Show client' summary: 'Show client'
description: 'Displays a client by id' description: |
## GET /api/v1/clients/{id}
Displays a client by id
x-codeSamples: x-codeSamples:
- lang: php - lang: php
label: php label: php
@ -382,6 +390,8 @@
- clients - clients
summary: 'Update client' summary: 'Update client'
description: | description: |
## PUT /api/v1/clients/{id}
Handles the updating of a client by id Handles the updating of a client by id
> 🚨 Important > 🚨 Important
@ -470,12 +480,17 @@
- clients - clients
summary: 'Delete client' summary: 'Delete client'
description: | description: |
## DELETE /api/v1/clients/{id}
Handles the deletion of a client by id Handles the deletion of a client by id
> ❗ Note > ❗ Note
Deleting a client does not purge the client from the system. The delete action will remove the clients data from all 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 views in the application but keep it on file in case it needs to be restored.
all of their records from the system, use the /purge route
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: x-codeSamples:
- lang: php - lang: php
@ -529,7 +544,21 @@
tags: tags:
- clients - clients
summary: 'Edit Client' 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 operationId: editClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -573,7 +602,23 @@
tags: tags:
- clients - clients
summary: 'Blank Client' 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 operationId: getClientsCreate
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -610,6 +655,8 @@
- clients - clients
summary: 'Bulk client actions' summary: 'Bulk client actions'
description: | description: |
## POST /api/v1/clients/bulk
Bulk actions allow to make changes to multiple clients in a single request the following actions are supported Bulk actions allow to make changes to multiple clients in a single request the following actions are supported
- archive - archive
@ -631,7 +678,7 @@
- assign_group - assign_group
Allows the setting of multiple clients to a single group Allows setting multiple clients to a single group
- bulk_update - bulk_update
@ -709,7 +756,11 @@
tags: tags:
- clients - clients
summary: 'Add client document' 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: x-codeSamples:
- lang: php - lang: php
label: php label: php
@ -797,6 +848,8 @@
- clients - clients
summary: 'Purge client' summary: 'Purge client'
description: | description: |
## POST /api/v1/clients/{id}/purge
Handles purging a client. Handles purging a client.
> ❗ Note > ❗ Note
@ -855,6 +908,8 @@
- clients - clients
summary: 'Merge client' summary: 'Merge client'
description: | description: |
## POST /api/v1/clients/{id}/{mergeable_client_hashed_id}/merge
Handles merging 2 clients Handles merging 2 clients
The id parameter is the client that will be the primary client after the merge has completed. The id parameter is the client that will be the primary client after the merge has completed.
@ -925,7 +980,11 @@
tags: tags:
- clients - clients
summary: 'Client statement PDF' 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 operationId: clientStatement
x-codeSamples: x-codeSamples:
- lang: php - lang: php
@ -1015,7 +1074,11 @@
tags: tags:
- clients - clients
summary: 'Removes email suppression of a user in the system' 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 operationId: reactivateEmail
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -1059,7 +1122,11 @@
tags: tags:
- clients - clients
summary: 'Update tax data' 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 operationId: updateClientTaxData
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'

137
openapi/paths/locations.yaml
View File

@ -3,22 +3,39 @@
tags: tags:
- locations - locations
summary: 'List 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: | 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: When retrieving a list of locations you can chain query parameters to filter the dataset. For example:
``` ```html
/api/v1/locations?name=warehouse* /api/v1/locations?name=warehouse*
``` ```
You can also sort the results: You can also sort the results:
``` ```html
/api/v1/locations?sort=name|desc /api/v1/locations?sort=name|desc
``` ```
For pagination, use per_page and page parameters: For pagination, use per_page and page parameters:
``` ```html
/api/v1/locations?per_page=15&page=2 /api/v1/locations?per_page=15&page=2
``` ```
@ -65,6 +82,11 @@
content: content:
application/json: application/json:
schema: schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Location' $ref: '#/components/schemas/Location'
401: 401:
$ref: '#/components/responses/401' $ref: '#/components/responses/401'
@ -81,7 +103,10 @@
tags: tags:
- locations - locations
summary: 'Create location' summary: 'Create location'
description: 'Adds a location to a company' description: |
## POST /api/v1/locations
Adds a location to a company
x-codeSamples: x-codeSamples:
- lang: php - lang: php
label: php label: php
@ -171,7 +196,10 @@
tags: tags:
- locations - locations
summary: 'Show location' summary: 'Show location'
description: 'Displays a location by id' description: |
## GET /api/v1/locations/{id}
Displays a location by id
operationId: showLocation operationId: showLocation
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -209,12 +237,28 @@
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/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: put:
tags: tags:
- locations - locations
summary: 'Update location' 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 operationId: updateLocation
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -259,12 +303,37 @@
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/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: delete:
tags: tags:
- locations - locations
summary: 'Delete location' 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 operationId: deleteLocation
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -297,13 +366,29 @@
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/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: /api/v1/locations/create:
get: get:
tags: tags:
- locations - locations
summary: 'Blank Location' 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 operationId: getLocationsCreate
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -333,6 +418,19 @@
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/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: /api/v1/locations/bulk:
post: post:
@ -340,6 +438,8 @@
- locations - locations
summary: 'Bulk location actions' summary: 'Bulk location actions'
description: | description: |
## POST /api/v1/locations/bulk
Bulk actions allow to make changes to multiple locations in a single request. The following actions are supported: Bulk actions allow to make changes to multiple locations in a single request. The following actions are supported:
- archive - archive
@ -349,6 +449,26 @@
All of these actions require an array of location ids to perform the requested action on ie. All of these actions require an array of location ids to perform the requested action on ie.
"ids":['id1','id2'] "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 operationId: bulkLocations
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -385,3 +505,4 @@
$ref: '#/components/responses/429' $ref: '#/components/responses/429'
default: default:
$ref: '#/components/responses/default' $ref: '#/components/responses/default'