valconsultby/byfax-php

PHP的byFax公共API SDK

维护者

详细信息

github.com/valconsultby/byfax-php

源代码

问题

安装: 1

依赖关系: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 0

公开问题: 0

1.1.0 2021-12-24 14:12 UTC

Requires

  • php: >=7.0.0

proprietary 09d06719e3e03026bde850be8d8aeafd6056c14a

  • ValConsultBy PUE <contact.woop@pamconsult.by>

phpapisdkfaxbyfax

This package is auto-updated.

Last update: 2024-09-24 20:28:12 UTC

README

byFax是一个在线传真平台，允许您在没有传真机或其他设备的浏览器中或通过此处展示的API集成中发送和接收传真。有关该平台及其功能的信息，可以在byFax网站上找到（https://byfax.biz）。

目录结构

  enum/          contains enumerations
  model/         contains data models (entities, requests, responses)
  samples/       contains sample scripts

要求

本项目最低要求您的Web服务器支持PHP 7.0.0。

状态

https://packagist.org.cn/packages/valconsultby/byfax-php

安装

安装此扩展的首选方法是通过composer

php composer.phar require --prefer-dist valconsultby/byfax-php

服务

要开始使用API，您需要创建一个byFax应用程序并获取api密钥和api密钥来授权您的应用程序访问API。在您实现解决方案时，您有一个功能齐全的测试环境，位于https://sandbox.byfax.biz。当您的解决方案完成后，服务的基本URL将更改为生产环境的https://api.byfax.biz。请参阅以下服务列表。

示例

授权

该应用程序使用包含api密钥和api密钥的特殊SOAP头授权API。该头由一个UsernameToken对象表示。

授权头在每次请求中传递，连接到API没有会话和额外的令牌。

$apiKey = "YOUR-API-KEY";
$apiSecret = "YOUR-API-SECRET";
$apiUrl = "https://sandbox.byfax.biz"; // Replace with https://api.byfax.biz for production

// Create "document " API service and pass API key-secret and url data
$serviceDoc = new \byfax\ApiServiceDocumentSoapClient($apiKey, $apiSecret, $apiUrl);

封面页。列表

byFax提供了更多个性化的传真封面页。系统已加载了一个基本封面页集，这些封面页可以通过API以及byFax客户门户访问。

门户用户和API开发人员都可以在其应用程序中添加自定义封面页。封面页是一个包含预定义占位符的DocX文件，在发送过程中用发送者和接收者的数据替换这些占位符。

$apiKey = "YOUR-API-KEY";
$apiSecret = "YOUR-API-SECRET";
$apiUrl = "https://sandbox.byfax.biz"; // Replace with https://api.byfax.biz for production

// Create "cover" API service and pass API key-secret and url data
$serviceCover = new \byfax\ApiServiceCoverSoapClient($apiKey, $apiSecret, $apiUrl);

// call "listCovers" function and obtain response
$response = $serviceCover->listCovers();

// Check response state code for success and return false if failed
if ($response->stateCode != StateCodes::SUCCESS)
      return false;

封面页。添加新

要添加封面页，您应将DocX文件上传到系统中并设置其名称。

$apiKey = "YOUR-API-KEY";
$apiSecret = "YOUR-API-SECRET";
$apiUrl = "https://sandbox.byfax.biz"; // Replace with https://api.byfax.biz for production

// Create "cover" API service and pass API key-secret and url data
$serviceCover = new \byfax\ApiServiceCoverSoapClient($apiKey, $apiSecret, $apiUrl);

$filename = "/path/to/user/cover.docx";

// Create and fill FaxFile object
$coverDoc = new \byfax\model\entity\common\FaxFile();
$coverDoc->fileSize = filesize($filename);
$coverDoc->fileCheck = md5_file($filename);
$coverDoc->fileName = basename($filename);
$coverDoc->fileMime = mime_content_type($filename);
$coverDoc->fileData = file_get_contents($filename); // Read file data without encoding to Base64

// Call Api function "addCover" to upload a new cover page
$response = $serviceCover->addCover("Test cover name", $coverDoc);

// Check response state code for success and return false if failed
if ($response->stateCode != StateCodes::SUCCESS)
      return false;

// Store newly created cover page refID
$coverReference = response->objectRef;

预加载文档

如果必须多次或发送给许多收件人发送同一文件，系统提供了上传文档并将其保存以供进一步重用的功能。

$apiKey = "YOUR-API-KEY";
$apiSecret = "YOUR-API-SECRET";
$apiUrl = "https://sandbox.byfax.biz"; // Replace with https://api.byfax.biz for production

// Create "document " API service and pass API key-secret and url data
$serviceDoc = new \byfax\ApiServiceDocumentSoapClient($apiKey, $apiSecret, $apiUrl);

$filename = "/path/to/user/file.pdf";

// Create and fill FaxDocument object
$uploadDoc = new \byfax\model\entity\common\FaxDocument();
$uploadDoc->documentFile = new \byfax\model\entity\common\FaxFile();

