#About the API We are Bibliomundi, an ebook distributor and have made this api with the purpose of integrating our ebooks with your store's platform. In order to commercialize our ebooks at your store, it does require knowledge of programing. OBS: This API requires knowledge of PHP coding. In case you work with other coding standards, we have published the complete webservice which may be accessed through this link.

• cURL
• PHP >= 5.6
• Knowledge of Onix
• Key and Secret. If you do not possess these credentials, please contact us at contato@bibliomundi.com.br.

1. Import our complete calalogue. We will deliver the complete ONIX standard XML with all o four active ebooks.

2. Insert the ebooks from our database following the ONIX standard.

3. Update daily to verify if there are new ebooks, in case of a metadata update (e.g. title change) or if there are ebooks that have been deactivated which need to be removed from sale. We deliver an ONIX standard XML with the ebooks that require updating, adding or deleting.

4. Enable the ebooks for sale at your store.

5. Enable the download for a customer..

Simply download (or clone), add to your Project and then make a call to the file “autoload.php”, which is located within the "lib" folder. Concluding this step, you will have access to all of the API´s functionalities.

Ex: require 'lib/autoload.php'

Instance the Catalogue class by sending your credentials as parameter.

$catalog = new BBM\Catalog('YOUR_API_KEY', 'YOUR_API_SECRET');

Define if the environmente you will import our ebooks will be Production or Sandbox.

$catalog->environment = 'production';
ou
$catalog->environment = 'sandbox'; 

The following code is optional. It allows you to filter for ebooks which contain or not DRM protection.

 
$catalog->filters( array('drm' => 'no') );)//Will only deliver unprotected
ou
$catalog->filters( array('drm' => 'yes') );)// Will only deliver protected

Another optional code. We offer the option of importing the ebook covers at a pre-determined size, allowing you to save on server space, for example.

$catalog->filters( array('image_height' => 500) ););//Delivers covers at the height of 500px
...
$catalog->filters( array('image_width' => 700) ););//Delivers covers at the width of 700px
...
$catalog->filters( array('image_width' => 1024, 'image_height' => 768) );//Delivers covers at the width of 1024px e height de 768px

At the end of this step, validate your credentials and import de ebooks.

try
{
    $catalog->validate();//Validate your transactions
    $xml = $catalog->get();//Returns an XML, with the string format and ONIX standard, containing all the active ebooks in our platform
}
catch(\BBM\Server\Exception $e)
{
    var_dump($e);
}

Each tag <Product> returned by XML is an ebook. You will run through all of them, following the ONIX standard and insert them into your database.

For more details, view an example here.

Once having imported our ebooks´s XML, you may work in the matter you prefer but we strongly recommend using a Parser, like PHP´s Simple XML for example. It will be your responsibility to insert the ebooks with a minimum amount of basic information. We also recommend not inserting titles which are not available for sale, and for that you must check the tags <PublishingStatus> and <ProductAvailability>. By clicking here you will see an example of the XML, which we deliver to you using ONIX standard, and the information we consider most essential.

Our routine is to update our systems daily and you will have to create one too.Create a daily routine to verify if there are new titles added, updated or removed. We recommend you create a task reminder to run between 01 and 06 AM (GMT -3) in order to avoid displaying ebooks with outdated information resulting in an error generation.

Simply add a third parameter called 'updates'.

$catalog = new BBM\Catalog('YOUR_API_KEY', 'YOUR_API_SECRET', 'updates');

It does not change the routine for the usual request.

$catalog->environment = 'production';
ou
$catalog->environment = 'sandbox';

try
{
    $catalog->validate();//Validate your credentials
    $xml = $catalog->get();//Returns an XML with the ebooks and their respective routines (insert, update or delete) in a string format and ONIX

standard
}
catch(\BBM\Server\Exception $e)
{
    var_dump($e);
}

For each tag <Product>, returned by the XML, there is a tag named <NotificationType> indicating the operation to be performed.

