nexusvc/ccg-sales-api

CCG SalesAPI的PHP库

维护者

详细信息

github.com/nexusvc/ccg-sales-api

源代码

问题

安装: 130

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 0

公开问题: 0

v1.0.81 2023-10-27 04:33 UTC

Requires

MIT 5a7b4ae811439b56bc232f097b0013f55e37450d

  • NexusVC, LLC <development.woop@nxvc.io>
  • John Paul Medina <jp.woop@nxvc.io>

libraryccgnexusvc

This package is auto-updated.

Last update: 2024-09-28 15:23:49 UTC

README

CCG Sales API是一个PHP库，用于与Cost Containment Group的开发和生产端点通信。CCG Sales API由NexusVC, LLC维护，是一个独立的社区贡献库。

文档

文档目前正在等待中。以下提供了简单的使用示例。

安装

您可以通过composer安装ccg-sales-api，或者通过下载源代码。

通过Composer

ccg-sales-api在Packagist上作为nexusvc/ccg-sales-api包提供

composer require nexusvc/ccg-sales-api

版本

ccg-sales-api对所有更改使用修改后的语义版本控制。有关详细信息，请参阅此文档。

快速入门

认证

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$username = 'FIRSTNAME.LASTNAME'; // Sales Agent Username from CCG
$password = 'XXXXXXXXXXXXXXXXXX'; // Sales Agent Password from CCG
$npn      = 'XXXXXXXX';           // Sales Agent NPN

// Authenticating and getting a token
$ccg = new CCG;

$ccg->auth()->login(
    $username,
    $password,
    $npn
);

return $ccg->auth();

列出产品类别

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

return $ccg->quote()->categories();

列出类别中的产品

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

// Set Product Params
$params = [
    'type' => $CategoryType, // Set the Type returned from categories
];

return $ccg->quote($params)->products();

列出产品验证类型

将列出接受的验证类型。此方法将用于未来的更改，包括根据order对象捕获修改后的语音脚本。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

return $ccg->quote()->verifications();

创建可支付令牌 - 支付方式

可支付是一种支付方式，可以是借记/信用卡和/或银行账户。库将根据在实例化新可支付时传递的参数确定类型。它还将对常见格式进行验证。一旦将可支付附加到Order对象上，它将自动加密，并始终以令牌化格式返回。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

// Credit or Debit
$payable = $ccg->payable([
    'account' => 'XXXXXXXXXXXXXXXX',
    'cvc'     => 'XXX',
    'expiration' => [
        'month' => 'XX',
        'year'  => 'XXXX'
    ],
]);

// BankAccount
$payable = $ccg->payable([
    'account' => 'XXXXXXXXXXXX',
    'routing' => 'XXXXXXXXXXXX'
]);

// Attach Payable to Order
$payable->addToOrder();

// Alternative: Attach Payable to Order
$ccg->order->addPayable($payable);

选择产品

可以将产品附加到订单对象，类似于附加可支付。您可以通过在“列出类别中的产品”部分中显示的方式传递参数来过滤产品，但您还可以使用集合过滤返回的项目，然后使用产品上的addToOrder()方法将产品推入订单对象。您还可以在订单对象上使用addProduct($product)方法直接推入产品。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

$params = [
    'state'        => 'FL', 
    'type'         => 'LimitedMedical',
    'coverageType' => 1
];

// Example filter by groupId
$product = $ccg->quote($params)->products()->filter(function($item) {
    return $item->groupId === 12362;
})->first();

// Attach Product to Order
$product->addToOrder();

// Alternative: Attach Product to Order
$ccg->order->addProduct($product);

创建申请人

在构建订单时，您必须附加1个或多个申请人。首先，创建一个新的申请人，并将其推送到订单中，类似于推送产品。您可以直接在申请人上使用addToOrder()方法，或者在订单对象上使用addApplicant($applicant)方法。您还可以使用申请人上的addContactable($contact)方法将可联系的对象附加到申请人。当前支持的联系方式是phone、email和address。

可联系对象将验证常见格式和USPS地址系统。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

// Create applicant
// This method always returns a new Applicant()
$applicant = $ccg->applicant([
    'firstName' => 'John', 
    'lastName'  => 'Doe',
    'dob'       => 'YYYY-MM-DD',
    'gender'    => 'Male',
    'relation'  => 'primary'
]);

// Phone
$phone = $ccg->phone('XXXXXXXXXX');
// Email
$email = $ccg->email('XXXXXXXXXX');

// Address
$addressParams = [
    'street1' => '1 GENERAL WAY',
    'street2' => 'APT 100',
    'city'    => 'Popular City',
    'state'   => 'FL',
    'zip'     => 'XXXXX'
];

$address = $ccg->address($addressParams);

// You may daisy chain addContactable method
$applicant->addContactable($phone)
          ->addContactable($email)
          ->addContactable($address);

// Add Applicant to Order
$applicant->addToOrder();

// Alternative: Add Applicant to Order
$ccg->order->addApplicant($applicant);

