OpenAPIClient-php

Documentation of the Billbee REST API to connect a Billbee account to external aplications.

Endpoint

The Billbee API endpoint base url is https://api.billbee.io/api/v1

Activation

You have to enable the API in the settings of your Billbee account. In addition you need a Billbee API Key identifying the application you develop. To get an API key, send a mail to support@billbee.io and send us a short note about what you are building.

Authorization & security

Because you can access private data with the Billbee API, every request has to be sent over https and must

Contain a valid API Key identifying the application/developer. It has to be sent as the HTTP header X-Billbee-Api-Key
Contain a valid user login with billbee username and api password in form of a basic auth HTTP header

Throttling

50 calls per second for each API Key.

10 calls per second for each API Key in combination with Billbee user.

Besides that each endpoint has a throttle of max 2 requests per second per combination of API Key and Billbee user.

When you exceed the throttle threshold, the API will return a HTTP 429 status code and a Retry-After-Header indicating how many seconds you will have to wait before you can call the API again.

For more information, please visit https://www.billbee.io.

Installation & Usage

Requirements

PHP 7.4 and later. Should also work with PHP 8.0.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/kruegge82/billbee-php-sdk-api.git"
    }
  ],
  "require": {
    "GIT_USER_ID/GIT_REPO_ID": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure HTTP basic authorization: basicAuth
$config = kruegge82\billbee\Configuration::getDefaultConfiguration()
              ->setUsername('YOUR_USERNAME')
              ->setPassword('YOUR_PASSWORD');

// Configure API key authorization: ApiKeyAuth
$config = kruegge82\billbee\Configuration::getDefaultConfiguration()->setApiKey('X-Billbee-Api-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = kruegge82\billbee\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-Billbee-Api-Key', 'Bearer');


$apiInstance = new kruegge82\billbee\Api\CloudStorageApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

try {
    $result = $apiInstance->cloudStorageApiGetList();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling CloudStorageApi->cloudStorageApiGetList: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://app.billbee.io

Class	Method	HTTP request	Description
CloudStorageApi	cloudStorageApiGetList	GET /api/v1/cloudstorages	Gets a list of all connected cloud storage devices
CustomerAddressesApi	customerAddressesCreate	POST /api/v1/customer-addresses	Creates a new customer address
CustomerAddressesApi	customerAddressesGetAll	GET /api/v1/customer-addresses	Get a list of all customer addresses
CustomerAddressesApi	customerAddressesGetOne	GET /api/v1/customer-addresses/{id}	Queries a single customer address by id
CustomerAddressesApi	customerAddressesUpdate	PUT /api/v1/customer-addresses/{id}	Updates a customer address by id
CustomersApi	customerAddCustomerAddress	POST /api/v1/customers/{id}/addresses	Adds a new address to a customer
CustomersApi	customerCreate	POST /api/v1/customers	Creates a new customer
CustomersApi	customerGetAll	GET /api/v1/customers	Get a list of all customers
CustomersApi	customerGetCustomerAddress	GET /api/v1/customers/addresses/{id}	Queries a single address from a customer
CustomersApi	customerGetCustomerAddresses	GET /api/v1/customers/{id}/addresses	Queries a list of addresses from a customer
CustomersApi	customerGetCustomerOrders	GET /api/v1/customers/{id}/orders	Queries a list of orders from a customer
CustomersApi	customerGetOne	GET /api/v1/customers/{id}	Queries a single customer by id
CustomersApi	customerPatchAddress	PATCH /api/v1/customers/addresses/{id}	Updates one or more fields of an address
CustomersApi	customerUpdate	PUT /api/v1/customers/{id}	Updates a customer by id
CustomersApi	customerUpdateAddress	PUT /api/v1/customers/addresses/{id}	Updates all fields of an address
CustomersApi	searchSearch	POST /api/v1/search	Search for products, customers and orders. Type can be "order", "product" and / or "customer" Term can contain lucene query syntax
DeliveryNoteApi	orderApiCreateDeliveryNote	POST /api/v1/orders/CreateDeliveryNote/{id}	Create an delivery note for an existing order. This request is extra throttled by order and api key to a maximum of 1 per 5 minutes.
EnumApiApi	enumApiGetAccountSyncState	GET /api/v1/enums/accountsyncstate	Returns a list with all defined account sync states
EnumApiApi	enumApiGetOrderStates	GET /api/v1/enums/orderstates	Returns a list with all defined orderstates
EnumApiApi	enumApiGetPaymentTypes	GET /api/v1/enums/paymenttypes	Returns a list with all defined paymenttypes
EnumApiApi	enumApiGetShipmentTypes	GET /api/v1/enums/shipmenttypes	Returns a list with all defined shipmenttypes
EnumApiApi	enumApiGetShippingCarriers	GET /api/v1/enums/shippingcarriers	Returns a list with all defined shippingcarriers
EnumApiApi	enumApiGetShopAccountType	GET /api/v1/enums/shopaccounttype	Returns a list with all defined account types
EventsApi	eventApiGetList	GET /api/v1/events	Get a list of all events optionally filtered by date. This request is extra throttled to 2 calls per page per hour.
InvoiceApi	orderApiCreateInvoice	POST /api/v1/orders/CreateInvoice/{id}	Create an invoice for an existing order. This request is extra throttled by order and api key to a maximum of 1 per 5 minutes.
InvoiceApi	orderApiGetInvoiceList	GET /api/v1/orders/invoices	Get a list of all invoices optionally filtered by date. This request ist throttled to 1 per 1 minute for same page and minInvoiceDate
OrdersApi	layoutApiGetList	GET /api/v1/layouts
OrdersApi	orderApiAddShipment	POST /api/v1/orders/{id}/shipment	Add a shipment to a given order
OrdersApi	orderApiCreateDeliveryNote	POST /api/v1/orders/CreateDeliveryNote/{id}	Create an delivery note for an existing order. This request is extra throttled by order and api key to a maximum of 1 per 5 minutes.
OrdersApi	orderApiCreateInvoice	POST /api/v1/orders/CreateInvoice/{id}	Create an invoice for an existing order. This request is extra throttled by order and api key to a maximum of 1 per 5 minutes.
OrdersApi	orderApiFind	GET /api/v1/orders/find/{id}/{partner}	Find a single order by its external id (order number)
OrdersApi	orderApiGet	GET /api/v1/orders/{id}	Get a single order by its internal billbee id. This request is throttled to 6 calls per order in one minute
OrdersApi	orderApiGetByExtRef	GET /api/v1/orders/findbyextref/{extRef}	Get a single order by its external order number
OrdersApi	orderApiGetInvoiceList	GET /api/v1/orders/invoices	Get a list of all invoices optionally filtered by date. This request ist throttled to 1 per 1 minute for same page and minInvoiceDate
OrdersApi	orderApiGetList	GET /api/v1/orders	Get a list of all orders optionally filtered by date
OrdersApi	orderApiGetPatchableFields	GET /api/v1/orders/PatchableFields	Returns a list of fields which can be updated with the orders/{id} patch call
OrdersApi	orderApiMessage	POST /api/v1/orders/{id}/message	Adds a message to the order
OrdersApi	orderApiParsePlaceholders	POST /api/v1/orders/{id}/parse-placeholders	Parses a text and replaces all placeholders
OrdersApi	orderApiPatchOrder	PATCH /api/v1/orders/{id}	Updates one or more fields of an order
OrdersApi	orderApiPostNewOrder	POST /api/v1/orders	Creates a new order in the Billbee account
OrdersApi	orderApiSendMessage	POST /api/v1/orders/{id}/send-message	Sends a message to the buyer
OrdersApi	orderApiTagsCreate	POST /api/v1/orders/{id}/tags	Attach one or more tags to an order
OrdersApi	orderApiTagsUpdate	PUT /api/v1/orders/{id}/tags	Sets the tags attached to an order
OrdersApi	orderApiTriggerEvent	POST /api/v1/orders/{id}/trigger-event	Triggers a rule event
OrdersApi	orderApiUpdateState	PUT /api/v1/orders/{id}/orderstate	Changes the main state of a single order
OrdersApi	searchSearch	POST /api/v1/search	Search for products, customers and orders. Type can be "order", "product" and / or "customer" Term can contain lucene query syntax
ProductsApi	articleCreateArticle	POST /api/v1/products	Creates a new product
ProductsApi	articleDeleteArticle	DELETE /api/v1/products/{id}	Deletes a product
ProductsApi	articleDeleteImage	DELETE /api/v1/products/images/{imageId}	Deletes a single image by id
ProductsApi	articleDeleteImageFromProduct	DELETE /api/v1/products/{productId}/images/{imageId}	Deletes a single image from a product
ProductsApi	articleDeleteImages	POST /api/v1/products/images/delete
ProductsApi	articleGetArticle	GET /api/v1/products/{id}	Queries a single article by id or by sku
ProductsApi	articleGetCategory	GET /api/v1/products/category	GEts a list of all defined categories
ProductsApi	articleGetCustomField	GET /api/v1/products/custom-fields/{id}	Queries a single custom field
ProductsApi	articleGetCustomFields	GET /api/v1/products/custom-fields	Queries a list of all custom fields
ProductsApi	articleGetImage	GET /api/v1/products/images/{imageId}	Returns a single image by id
ProductsApi	articleGetImageFromProduct	GET /api/v1/products/{productId}/images/{imageId}	Returns a single image by id
ProductsApi	articleGetImages	GET /api/v1/products/{productId}/images	Returns a list of all images of the product
ProductsApi	articleGetList	GET /api/v1/products	Get a list of all products
ProductsApi	articleGetPatchableFields	GET /api/v1/products/PatchableFields	Returns a list of fields which can be updated with the patch call
ProductsApi	articleGetReservedAmount	GET /api/v1/products/reservedamount	Queries the reserved amount for a single article by id or by sku
ProductsApi	articleGetStocks	GET /api/v1/products/stocks	Query all defined stock locations
ProductsApi	articlePatchArticle	PATCH /api/v1/products/{id}	Updates one or more fields of a product
ProductsApi	articlePutImage	PUT /api/v1/products/{productId}/images/{imageId}	Add or update an existing image of a product
ProductsApi	articlePutImages	PUT /api/v1/products/{productId}/images	Add multiple images to a product or replace the product images by the given images
ProductsApi	articleUpdateStock	POST /api/v1/products/updatestock	Update the stock qty of an article
ProductsApi	articleUpdateStockCode	POST /api/v1/products/updatestockcode	Update the stock code of an article
ProductsApi	articleUpdateStockMultiple	POST /api/v1/products/updatestockmultiple	Update the stock qty for multiple articles at once
ProductsApi	searchSearch	POST /api/v1/search	Search for products, customers and orders. Type can be "order", "product" and / or "customer" Term can contain lucene query syntax
ProvisioningApi	automaticProvisioningCreateAccount	POST /api/v1/automaticprovision/createaccount	Creates a new Billbee user account with the data passed
ProvisioningApi	automaticProvisioningTermsInfo	GET /api/v1/automaticprovision/termsinfo	Returns infos about Billbee terms and conditions
ShipmentsApi	shipmentGetList	GET /api/v1/shipment/shipments	Get a list of all shipments optionally filtered by date. All parameters are optional.
ShipmentsApi	shipmentGetPing	GET /api/v1/shipment/ping
ShipmentsApi	shipmentGetShippingCarrier	GET /api/v1/shipment/shippingcarriers	Queries the currently available shipping carriers.
ShipmentsApi	shipmentGetShippingproviders	GET /api/v1/shipment/shippingproviders	Query all defined shipping providers
ShipmentsApi	shipmentPostShipment	POST /api/v1/shipment/shipment	Creates a new shipment with the selected Shippingprovider
ShipmentsApi	shipmentShipWithLabel	POST /api/v1/shipment/shipwithlabel	Creates a shipment for an order in billbee
ShopAccountsApi	shopAccountQueryShopAccounts	GET /api/v1/shopaccounts	Queries a list of avaible shop accounts
WebhooksApi	webHookManagementDelete	DELETE /api/v1/webhooks/{id}	Deletes an existing WebHook registration.
WebhooksApi	webHookManagementDeleteAll	DELETE /api/v1/webhooks	Deletes all existing WebHook registrations.
WebhooksApi	webHookManagementGet	GET /api/v1/webhooks	Gets all registered WebHooks for a given user.
WebhooksApi	webHookManagementGetFilters	GET /api/v1/webhooks/filters	Returns a list of all known filters you can use to register webhooks
WebhooksApi	webHookManagementLookup	GET /api/v1/webhooks/{id}	Looks up a registered WebHook with the given {id} for a given user.
WebhooksApi	webHookManagementPost	POST /api/v1/webhooks	Registers a new WebHook for a given user.
WebhooksApi	webHookManagementPut	PUT /api/v1/webhooks/{id}	Updates an existing WebHook registration.

Models

Authorization

Authentication schemes defined for the API:

basicAuth

Type: HTTP basic authentication

ApiKeyAuth

Type: API key
API key parameter name: X-Billbee-Api-Key
Location: HTTP header

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

support@billbee.io