$uploadDoc->documentFile->fileSize = filesize($filename);
$uploadDoc->documentFile->fileCheck = md5_file($filename);
$uploadDoc->documentFile->fileName = basename($filename);
$uploadDoc->documentFile->fileMime = mime_content_type($filename);
$uploadDoc->documentFile->fileData = file_get_contents($filename); // Read file data without encoding to Base64

// Call Api function "uploadDocument" to upload a document to cache
$response = $serviceDoc->uploadDocument($uploadDoc);

// Check response state code for success and return false if failed
if ($response->stateCode != StateCodes::SUCCESS)
      return false;

// Store uploaded document refID for firther use
$uploadedRef = $response->fileRef;

发送传真（常见提交方式）

系统提供了许多选项来传递发送传真请求 - 在请求中直接加载文档，使用之前上传的文档，使用封面页，以高或标准质量提交传真，以文本或照片模式提交传真，为请求中的一份或多份文档提交传真，为一份或多份收件人提交传真，设置自己的传真抬头格式，设置忙线时的重试次数等。下面是一个使用最常见选项的示例。

$apiKey = "YOUR-API-KEY";
$apiSecret = "YOUR-API-SECRET";
$apiUrl = "https://sandbox.byfax.biz"; // Replace with https://api.byfax.biz for production

// Create "faxout" API service and pass API key-secret and url data
$serviceFax = new \byfax\ApiServiceFaxoutSoapClient($apiKey, $apiSecret, $apiUrl);

// Crate and fill fax submission request data
$submitRequest = new \byfax\model\request\faxout\ApiRequestFaxjobSubmit();

// Submission broadcast refID.
// Unique within your API account
// Should be unique for each submission
// Uncomment this line to set at your side otherwise API will generate.
// $submitRequest->broadcastRef = md5("my-broadcast-ref" . microtime(true));

// Fax header format template
$submitRequest->Header = "<DateTime> <Timezone>|From: <From> To: <To>|Page <CurPage>of <CurPages>";

// Sender timezone
$submitRequest->Timezone = "Europe/Minsk";

// Number of reties in case of Busy or NoAnswer
$submitRequest->busyRetry = 3;

// Send quality. Available options are STANDARD or FINE. See the enumeration
$submitRequest->sendQuality = \byfax\enum\FaxQuality::FINE;

// Send mode. Available options are TEXT or PHOTO. See the enumeration
$submitRequest->sendMode = \byfax\enum\FaxMode::TEXT;

// Cover page if needed to add to fax, skip otherwise. Use listCovers to obtain a cover RefID.
$submitRequest->Cover = new \byfax\model\entity\cover\FaxCover();
$submitRequest->Cover->coverRef = "COVER_PAGE_REF_ID";

// Sender identification. At least one of properties is required
$submitRequest->Sender = new \byfax\model\entity\common\FaxContact();
$submitRequest->Sender->Name = "My sender name";
$submitRequest->Sender->Company = "My sender company";
$submitRequest->Sender->Number = "+375 99 111111111";

// Recipient object. Number and Name/Company are required.
$submitRecipient = new \byfax\model\entity\common\FaxRecipient();
// Unique message reference-ID. 
// Uncomment this line to set at your side otherwise API will generate.
// $submitRecipient->messageRef = md5("my-message-ref" . microtime(true));  
$submitRecipient->Name = "Recipient name";
$submitRecipient->Company = "Recipient company";
$submitRecipient->Number = "+375 99 111111122";

// Push recipient object to array and create another if it is a batch job
$submitRequest->Recipients[] = $submitRecipient;

// Document object with previously uploaded file.
$submitDoc = new \byfax\model\entity\common\FaxDocument();
$submitDoc->documentRef = $uploadedRef;

// Push document object into the array. Add another one if needed.
$submitRequest->Documents[] = $submitDoc;

$filename = "/path/to/user/file.pdf";

// Document object with a file to upload within exact fax submission.
$submitDoc = new \byfax\model\entity\common\FaxDocument();
$submitDoc->documentFile = new \app\components\byfax\model\entity\common\FaxFile();
$submitDoc->documentFile->fileSize = filesize($filePath);
$submitDoc->documentFile->fileCheck = md5_file($filePath);
$submitDoc->documentFile->fileName = basename($filePath);
$submitDoc->documentFile->fileMime = mime_content_type($filePath);
$submitDoc->documentFile->fileData = file_get_contents($filePath);

// Push document object into the array.
$submitRequest->Documents[] = $submitDoc;

// Call "Submit" API function to push fax into the queue
$response = $serviceFax->Submit($submitRequest);

// Check response state code for success and return false if failed
if ($response->stateCode != StateCodes::SUCCESS)
      return false;

// Create and fill check-state request for a single recipient
$checkRequest = new \byfax\model\request\faxout\ApiRequestFaxjobListMessages();
$checkRequest->messageRefs[] = $response->reportRecipients[0]->messageRef;

// Add and fill pagination data
$checkRequest->pagination = new \byfax\model\entity\common\ListPagination();
$checkRequest->pagination->pageNumber = 0;
$checkRequest->pagination->pageSize = 10;