语音验证和附加音频

获取语音验证脚本，解析脚本内的变量，并更新脚本变量以生成完整的语音验证。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

// Add Product to Order
// Add Applicant(s) to Order
// Add Payable to Order

// Request Voice Verification Script
$verification = $ccg->quote()->verifications('voice')->fetch();

// Getting available script variables
$variables = $verification->getVariables();

// Update the value of each variable
// Doing so will parse and replace the voice
// script content w/ new values

// Setting Values
$verification->setVariables($variables);

// Request Formatted Script
$verification->format();

// Accessing Formatted Script
$verification->format()->script;

// Alternative: Accessing Formatted Script
// must have previously called ->format() method
$verification->script;

// Display Script to Agent

// Record audio & save


// You may pass a URL and/or audio file
// Formats accepted are: mp3, wav, url

// Local File Path
$recording = '/path/to/audio/file';

// Alternative: Remote File
$recording = 'https://www.dropbox.com/s/euygas65j1y7/john_doe_ver.mp3?dl=1';

// Adding recorded voice verification
$verification->addRecording($recording);

// Adding Verification to Order
// Recording must be attached
$verification->addToOrder();

// Alternative: Adding Verification to Order
// Recording must be attached
$ccg->order->addVerification($verification);

电子签名验证邀请（可选：$callbackUrl）

一旦您准备好请求电子签名邀请，可以使用验证类型esign和invite($callbackUrl)方法进行。$callbackUrl参数是可选的，但将允许CCG服务器在电子签名成功完成后立即将POST回引用的URL。这是完成推送通知的首选方法。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

// Add Product to Order
// Add Applicant(s) to Order
// Add Payable to Order

// Optional: Setting a $callbackUrl
// Passing a callbackUrl will fire automatically to the url upon
// successful esign by customer. This will eliminate the need for
// a status check and allow you to be notified immediately.
$callbackUrl = 'https://some.callback.url.com/';

// Request Esign
$esign = $ccg->quote()->verifications('esign');

// Sending Invitation
// Calling invite will push the verification to the order
$esign->invite($callbackUrl);

电子签名验证状态（可选：$callbackUrl）

您可以通过使用请求邀请时的 $callbackUrl 选项或使用 status() 方法来检查 esign 验证的状态。$callbackUrl 参数是可选的，但允许 CCG 服务器在 eSign 成功完成后立即将 POST 返回到引用的 URL。这是完成通知的首选方法。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

// Add Product to Order
// Add Applicant(s) to Order
// Add Payable to Order

// Optional: Setting a $callbackUrl
// Passing a callbackUrl will fire automatically to the url upon
// successful esign by customer. This will eliminate the need for
// a status check and allow you to be notified immediately.
$callbackUrl = 'https://some.callback.url.com/';

// Request Esign
$esign = $ccg->quote()->verifications('esign');

// Sending Invitation
// Calling invite will push the verification to the order
$esign->invite($callbackUrl);

// Wait for customer to complete esign if you are using the status method
// use a queue and/or manual checking if not using a $callbackUrl.

// Manually checking esign status
$esign->status();

收费订单 - 注册

一旦您的订单通过 applicants、products、payable 和 verification 对象构建完成，您可以通过在订单上调用 charge() 方法来完成注册。此方法将验证订单模式，将订单对象重构为 CCG 兼容的 POST 参数。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

// Add Product to Order
// Add Applicant(s) to Order
// Add Payable to Order
// Add Verification to Order

return $ccg->order->charge();

订单

主类中的订单对象可以通过 $ccg->order 访问。订单对象将包含 applicants、products、verifications、payable 对象。您可能需要像上面那样通过特定的方法（如 addToOrder()）引用订单对象。您还可以通过 toArray() 方法输出整个订单。下面是一个作为数组返回的订单示例。

// Include the Library
use Nexusvc\CcgSalesApi\CCG;

$ccg = new CCG;

// Authenticate
// See Authenticating

// Add Product to Order
// Add Applicant(s) to Order
// Add Payable to Order
// Add Verification to Order

return json_encode($ccg->order->toArray());

JSON 格式示例输出数组

