Sellsy API V2 PHP client

• Introduction
• Installation
• Usage
  • Authenticate
  • Query the API
    • The basics
    • Operations
    • Index a resource
    • Show a resource
    • Create a resource
    • Update a resource
    • Delete a resource
• Contribute
• Credits
• License

⚠️ This client helps you query the Sellsy API V2.
If you're looking for a client for the API V1, checkout TeknooSoftware/sellsy-client instead.

Introduction

// TODO

Installation

This library requires PHP >= 7.4.

Grab the library using composer :

composer require hydrat-agency/sellsy-client

Usage

Authenticate

This package only supports "Personnal" OAuth client credentials authentication.
Before calling any API class (or the Client helper), you MUST provide your credentials via the Config class :

use Hydrat\Sellsy\Api\ContactsApi;
use Hydrat\Sellsy\Core\Client;
use Hydrat\Sellsy\Core\Config;

$config = Config::getInstance();

$config->set('url', 'https://api.sellsy.com/v2/') // optionnal, this is the default value.
       ->set('client_id', 'f48f0fgm-2703-5689-2005-27403b5adb8d')
       ->set('client_secret', 'av8v94jx0ildsjje50sm9x1hnmjsg27bnqyryc0zgbmtxxmzpjzlw2vnj9aockwe');

$client = new Client();

$client->contacts()->index()->json(); // List contacts from API.

Learn more about Sellsy API v2 credentials.

Query the API

The basics

The easiest way to start querying the API is to initialize the corresponding class and call the needed method(s) :

use Hydrat\Sellsy\Api\ContactsApi;

$contacts = new ContactsApi();

$contacts->show($contact_id);

You may also use the client helper that holds all API namespaces using methods. The downside is that you would lose the editor documentation.

use Hydrat\Sellsy\Core\Client;

(new Client())->contacts()->show($contact_id);

# Or statically :
Client::contacts()->show($contact_id);

Operations

ℹ️ To illustrate this part of the documentation, we will use the ContactsApi endpoint.

This client is using the CRUD operations keywords to name API methods :

Client Keyword	Related operation
index	List resources.
show	Get a single resource.
create	Create a single resource.
update	Update a single resource.
destroy	Delete a single resource.
search	Search resources.

Classic methods signatures :

public function index(array $query = []): self;
public function show(string $id, array $query = []): self;
public function store(Contact $contact, array $query = []): self;
public function update(Contact $contact, array $query = []): self;
public function destroy(int $id): self;

When querying the API, you get back an API object containing a response. If something goes wrong, a RequestException will be thrown.
Most of the time, you only need to get the response entity sent back from the API. However, you can also make use of other available methods :

use Hydrat\Sellsy\Api\ContactsApi;

$contacts = new ContactsApi();

$api = $contacts->index();   # List
$api = $contacts->get(123);  # Get

$api->entity();      # Get single resource entity, when available
$api->entities();    # Get resource entities collection, when available (for listing/search)
$api->pagination();  # Get the pagination object, when available
$api->json();        # Get raw json data from response, as associative array
$api->response();    # Get the \Illuminate\Http\Client\Response object

Under the hood, this client uses the Laravel HTTP client, which is a minimal wrapper around the Guzzle HTTP client. By calling the response() method, you get a Response object containing a variety of methods that may be used to inspect the response :

$api->response()->body(): string;
$api->response()->json(): array|mixed;
$api->response()->status(): int;
$api->response()->ok(): bool;
$api->response()->successful(): bool;
$api->response()->failed(): bool;
$api->response()->serverError(): bool;
$api->response()->clientError(): bool;
$api->response()->header($header): string;
$api->response()->headers(): array;

This client make use of DTO objects (called Entity). Results from api are parsed into DTO objects, and the client expects DTO objects as argument when manipulating entities in the API.
Under the hood, we are using the spatie/data-transfer-object library, so make sure to consult their documentation if you're unsure about DTO objects.

List a resource

To list a resource, we use the index() method. This method accept query parameters as only argument.

$contacts = new ContactsApi();

$index = $contacts->index();

