README

##关于API 我们是Bibliomundi，一家电子书发行商，我们制作了这个API的目的是将我们的电子书与您的商店平台集成。为了在您的商店商业化我们的电子书，确实需要编程知识。注意：此API需要PHP编程知识。如果您使用其他编码标准，我们已发布了完整的webservice，可以通过此链接访问。

要求

cURL
PHP >= 5.6
了解ONIX
密钥和秘密。如果您没有这些凭据，请联系我们contato@bibliomundi.com.br。

工作流程

导入我们的完整目录。我们将提供包含所有四个活跃电子书的完整ONIX标准XML。
根据ONIX标准从我们的数据库中插入电子书。
每天更新以验证是否有新的电子书，如果是元数据更新（例如，标题更改）或如果需要从销售中删除已停用的电子书。我们提供需要更新、添加或删除的电子书的ONIX标准XML。
在您的商店中启用电子书销售。
启用客户下载。

安装

只需下载（或克隆），添加到您的项目中，然后调用位于"lib"文件夹中的文件“autoload.php”。完成此步骤后，您将能够访问API的所有功能。

Ex: require 'lib/autoload.php'

步骤1 - 将电子书导入您的商店

通过发送您的凭据作为参数来实例化目录类。

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

定义您将导入我们的电子书的环境是生产还是沙盒。

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

以下代码是可选的。它允许您筛选包含或不包含DRM保护的电子书。

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

另一段可选代码。我们提供导入预定大小的电子书封面选项，例如，可以帮助您节省服务器空间。

$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

在此步骤结束时，验证您的凭据并导入电子书。

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);
}

XML返回的每个<Product>标签都是一个电子书。您将遍历所有这些标签，按照ONIX标准将它们插入到您的数据库中。

有关更多详细信息，请查看此处的示例。

步骤2 - 在您的商店中插入电子书

导入我们的电子书的XML后，您可以按您喜欢的任何方式工作，但我们强烈建议使用解析器，例如PHP的Simple XML。您将负责以基本信息的最少量插入电子书。我们还建议不要插入不可销售的标题，为此您必须检查标签<PublishingStatus>和<ProductAvailability>。通过单击此处，您将看到我们使用ONIX标准提供的XML示例以及我们认为最重要的信息。

步骤 3 - 每日更新

我们的常规是每天更新系统，您也需要这样做。创建一个每日例行程序来验证是否添加、更新或删除了新的标题。我们建议您在凌晨 01 至 06 点（GMT -3）之间创建一个任务提醒，以避免显示过时信息的电子书导致错误生成。

只需添加一个名为 'updates' 的第三个参数。

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

它不会改变常规的请求。

$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);
}

对于 XML 返回的每个 <Product> 标签，都有一个名为 <NotificationType> 的标签，指示要执行的操作。

例如：03 -> 添加。 04 -> 更新。 05 -> 删除。

步骤 4 - 交易

一旦您完成目录的导入，您的消费者就可以购买电子书了。每次消费者尝试从我们这里购买电子书时，您都需要在我们进行结账之前验证交易。请注意，您的验证和结账以及我们的验证和结账是两个不同的过程。您必须始终与我们进行验证和结账，以便我们知道交易已经完成，以便我们可以批准电子书的下载。请记住这一点。

工作流程：

消费者购买我们的一个或多个产品。
您通过 Validate() 函数验证交易。
如果确认，您可以进行您和我们的结账。

通过发送您的凭证作为参数来实例化一个 Purchase 类。

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

选择您的环境。

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

按照以下规则发送进行交易的用户信息。

$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);

然后通过添加其 ID 和价格来插入电子书，并告知货币。

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

请在此处查看完整的列表：这里。

OBS: 您可以通过简单地重复此程序添加所需的电子书数量。

然后验证电子书并继续结账。

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);
}

完成。如果一切顺利，您已向我们注册了一笔销售。

有关更多详细信息，请参阅以下示例这里。

OBS..

在验证我们之前，不要向您的客户销售电子书，因为存在一些可能使销售无效的条件，例如您的商店未激活或电子书存在问题。
不要忘记与我们确认结账，并且您只能在向客户确认付款后进行一次。

退款购买（进行中）

有时您的客户可能要求退款，在这种情况下，您的商店需要向我们发送请求。

您只需要三个字段。

以下是一个代码示例。

$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();

响应

在响应中，您将收到一个关联数组，其中的键是您在请求中发送的每个 ebook_ids。

有两种情况，退款将自动接受：

在法律规定的期间内（七天内）提出请求；
商店和电子书出版社属于同一家公司。

否则，请求将发送到出版社，您将必须等待他们的批准。

消息代码

错误

错误可能发生在所有阶段（完整、更新、验证、结账和下载），您负责处理它们并在必要时通知用户。无论正在执行什么请求，我们都会返回一个包含错误信息的异常。您可以在此处查看错误列表及其相应阶段这里。我们还提供了由 PHPDoc 生成的文档。

magrao / client-side-api

维护者

详细信息