519 lines
16 KiB
YAML
519 lines
16 KiB
YAML
/api/v1/locations:
|
|
get:
|
|
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
|
|
```
|
|
|
|
The default per_page value is 20.
|
|
operationId: getLocations
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- name: name
|
|
in: query
|
|
description: |
|
|
Filter by location name
|
|
|
|
```html
|
|
?name=warehouse
|
|
```
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: warehouse
|
|
- name: sort
|
|
in: query
|
|
description: |
|
|
Returns the list sorted by column in ascending or descending order.
|
|
|
|
```html
|
|
?sort=name|desc
|
|
```
|
|
required: false
|
|
schema:
|
|
type: string
|
|
example: name|desc
|
|
responses:
|
|
200:
|
|
description: 'A list of locations'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Location'
|
|
meta:
|
|
type: object
|
|
$ref: '#/components/schemas/Meta'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
|
|
post:
|
|
tags:
|
|
- locations
|
|
summary: 'Create location'
|
|
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'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
requestBody:
|
|
description: Location object that needs to be added to the company
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LocationRequest'
|
|
responses:
|
|
200:
|
|
description: 'Returns the saved location object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Location'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
|
|
'/api/v1/locations/{id}':
|
|
get:
|
|
tags:
|
|
- locations
|
|
summary: 'Show location'
|
|
description: |
|
|
## GET /api/v1/locations/{id}
|
|
|
|
Displays a location by id
|
|
operationId: showLocation
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- name: id
|
|
in: path
|
|
description: 'The Location Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
responses:
|
|
200:
|
|
description: 'Returns the location object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Location'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$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: |
|
|
## PUT /api/v1/locations/{id}
|
|
|
|
Handles the updating of a location by id
|
|
operationId: updateLocation
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
- name: id
|
|
in: path
|
|
description: 'The Location Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
requestBody:
|
|
description: Location object that needs to be updated
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LocationRequest'
|
|
responses:
|
|
200:
|
|
description: 'Returns the location object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Location'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$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: |
|
|
## DELETE /api/v1/locations/{id}
|
|
|
|
Handles the deletion of a location by id
|
|
operationId: deleteLocation
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- name: id
|
|
in: path
|
|
description: 'The Location Hashed ID'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: string
|
|
example: D2J234DFA
|
|
responses:
|
|
200:
|
|
description: 'Returns a HTTP status'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$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: |
|
|
## GET /api/v1/locations/create
|
|
|
|
Returns a blank object with default values
|
|
operationId: getLocationsCreate
|
|
parameters:
|
|
- $ref: '#/components/parameters/X-API-TOKEN'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
responses:
|
|
200:
|
|
description: 'A blank location object'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Location'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$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:
|
|
tags:
|
|
- 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
|
|
- restore
|
|
- delete
|
|
|
|
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'
|
|
- $ref: '#/components/parameters/X-Requested-With'
|
|
- $ref: '#/components/parameters/index'
|
|
requestBody:
|
|
description: 'Bulk action array'
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GenericBulkAction'
|
|
responses:
|
|
200:
|
|
description: 'The Location list Response of the updated locations that were bulk updated'
|
|
headers:
|
|
X-MINIMUM-CLIENT-VERSION:
|
|
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
|
|
X-RateLimit-Remaining:
|
|
$ref: '#/components/headers/X-RateLimit-Remaining'
|
|
X-RateLimit-Limit:
|
|
$ref: '#/components/headers/X-RateLimit-Limit'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Location'
|
|
meta:
|
|
type: object
|
|
$ref: '#/components/schemas/Meta'
|
|
401:
|
|
$ref: '#/components/responses/401'
|
|
403:
|
|
$ref: '#/components/responses/403'
|
|
422:
|
|
$ref: '#/components/responses/422'
|
|
429:
|
|
$ref: '#/components/responses/429'
|
|
default:
|
|
$ref: '#/components/responses/default'
|
|
|