$index->entities();    // The API entities
$index->pagination();  // The pagination DTO

Show a resource

To show a resource, we use the show() method. This method accept the resource id as first parameter :

$contacts = new ContactsApi();

$contacts->show(123)->entity();

This returns a Hydrat\Sellsy\Entities\Contact instance :

Hydrat\Sellsy\Entities\Contact^ {
  +id: 35520506
  +civility: "ms"
  +first_name: "Amélie"
  +last_name: "PETIT"
  +email: "[email protected]"
  +website: null
  +phone_number: null
  +mobile_number: null
  +fax_number: null
  +position: "Gérante"
  +birth_date: null
  +avatar: null
  +note: ""
  +social: Hydrat\Sellsy\Entities\ContactSocials^ {
    +twitter: null
    +facebook: null
    +linkedin: null
    +viadeo: null
  }
  +sync: Hydrat\Sellsy\Entities\ContactSync^ {
    +mailchimp: true
    +mailjet: true
    +simplemail: true
  }
  +is_archived: false
  +invoicing_address_id: null
  +delivery_address_id: null
  +invoicing_address: null
  +delivery_address: null
  +created: "2022-02-16T15:56:17+01:00"
  +owner: array:2 [
    "id" => 214007
    "type" => "staff"
  ]
}

As described in the Sellsy documentation, you may also send query parameters embed and field. This can be done by specifying the query parameters as the second argument of the show() method :

$query = [
  'embed' => [
    'invoicing_address',
  ],
  'field' => [
    'first_name',
    'email',
  ],
];

$contacts->show(123, $query)->entity();

When specifing $embed entities, the client will automatically parse them into subsequent entity classes :

Hydrat\Sellsy\Entities\Contact^ {
  +id: 35520506
  +email: "[email protected]"
  [...]
  +invoicing_address: Hydrat\Sellsy\Entities\Address^ {
    +id: 128934588
    +name: "Domicile"
    +address_line_1: "34 Rue du moulin"
    +address_line_2: ""
    +address_line_3: ""
    +address_line_4: ""
    +postal_code: "75001"
    +city: "Paris"
    +country: "France"
    +country_code: "FR"
    +is_invoicing_address: true
    +is_delivery_address: false
    +geocode: Hydrat\Sellsy\Entities\Geocode^ {
      +lat: 42.1040
      +lng: 6.43010
    }
  }
}

Create a resource

When creating a resource, the store() method should be called. This method expect the entity object as first argument and $query parameters as second argument :

use Hydrat\Sellsy\Entities\Contact;
use Hydrat\Sellsy\Entities\ContactSync;
use Hydrat\Sellsy\Entities\ContactSocials;

$contacts = new ContactsApi();

$contacts->store(new Contact([
    'civility'      => 'mr',
    'first_name'    => 'Jean',
    'last_name'     => 'MOULIN',
    'email'         => '[email protected]',
    'website'       => 'example.com',
    'mobile_number' => '0612121212',
    'position'      => 'Directeur',
    'social'        => new ContactSocials([
        'twitter' => 'https://twitter.com/u/example',
    ]),
    'sync'          => new ContactSync(),
]));

The API returns the entity, therefore you can chain ->entity() to retreive the created entity.

Update a resource

When updating a resource, the update() method should be called. This method expect the Contact entity to be updated as first parameter and $query parameters as second argument :

use Hydrat\Sellsy\Entities\Contact;

$contacts = new ContactsApi();

$contacts->update(new Contact([
    'id'         => 35536947,
    'first_name' => 'Jean',
    'last_name'  => 'CASTEX',
    'note'       => '',
]));

The API returns the entity, therefore you can chain ->entity() to retreive the created entity.

Delete a resource

When deleting a resource, the destroy() method should be called. This method only expect the resource id to be deleted :

$contacts->delete(123)->json();

Contribute

Feel free to contribute to the package !
If you find any security issue, please contact me at [email protected] instead of creating a public github issue.

First contribution guide

Credits

• Thomas Georgel
• All Contributors

License

The MIT License (MIT). Please see License File for more information.