Skip to content

Latest commit

 

History

History
324 lines (271 loc) · 36 KB

README.md

File metadata and controls

324 lines (271 loc) · 36 KB
Raw

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 [email protected] 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/GIT_USER_ID/GIT_REPO_ID.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_0 POST /api/v1/search Search for products, customers and orders. Type can be &quot;order&quot;, &quot;product&quot; and / or &quot;customer&quot; Term can contain lucene query syntax
DeliveryNoteApi orderApiCreateDeliveryNote_0 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_0 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_0 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_1 POST /api/v1/search Search for products, customers and orders. Type can be &quot;order&quot;, &quot;product&quot; and / or &quot;customer&quot; 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 &quot;order&quot;, &quot;product&quot; and / or &quot;customer&quot; 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

[email protected]