README

Prerequisites

This project contains PHP bindings for Esempla GovTech API - a set of business-related tools. Full API documentation can be found here

Please note, that current state of these bindings can be behind of API state. In such case, please feel free to send us a corresponding issue

Requirements

PHP version >=5.4.0 (>=7.0.0)
yii2-httpclient version ^2.0
lcobucci/jwt version ^3.3

In further releases the http client can be replaced in order to remove dependency of yii2 ecosystem

Examples

First, you need to set a params item with EsemplaGovTechConfig instance:

<?php
use Esempla\GovTech\EsemplaGovTechConfig;

const CONFIG_CREDENTIALS = 'some_config_key';

$config = new EsemplaGovTechConfig();

$config->ClientID('your_client_id');
$config->ClientSecret('your_client_secret');
$config->Sandbox(true); // by default, `sandbox` is set to false, so all API calls lead to production API installation

return array(
    CONFIG_CREDENTIALS => $config
);

Authorization

<?php
use Esempla\GovTech\EsemplaGovTechSSO\EsemplaGovTechSSO;

$sso = new EsemplaGovTechSSO(CONFIG_CREDENTIALS);

if (!$sso->Login()) {
    // some failure login handling
}
else {
    $token = $sso->EsemplaGovTechProviderToken();

    // variable $token now contains the obtained authorization token
    // it is automatically cached in any `IEsemplaGovTechProvider`, but you would like to store it to use in other requests
}

Authorization token re-using

First, let's bring some boilerplate stuff:

<?php
use Esempla\GovTech\EsemplaGovTechSSO\EsemplaGovTechSSO;
use Esempla\GovTech\EsemplaGovTechInvoicing\EsemplaGovTechInvoicing;
use Esempla\GovTech\EsemplaGovTechInvoicing\EsemplaGovTechInvoicingDTO;

$authorization = '<stored-authorization-token-value>';

There are several options to re-using of authorization token. Let's understand them by following example:

<?php
/**
 * @var EsemplaGovTechInvoicing $invoicing
 */
$invoicing = EsemplaGovTechSSO::Authorize(CONFIG_CREDENTIALS, $authorization, new EsemplaGovTechInvoicing());

if ($invoicing == null) {
    // some failure token refreshing handling
    exit(); // or `return` if in function/method
}

<?php
$sso = new EsemplaGovTechSSO(CONFIG_CREDENTIALS);

$sso->EsemplaGovTechProviderToken($authorization);

if ($sso->AuthorizationNeed() && !$sso->Login()) {
    // some failure token refreshing handling
    exit(); // or `return` if in function/method
}

/**
 * @var EsemplaGovTechInvoicing $invoicing
 */
$invoicing = $sso->ContinueWith(new EsemplaGovTechInvoicing());

<?php
$invoicing = new EsemplaGovTechInvoicing(CONFIG_CREDENTIALS);

$invoicing->EsemplaGovTechProviderToken($authorization);

if ($invoicing->AuthorizationNeed()) {
    $sso = new EsemplaGovTechSSO(CONFIG_CREDENTIALS);

    if (!$sso->Login()) {
        // some failure token refreshing handling
        exit(); // or `return` if in function/method
    }

    $invoicing->EsemplaGovTechProviderToken($sso->EsemplaGovTechProviderToken());
}

Now, we can do some API calls, for example:

<?php
$dto = new EsemplaGovTechInvoicingDTO();
$dto->Sender('<IDNP>');
$dto->Service('<serviceID>'); // this should be equal to identifier of invoicing service, that is provided for your project
$dto->Amount(9.99); // optional (see corresponding API documentation) parameter

$invoice = $invoicing->InvoiceCreate($dto);

if ($invoice == null) {
    // some failure invoice creation handling
    exit(); // or `return` if in function/method
}

$invoice_id = $invoice->ID(); // returned invoice identifier
var_dump($invoice_id);

Testing

You can run tests (that are located in ./tests) for existing functionality by typing test's filename within php command. For example:

$ php ./tests/SSO/TestCheckToken.php

esempla / govtech-api

Maintainers

Details