README

PHP SDK to consume the Tusdatos background check API, built on top of placetopay/tangram.

Requirements

PHP 8.2 or higher
ext-json and ext-mbstring

Installation

Add the PlacetoPay repository to your composer.json:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://repository.placetopay.com"
        }
    ]
}

Then install the package:

composer require tusdatos-dev/tusdatos-sdk

Configuration

use Placetopay\TusdatosSdk\Gateway;

$gateway = new Gateway([
    'url' => 'https://docs.tusdatos.co/api/',
    'username' => 'your-username',
    'password' => 'your-password',
]);

Setting	Type	Required	Default	Description
`url`	`string`	Yes		Base URL of the Tusdatos API.
`username`	`string`	Yes		Tusdatos username, sent with HTTP basic authentication.
`password`	`string`	Yes		Tusdatos password, sent with HTTP basic authentication.
`timeout`	`int\\|float`	No	`30`	Seconds to wait for Tusdatos before failing the request.
`simulatorMode`	`bool`	No	`false`	Uses the built-in simulator instead of the real API.
`providerName`	`string`	No	`Tusdatos`	Name used to identify the provider in the logs.
`client`	`GuzzleHttp\ClientInterface`	No	Guzzle client or simulator	Custom HTTP client.
`logger`	`array`	No		`via` (`Psr\Log\LoggerInterface`, required), `name`, `path`, `debug`.

Invalid settings throw PlacetoPay\Tangram\Exceptions\InvalidSettingException.

When a logger is configured, every request, response and error is logged and the Authorization header is always masked.

Operations

Method	Transaction	Tusdatos endpoint	Result getter
`launch()`	`LaunchTransaction`	`POST launch`	`getLaunchData()`
`checkStatus()`	`CheckStatusTransaction`	`GET results/{jobId}`	`getCheckStatusData()`
`formatJson()`	`FormatJsonTransaction`	`GET report_json/{id}`	`getFormatJsonData()`
`queryDocumentStatus()`	`StatusDocumentTransaction`	`POST launch/verify`	`getQueryDocumentData()`

The result getters return the decoded Tusdatos payload exactly as the provider sends it, or an empty array when the operation fails.

use Placetopay\TusdatosSdk\Entities\CheckStatusTransaction;
use Placetopay\TusdatosSdk\Entities\FormatJsonTransaction;
use Placetopay\TusdatosSdk\Entities\LaunchTransaction;

$launch = $gateway->launch(new LaunchTransaction([
    'type' => 'CC',
    'number' => '1032456789',
    'expeditionDate' => '01/12/2017',
]));

$status = $gateway->checkStatus(new CheckStatusTransaction($launch->getLaunchData()['jobid']));

if ($status->getCheckStatusData()['estado'] === 'finalizado') {
    $report = $gateway->formatJson(new FormatJsonTransaction($status->getCheckStatusData()['id']));
}

Handling failures

Provider failures never throw. They are reported through the transaction, so the integrating system can log them:

$report = $gateway->formatJson(new FormatJsonTransaction($id));

if (! $report->status()->isSuccessful()) {
    $logger->warning($report->status()->message(), [
        'reason' => $report->status()->reason(),
        'httpStatusCode' => $report->httpStatusCode(),
    ]);
}

Scenario	Reason code	HTTP status code	Message example
Successful response	`00`	`200`	`Background check report retrieved successfully`
Invalid credentials (`401`, `403`)	`XX` invalid setting	`401`	`Tusdatos responded with HTTP 401 Unauthorized: Invalid credentials`
Rejected request (other `4xx`)	`X3` invalid request	`422`	`Tusdatos responded with HTTP 422 Unprocessable Entity: field required (body.doc)`
Provider error (`5xx`)	`XR` invalid response	`502`	`Tusdatos responded with HTTP 502 Bad Gateway: 502 Bad Gateway`
Empty or non JSON object body	`XR` invalid response	`200`	`Tusdatos responded with HTTP 200 OK but the response body is not a JSON object (null given)`
Connection error or timeout	`XH` invalid host	`null`	`Unable to connect to Tusdatos: cURL error 28: Operation timed out after 30001 milliseconds`

Exceptions are only thrown for integration errors, and all of them extend Placetopay\TusdatosSdk\Exceptions\TusdatosSdkException:

Exception	When
`InvalidTransactionException`	A required field is missing, for example `The job id is required to execute the Tusdatos checkStatus operation`.
`ParserException`	The operation passed to `process()` is not supported.
`TusdatosSdkException`	Any unexpected error, wrapped with the operation name and the original exception as previous.

Simulator

With simulatorMode enabled the SDK answers locally. These values trigger specific scenarios:

Operation	Value	Scenario
Any	`username` = `ClientSimulator::REJECTED_USERNAME`	`401` invalid credentials
`launch`	`LaunchBehaviour::INVALID_DOCUMENT`	`422` validation error
`launch`	`LaunchBehaviour::SERVER_ERROR_DOCUMENT`	`500` HTML error page
`launch`	`LaunchBehaviour::CACHED_DOCUMENT`	Report id of a previous check
`checkStatus`	`CheckStatusBehaviour::NOT_FOUND_JOB`	`404` job not found
`checkStatus`	`CheckStatusBehaviour::PROCESSING_JOB`	Check still in progress
`formatJson`	`FormatJsonBehaviour::NOT_FOUND_REPORT`	`404` report not found
`formatJson`	`FormatJsonBehaviour::NULL_BODY_REPORT`	`200` with a `null` body
`formatJson`	`FormatJsonBehaviour::EMPTY_BODY_REPORT`	`200` with an empty body
`formatJson`	`FormatJsonBehaviour::MALFORMED_BODY_REPORT`	`200` with malformed JSON
`formatJson`	`FormatJsonBehaviour::INVALID_UTF8_REPORT`	`200` with invalid UTF-8 characters
`formatJson`	`FormatJsonBehaviour::SERVER_ERROR_REPORT`	`500` HTML error page
`queryDocumentStatus`	`QueryStatusDocumentBehaviour::INVALID_DOCUMENT`	`422` validation error

Development

composer test
composer phpstan
composer phpcs-validate

tusdatos-dev / tusdatos-sdk

Package info

Security

Statistics