Ex: 03 -> inserir. 04 -> Atualizar. 05 -> Deletar.

Once you have finished importing the catalogue, your consumers will be able to purchase the ebooks. Every time a consumer attempts to purchase an ebook from us, it is required that you validate the transaction with us before they head to the checkout. Notice that your validation and checkout and our validation and checkout are two different processes. You must always validate and checkout with us so that we may be aware that the transaction has been made so that we may approve the ebook´s download. Keep that in mind.

Workflow::

• Consumer purchases one or more of our products.
• You validade the transaction through the Validate() funcition.
• If confirmed you may proceed to both your and our checkouts.

Instance a Purchase class by sending your credentials as parameters.

$purchase = new BBM\Purchase('YOUR_API_KEY', 'YOUR_API_SECRET');

Choose your environment.

$catalog->environment = 'production';
ou
$catalog->environment = 'sandbox';

Send us the user information that made the transaction respecting the rules below.

$customer = [
    'customerIdentificationNumber' => 1, // INT, YOUR STORE CUSTOMER ID
    'customerFullname' => 'CUSTOMER NAME', // STRING, CUSTOMER FULL NAME
    'customerEmail' => 'customer@email.com', // STRING, CUSTOMER EMAIL
    'customerGender' => 'm', // ENUM, CUSTOMER GENDER, USE m OR f (LOWERCASE!! male or female)
    'customerBirthday' => '1991/11/03', // STRING, CUSTOMER BIRTH DATE, USE Y/m/d (XXXX/XX/XX)
    'customerCountry' => 'BR', // STRING, 2 CHAR STRING THAT INDICATE THE CUSTOMER COUNTRY (BR, US, ES, etc)
    'customerZipcode' => '31231223', // STRING, POSTAL CODE, ONLY NUMBERS
    'customerState' => 'RJ' // STRING, 2 CHAR STRING THAT INDICATE THE CUSTOMER STATE (RJ, SP, NY, etc)
];

$purchase->setCustomer($customer);

Then insert the ebook by adding its ID and Price and then inform the currency.

$purchase->addItem($ebookID, $ebookPrice, 'USD');

Check here the full list.

OBS: You may add as many ebooks as necessary by simply repeating the procedure.

Then validate the ebooks and follow to checkout.

try
{
    $purchase->validate();
    
    //A transaction key may be anything but we recommend using the same as the effective transaction. It will be requested when the attempting to download the ebooks related to this checkout.
    $purchase->checkout('TRANSACTION_KEY', time());
}
catch(\BBM\Server\Exception $e)
{
    var_dump($e);
}

Done. If everything has run smoothly, you have just registered a sale with us.

For more detailes, se the following example here.

OBS..

• Do not sell the ebook to your customer without validating with us first,because there are conditions which may invalidate the sale such as your store not being active or issues with the ebook.
• Do not forget to confirm the checkout with us and you must only do so once the payment is confirmed with your client.

Sometimes your customer may want to request a refund and doing so, your store needs to send us the request.

You only need three fields.

Here's a code sample.

$sale_reverser = new BBM\RefundPurchase(CLIENT_ID, CLIENT_SECRET);

$data = [
    'transaction_key' => 'MY_STORE_TRANSACTION',
    'ebook_ids' => [/*ebook_ids from the transaction*/],
    'refund_reason' => "Reason for the refund"
];

$response = $sale_reverser->requestRefund();

In the response, you will receive an associative array where the keys are each one of ebook_ids you sent into the request.

There are two cases where the refund will be automatically accepted:

• was requested within period demanded by law(seven days);
• the store and the ebooks's imprint belong to the same company.

Otherwise, the request will be sent to the imprint and you will have to wait for their approval.

Errors may occur at all stages (Complete, Update, Validate, Checkout and Download) and will be of your responsibility to treat them and inform to the user if it is the case. Regardless of the requisition which is being made, we always return an Exception with information about the error. You may check the errors list and their respective stages here. We have also made available the documentation generated by PHPDoc.