Download the PHP package grinchenkoedu/diia-php without Composer

Diia (Дія) API client for PHP

[!NOTE] This is a community library. It is not developed, endorsed or supported by Diia or the Ministry of Digital Transformation of Ukraine.

A client for the Diia acquirer API: branches, offers, and offer requests for Дія.Підпис (signing) and Дія.Шеринг (document sharing). PHP 7.4 or newer.

Installation

Recommended libraries

• ramsey/uuid - for request IDs (UUID4)
• matasarei/euspe ^2.0 - hashing documents, verifying signatures, opening sharing envelopes

Examples

The examples run in order: each one uses variables from the ones before it. tests/ReadmeExamplesTest.php runs every PHP block of this file, so they stay in step with the code.

Client initialization

Build the factory once, in a service provider or your container, and take the clients from it. Clients from one factory share one bearer token, kept in the PSR-16 cache you pass; it is refreshed before it expires, and once more if Diia rejects it with a 401.

Branches

A branch is the part of your organization users see in Diia.

Changing a branch's scopes: in our experience (observed in 2024, with 1.x) Diia did not apply new scopes to an existing branch, and the branch had to be deleted and created again. This is not confirmed by Diia's current documentation; check it on the partner portal before relying on either behaviour.

Errors

Failed calls throw DiiaApiException: an HTTP error, a response the client cannot read, or no response at all.

Дія.Підпис

Create the offer once and keep its ID. Then, for every document, hash it, send the hash, and give the user the deep link.

Дія.Шеринг

Callbacks

This library covers the calls you make to Diia. Diia's calls back to you — the signed hashes and the shared documents — are yours to receive. What they carry:

• an X-Document-Request-Trace-Id header that identifies the request. Validate it before you use it in a key or a file name;
• a body with encodeData:
  • signing: base64 of a JSON object whose signedItems list holds name (the file name you sent) and signature (base64);
  • sharing: an encrypted envelope, plus the documents themselves as multipart file uploads.

What the receiver must do:

• Verify every signature against the hash you stored for that file, with euspe. A callback is just an HTTP request; without the check, anyone who can reach the URL can "sign" your documents.
• Open the sharing envelope with your acquirer key (euspe's EnvelopeDeveloper).
• Never store an upload under the name the client sent. Generate the name, and keep the files in a directory your web server does not serve.
• Answer fast and process asynchronously. Store the request, return 200, and do the rest in a background job.

The check for a signing callback, in that background job:

Cleaning up

Upgrading from 1.x

2.0 replaces AcquirersClient with one client per API resource, built by ClientFactory. Replace the manual wiring (DependencyResolver, RequestJsonMapper, the five ResponseJsonMappers, HttpHeadersProvider) with the client initialization above, then rename the calls:

HTTP errors, transport errors and unreadable responses are now DiiaApiException instead of Guzzle exceptions or UnexpectedValueException. The DTOs, enums, endpoints and request bodies are unchanged. See CHANGELOG.md.

Tests and development