Client Addresses

12 vues Markdown

The five endpoints that read, add, update and delete an address in a client's address book.

Overview

A client can hold several addresses, and an invoice is issued to one of them. The address book is separate from the client record.

One address is the default. Making a new address the default clears the flag on the previous one; there is never more than one default.

Notification preferences

A notification preference is stored as a bitmask: one number carrying several choices.

Reference

Listing Addresses

get/api/v1/admin/clients/{id}/addresses
Clients/GetClientAddresses admin

Returns the client's whole address book. The default one is flagged with is_default.

Response fields data[] — 17
idintAddress id.
full_namestringFull name.
labelstringAddress label, for example Office.
typestringindividual or corporate.
emailstringEmail address.
phonestringPhone; digits only are stored.
identitystringIdentity or tax number.
companyobjectTax details on a corporate address.
namestringTrading name.
tax_numberstringTax number.
tax_officestringTax office.
country_idintCountry id. Resolve with reference/countries.
statestringState or region.
citystringCity.
addressstringStreet address.
zipcodestringPostcode. At most 20 characters.
is_defaultboolWhether this is the default address.
email_notificationsintEmail notification preference (bitmask).
sms_notificationsintSMS notification preference (bitmask).
statusstringactive or passive.
Errors 2
not_found404No such client or address.
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/clients/42/addresses' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Accept: application/json'
const res  = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$response = Api::Clients()->GetClientAddresses(['id' => 42]);

foreach ($response['data'] as $address) {
    if ($address['is_default']) {
        $invoiceAddress = $address;
    }
}

Adding an Address

post/api/v1/admin/clients/{id}/addresses
Clients/CreateClientAddress admin

Adds a record to the address book and returns it in the same schema as the list.

Body 16 fields, 5 required
full_namestringrequiredFull name.
emailstringrequiredValidated for format.
country_idintrequiredCountry id. List: reference/countries.
statestringrequiredState or region.
citystringrequiredCity.
typestringindividual or corporate. Defaults to individual.
labelstringAddress label.
phonestringPhone; digits only are stored.
identitystringIdentity or tax number.
companyobjectTax details on a corporate address.
namestringTrading name.
tax_numberstringTax number.
tax_officestringTax office.
addressstringStreet address.
zipcodestringPostcode. At most 20 characters.
is_defaultboolMakes this the default address.
email_notificationsintEmail notification preference. Defaults to all on.
sms_notificationsintSMS notification preference. Defaults to all on.
overwrite_invoicesboolApplies this address to the client's open invoices as well.
Response fields data
dataobjectThe address created, returned with 201. Same shape as the list schema.
Errors 4
not_found404No such client or address.
email_invalid422Email format is not valid.
address_add_failed500The record could not be created.
insufficient_scope403The key lacks the required scope.
Request 
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/addresses' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"full_name":"John Doe","email":"[email protected]","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}'
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"full_name":"John Doe","email":"[email protected]","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'full_name'  => 'John Doe',
        'email'      => '[email protected]',
        'country_id' => 840,
        'state'      => 'California',
        'city'       => 'San Francisco',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$response = Api::Clients()->CreateClientAddress([
    'id'         => 42,
    'full_name'  => 'John Doe',
    'email'      => '[email protected]',
    'country_id' => 840,
    'state'      => 'California',
    'city'       => 'San Francisco',
    'is_default' => true,
]);

$addressId = $response['data']['id'] ?? 0;
Response 
{
  "data": {
    "id": 13,
    "full_name": "John Doe",
    "type": "individual",
    "country_id": 840,
    "city": "San Francisco",
    "zipcode": "94105",
    "is_default": true,
    "status": "active"
  }
}
{
  "error": {
    "code": "email_invalid",
    "message": "A valid email is required."
  }
}

Address Detail

get/api/v1/admin/clients/{id}/addresses/{addr_id}
Clients/GetClientAddress admin

Returns one address. The schema is the same as in the list.

Response fields data
dataobjectThe address itself. Same shape as the list schema.
Errors 2
not_found404No such client or address.
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$response = Api::Clients()->GetClientAddress(['id' => 42, 'addr_id' => 13]);

Updating an Address

put/api/v1/admin/clients/{id}/addresses/{addr_id}
Clients/UpdateClientAddress admin full replace

Updates the address. The body takes the same fields as create, and the required ones stay required.

Body the same 16 fields as create
full_namestringrequiredFull name.
emailstringrequiredValidated for format.
country_idintrequiredCountry id.
statestringrequiredState or region.
citystringrequiredCity.
overwrite_invoicesboolApplies the change to the client's open invoices as well.
Response fields data
dataobjectThe address after the update. Same shape as the list schema.
Errors 7
not_found404No such client or address.
full_name_required422full_name is required.
email_invalid422A valid email is required.
country_required422country_id is required.
state_required422state is required.
city_required422city is required.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"full_name":"John Doe","email":"[email protected]","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}'
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"full_name":"John Doe","email":"[email protected]","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($address),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The required fields are sent again: this is a full update, not a partial one.
$response = Api::Clients()->UpdateClientAddress([
    'id'         => 42,
    'addr_id'    => 13,
    'full_name'  => 'John Doe',
    'email'      => '[email protected]',
    'country_id' => 840,
    'state'      => 'California',
    'city'       => 'San Francisco',
]);

Deleting an Address

delete/api/v1/admin/clients/{id}/addresses/{addr_id}
Clients/DeleteClientAddress admin

Deletes the address and returns the id that was removed.

Response fields data
deletedboolWhether the delete succeeded.
idintId of the deleted address.
Errors 1
not_found404No such client or address.
Request 
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$response = Api::Clients()->DeleteClientAddress(['id' => 42, 'addr_id' => 13]);

Pitfalls

There is only one default

Flagging an address with is_default clears the flag on the previous one. You do not have to update the old address; two defaults cannot exist.

Open invoices do not change by themselves

Updating an address does not reach invoices that were already issued. Send overwrite_invoices if you want it to.

The update is not partial

The endpoint is PUT. Leave a required field out and the request is refused; sending only the changed field is not enough.

Cet article vous a-t-il été utile ?

Merci pour votre retour !

Besoin d'aide supplémentaire ?

Notre équipe d'assistance est disponible 24h/24 pour tout ce que vous ne trouvez pas ci-dessus.

Nous contacter Ouvrir un ticket

Nous utilisons des cookies pour vous garder connecté, mémoriser votre langue et votre devise, et améliorer le site. Politique relative aux cookies