// Call "listRecipients" API function to obtain recipients status
$checkResponse = $serviceFaxout->listRecipients($checkRequest);

// Check response state code for success and return false if failed
if ($checkResponse->stateCode != StateCodes::SUCCESS)
return false;

// Obtain and store recipient status
$recipientStatus = $checkResponse->Messages[0]->jobState;

发送传真（准备好的TIFF提交）

此方法专门设计用于将准备好的TIFF文件发送给单个收件人。仅当TIFF文件在应用程序端准备，并且必须通过byFax文档准备系统发送时才使用此方法。使用此方法，应用程序应仅传递以下数据：发件人详情（发件人对象）、收件人详情（收件人对象）、容器唯一标识符（broadcastRef参数）和准备好的TIFF文件（文档对象）。还可以传递传真抬头全文，以便将其放在页面顶部。如果抬头已放置在文档的所有页面上，则将header参数传递为空字符串。以下是使用此函数的示例。

$apiKey = "YOUR-API-KEY";
$apiSecret = "YOUR-API-SECRET";
$apiUrl = "https://sandbox.byfax.biz"; // Replace with https://api.byfax.biz for production

// Create "faxout" API service and pass API key-secret and url data
$serviceFax = new \byfax\ApiServiceFaxoutSoapClient($apiKey, $apiSecret, $apiUrl);

// Crate and fill fax submission request data
$submitRequest = new \byfax\model\request\faxout\ApiRequestFaxjobMessage();

// Submission broadcast refID.
// Unique within your API account
// Should be unique for each submission
// Uncomment this line to set at your side otherwise API will generate.
// $submitRequest->broadcastRef = md5("my-broadcast-ref" . microtime(true));

// Submission message refID.
// Unique within your API account
// Should be unique for each recipient withn the entire account
// Uncomment this line to set at your side otherwise API will generate.
// $submitRequest->messageRef = md5("my-message-ref" . microtime(true));

// Fax header format template
$submitRequest->Header = "<DateTime> <Timezone>|From: <From> To: <To>|Page <CurPage>of <CurPages>";

// Sender timezone
$submitRequest->Timezone = "Europe/Minsk";

// Number of reties in case of Busy or NoAnswer
$submitRequest->busyRetry = 3;

// Sender identification. At least one of properties is required
$submitRequest->Sender = new \byfax\model\entity\common\FaxContact();
$submitRequest->Sender->Name = "My sender name";
$submitRequest->Sender->Company = "My sender company";
$submitRequest->Sender->Number = "+375 99 111111111";

// Recipient object. Number and Name/Company are required.
$submitRequest->Recipient = new \byfax\model\entity\common\FaxContact();
$submitRequest->Recipient->Name = "Recipient name";
$submitRequest->Recipient->Company = "Recipient company";
$submitRequest->Recipient->Number = "+375 99 111111122";

$filename = "/path/to/user/file.pdf";

// Document object with a file to upload within exact fax submission.
$submitRequest->Document = new \byfax\model\entity\common\FaxDocument();
$submitRequest->Document->documentFile = new \app\components\byfax\model\entity\common\FaxFile();
$submitRequest->Document->documentFile->fileSize = filesize($filePath);
$submitRequest->Document->documentFile->fileCheck = md5_file($filePath);
$submitRequest->Document->documentFile->fileName = basename($filePath);
$submitRequest->Document->documentFile->fileMime = mime_content_type($filePath);
$submitRequest->Document->documentFile->fileData = file_get_contents($filePath);


// Call "SubmitMessage" API function to push fax into the queue
$response = $serviceFax->SubmitMessage($submitRequest);

// Check response state code for success and return false if failed
if ($response->stateCode != StateCodes::SUCCESS)
      return false;


// Create and fill check-state request for a single recipient
$checkRequest = new \byfax\model\request\faxout\ApiRequestFaxjobListMessages();
$checkRequest->messageRefs[] = $response->reportRecipients[0]->messageRef;

// Add and fill pagination data
$checkRequest->pagination = new \byfax\model\entity\common\ListPagination();
$checkRequest->pagination->pageNumber = 0;
$checkRequest->pagination->pageSize = 10;

// Call "listRecipients" API function to obtain recipients status
$checkResponse = $serviceFaxout->listRecipients($checkRequest);

// Check response state code for success and return false if failed
if ($checkResponse->stateCode != StateCodes::SUCCESS)
return false;

// Obtain and store recipient status
$recipientStatus = $checkResponse->Messages[0]->jobState;

还有其他问题吗？

如果您还有任何问题，或者上述示例信息不足，您可以在每个服务的详细描述中获取有关API函数、对象和枚举的更详细信息（链接可在上文找到），您也可以通过帮助台或JivoSite联系我们。我们总是很高兴听到有关扩展或改进byFax API和整个产品的建议和想法。

目前，我们的开放API中仅提供byFax门户的基本功能，如果您需要扩展功能或添加根本性的新功能，我们始终乐意进行讨论。

如果您是Java、Ruby、Go或其他编程语言开发人员，并希望帮助改进byFax API SDK，我们很乐意欢迎您的帮助开发其他语言的SDK。