PHPackages magrao/client-side-api - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. magrao/client-side-api ActiveLibrary[API Development](/categories/api) magrao/client-side-api ====================== Request handler for Bibliomundi authorized clients. 01204PHP Since Dec 15Pushed 4y ago5 watchersCompare [ Source](https://github.com/bibliomundi/client-side-api)[ Packagist](https://packagist.org/packages/magrao/client-side-api)[ RSS](/packages/magrao-client-side-api/feed)WikiDiscussions master Synced 4d ago READMEChangelogDependenciesVersions (1)Used By (0) \#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](https://drive.google.com/file/d/0BzwFNhJ9FBNwS0JCSzA3cXFPYUk/view). Requirements ============ [](#requirements) - [cURL](http://php.net/manual/en/book.curl.php) - [PHP >= 5.6](http://php.net/) - Knowledge of [Onix](http://www.editeur.org/83/Overview/) - Key and Secret. If you do not possess these credentials, please contact us at . Workflow ======== [](#workflow) 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.. Instalation =========== [](#instalation) 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' ``` Step 1 - Importing the ebooks to your store =========================================== [](#step-1---importing-the-ebooks-to-your-store) 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](https://github.com/bibliomundi/client-side-api/blob/master/onix-essential.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](https://github.com/bibliomundi/client-side-api/tree/master/lib/BBM/examples/catalog.php). Step 2 - Inserting the ebooks in your store =========================================== [](#step-2---inserting-the-ebooks-in-your-store) Once having imported our ebooks´s [XML](https://github.com/bibliomundi/client-side-api/blob/master/onix-essential.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](https://github.com/bibliomundi/client-side-api/blob/master/onix-essential.xml) you will see an example of the XML, which we deliver to you using ONIX standard, and the information we consider most essential. Step 3 - Daily Updates ====================== [](#step-3---daily-updates) 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. Step 4 - Transactions ===================== [](#step-4---transactions) 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](https://github.com/bibliomundi/client-side-api/blob/master/currency.md) 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](https://github.com/bibliomundi/client-side-api/tree/master/lib/BBM/examples/purchase.php). 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. Refund a Purchase (Work in Progress) ==================================== [](#refund-a-purchase-work-in-progress) 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. fieldtyperequireddescriptiontransaction\_keystringyesthe transaction key you sent us when you created the purchase through our APIebook\_idsarrayyesan array containing the ids of the ebooks you want to refund from the purchaserefund\_reasonstringyesthe reason why the refund is being requestedHere'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(); ``` ### The Response [](#the-response) In the response, you will receive an associative array where the keys are each one of ebook\_ids you sent into the request. fieldtypedescriptioncodeintegerinternal response code regarding the action of execution of the refundmessagestringthe message of the execution of the refundThere 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. ### The Message Codes [](#the-message-codes) codemessage-1Ebook was not found in this transaction0Refund has already been refused(reason will be in the message)1Refund has already been sent to imprint's analysis2Refund has already been approved3Refund has been sent to imprint's analysis4Refund has automatically been approved5Refund has automatically been refusedErrors ====== [](#errors) 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](https://github.com/bibliomundi/client-side-api/blob/master/errors.md). We have also made available the [documentation](https://github.com/bibliomundi/client-side-api/tree/master/docs/) generated by [PHPDoc.](http://www.phpdoc.org/) ### Health Score 19 — LowBetter than 10% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity12 Limited adoption so far Community13 Small or concentrated contributor base Maturity27 Early-stage or recently created project Bus Factor1 Top contributor holds 67.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/2b20e3c898a1cd3e6ab1a1a70674481c623566e4e90678276391921c21c593ee?d=identicon)[xxMAGRAOxx](/maintainers/xxMAGRAOxx) --- Top Contributors [![victorfcm](https://avatars.githubusercontent.com/u/1637099?v=4)](https://github.com/victorfcm "victorfcm (37 commits)")[![ventuinha](https://avatars.githubusercontent.com/u/10697425?v=4)](https://github.com/ventuinha "ventuinha (18 commits)") ### Embed Badge ![Health badge](/badges/magrao-client-side-api/health.svg) ``` [![Health](https://phpackages.com/badges/magrao-client-side-api/health.svg)](https://phpackages.com/packages/magrao-client-side-api) ``` ### Alternatives [stripe/stripe-php Stripe PHP Library 4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk A PHP wrapper for Twilio's API 1.6k92.9M272](/packages/twilio-sdk)[knplabs/github-api GitHub API v3 client 2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk PHP SDK for Facebook Business 90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php PHP wrapper for the Meilisearch API 73813.7M114](/packages/meilisearch-meilisearch-php)[google/gax Google API Core for PHP 263103.1M454](/packages/google-gax) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)