{
  "applicants": [
    {
      "id": null,
      "firstName": "JOHN",
      "lastName": "DOE",
      "dob": "YYYY-MM-DD",
      "gender": "Male",
      "relation": "primary",
      "contactable": {
        "address": {
          "street1": "1 GENERAL WAY",
          "street2": 'APT 100',
          "city": "Popular City",
          "state": "FL",
          "zip": "33196",
          "type": "address",
          "address": "1 GENERAL WAY APT 100 Popular City, FL 33196"
        },
        "phone": {
          "type": "phone",
          "phone": "+1XXXXXXXXXX"
        },
        "email": {
          "type": "email",
          "email": "XXXX@XXXX.COM"
        }
      }
    }
  ],
  "payable": {
    "account": "eyJpdiI6IjBDd0dlUjVjamlPWXQ1TmhabzZ0QVE9PSIsInZhbHVlIjoiVmxJZ1A3clpLNTc0YVBaUzNoNFc5Z21OaVRnT1wvWFwvaEhXY1VlTkxXTjNQMHRYZ2NmOXNQZlZPZUxBOFZSYjhYY2lZSkRZUEUyamVMVGNzbGhTTmtXTUJxR252aDBMaWNGZGppcU54T1ZWY1hYMktiOUtBcnRZR0w4N1dMSVdxQ0FkazNwT003SkJ1U1p1dEwxXC81U0ZneGMzSkF2d2hjbFwvMHhiM0FNSDJaZmY4V0tkWXpiSlNyRlZRT3B5WU4zN0NRMm9ydEtVWGhTZzliYkdwQW9Ka2c9PSIsIm1hYyI6ImIyMGE3MzJmMGMwMjdmNjM4Y2U0YjYzOTBmNjZkMGFjYmE0NDAzMjc0Nzc0NTYxYTg1MjkyYWUyYmNjMjJjNzcifQ=="
  },
  "products": [
    {
      "groupId": 12362,
      "brandName": "Health Shield",
      "planId": 5,
      "planName": "Choice",
      "coverageTypeName": "Individual",
      "coverageType": 1,
      "retailAmount": 269.95,
      "carrierId": 293,
      "carrierName": "Crum & Forster",
      "quoteType": "LM",
      "brandLogo": "https://www.mymemberinfo.com/brand/12362/HS-UCA.gif",
      "agentId": XXXXXXXXX,
      "associationName": "Unified Caring Association",
      "enrollmentPlans": [
        {
          "planId": 1,
          "planName": "Lifetime Association Fee",
          "retailAmount": 99.95
        }
      ]
    },
    {
      "isOneTimeCharge": true,
      "planId": 1,
      "planName": "Lifetime Association Fee",
      "retailAmount": 99.95
    },
    {
      "planId": 727,
      "planName": "Legacy 200",
      "groupId": 12365,
      "brandName": "UCA Add-Ons",
      "retailAmount": 76.9,
      "coverageName": "Individual",
      "coverageType": 1,
      "addOnType": "Accidental Death"
    }
  ],
  "verification": {
    "type": "Esign",
    "esignCallbackUrl": "https://signal.leadtrust.io/callback/esignature",
    "token": "NVpxVDdeOTdlMjhwb2FidVRjVWEwMmova3pWNWFqaGk=",
    "otp": "XXXXXX",
    "responseType": 0,
    "responseMessage": null,
    "esignIPAddress": null,
    "esignRecipient": "+1XXXXXXXXXX",
    "esignUserDevice": null,
    "verificationStatus": "Pending",
    "eSignAcceptedDate": "0001-01-01T00:00:00-05:00"
  },
  "total": 446.8,
  "deposit": 99.95,
  "recurring": 346.85
}

模式验证与格式化

库中内置了模式验证器和模式格式化器。这通常在幕后处理，但必要时可以访问。您会使用这些来验证所需的结构（s）和/或以 current 或 deprecated 格式输出 order 以供 CCG 端点使用。目前的一个实际例子是在向 eSign 邀请发送 POST 时选择 version1 模式。它将重新创建 order 对象。

// Pass the $ccg->order
$schema = new \Nexusvc\CcgSalesApi\Schema\Schema($ccg->order);

return $schema->load('version-one')->format();

模式：版本 1

您会注意到一些 key 名称从上面的 order 输出中改变，并且由于目前 CCG 不接受加密令牌，可支付令牌现在被解密。这是目前接受的 order 模式。

{
  "firstName": "JOHN",
  "lastName": "DOE",
  "dateOfBirth": "YYYY-MM-DDT00:00:00-04:00",
  "gender": "M",
  "address1": "1 GENERAL WAY",
  "address2": "APT 100",
  "city": "Popular City",
  "state": "FL",
  "zip": "33196",
  "telephone": "+1XXXXXXXXXX",
  "email": "XXXX@XXXX.COM",
  "esignRecipient": "+1XXXXXXXXXX",
  "caseID": 0,
  "coverageType": 1,
  "groupID": 12362,
  "agentID": XXXXXXXXX,
  "paymentInfo": {
    "payType": 0,
    "ccExpMonth": "XX",
    "ccExpYear": "XXXX",
    "ccNumber": "XXXXXXXXXXXXXXXX",
    "cvv": "XXX",
    "accountNumber": "",
    "routingNumber": ""
  },
  "plans": [
    {
      "groupID": 12362,
      "planID": 5,
      "amount": 269.95,
      "planType": 0
    },
    {
      "planID": 1,
      "amount": 99.95,
      "isOneTimeCharge": true,
      "planType": 2
    },
    {
      "groupID": 12365,
      "planID": 727,
      "amount": 76.9,
      "planType": 1
    }
  ],
  "effectiveDate": "YYYY-MM-DDT00:00:00-05:00"
}