README

Laravel package for Asan İmza — Azerbaijan's mobile authentication and digital signing system. Communicates with the Asan İmza proxy server via JSON-RPC 2.0 protocol.

Requirements

• PHP ^8.3
• Laravel ^12.0
• Asan İmza proxy server running (default: http://localhost:8090)

Installation

composer require sarkhanrasimoghlu/laravel-asanimza

Publish the configuration file:

php artisan vendor:publish --tag=asanimza-config

Configuration

Add the following to your .env file:

ASANIMZA_BASE_URL=http://localhost:8090
ASANIMZA_SERVICE_NAME=AsanDoc
ASANIMZA_LANGUAGE=aze
ASANIMZA_TIMEOUT=30
ASANIMZA_LOG_ENABLED=true
ASANIMZA_LOG_CHANNEL=stack

Usage

Inject AsanImzaInterface via constructor or method injection:

use Sarkhanrasimoghlu\AsanImza\Contracts\AsanImzaInterface;

Authentication

Step 1: Start authentication

public function login(AsanImzaInterface $asanImza)
{
    $result = $asanImza->authenticate('+994501234567', 'userId123');

    // Show verification code to the user
    // $result->verificationCode — user must confirm this on their phone
    // $result->transactionId — needed for status check
    // $result->certificate — needed for status check
    // $result->challenge — needed for status check

    return response()->json([
        'transactionId' => $result->transactionId,
        'verificationCode' => $result->verificationCode,
        'certificate' => $result->certificate,
        'challenge' => $result->challenge,
    ]);
}

Step 2: Check authentication status (polling)

public function checkAuth(AsanImzaInterface $asanImza, Request $request)
{
    $status = $asanImza->getAuthStatus(
        transactionId: $request->input('transactionId'),
        certificate: $request->input('certificate'),
        challenge: $request->input('challenge'),
    );

    if ($status->status === \Sarkhanrasimoghlu\AsanImza\Enums\AuthStatus::USER_AUTHENTICATED) {
        // Authentication successful
        // $status->signature contains the base64-encoded signature
    }

    return response()->json([
        'status' => $status->status->value,
    ]);
}

Get Certificate Data

Extract user information from a certificate:

$certData = $asanImza->getCertificateData($certificate);

$certData->firstName;       // "John"
$certData->surname;         // "Doe"
$certData->personalCode;    // "1234567"
$certData->organizationName; // nullable
$certData->certType;        // CertType enum (AUTHENTICATION, CITIZEN_SIGNING, etc.)

Digital Signing

Step 1: Get signing certificates

$certs = $asanImza->getSigningCertificates('+994501234567', 'userId123');
// Returns: ['certId1' => 'base64cert1', 'certId2' => 'base64cert2']

Step 2: Sign files

use Sarkhanrasimoghlu\AsanImza\DTOs\DataFile;

$dataFiles = [
    new DataFile(
        content: base64_encode(file_get_contents('/path/to/document.pdf')),
        fileName: 'document.pdf',
        mimeType: 'application/pdf',
    ),
];

$result = $asanImza->signFiles(
    dataFiles: $dataFiles,
    phoneNumber: '+994501234567',
    userId: 'userId123',
    certIdentifier: 'certId1',
    certificate: $certs['certId1'],
);

// $result->transactionId
// $result->verificationCode — show to user
// $result->hash — needed for status check
// $result->container — needed for status check

Step 3: Check signing status (polling)

$status = $asanImza->getSignFileStatus(
    transactionId: $result->transactionId,
    hash: $result->hash,
    container: $result->container,
    certificate: $certs['certId1'],
);

if ($status->status === \Sarkhanrasimoghlu\AsanImza\Enums\SignStatus::SIGNATURE_CREATED) {
    // $status->container — signed container (base64)
    $signedContent = base64_decode($status->container);
}

Error Handling

All exceptions extend AsanImzaException:

use Sarkhanrasimoghlu\AsanImza\Exceptions\AsanImzaException;
use Sarkhanrasimoghlu\AsanImza\Exceptions\JsonRpcException;

try {
    $result = $asanImza->authenticate('+994501234567', 'userId123');
} catch (JsonRpcException $e) {
    // JSON-RPC error from Asan İmza proxy
    $e->getErrorCode();    // e.g., 2004
    $e->getErrorMessage(); // e.g., "Unknown phone number"
    $e->getContext();      // ['error_code' => 2004, 'error_message' => '...']
} catch (AsanImzaException $e) {
    // HTTP or parsing error
    $e->getMessage();
    $e->getContext();
}

Common Error Codes

Enums

AuthStatus

SignStatus

Same values as AuthStatus, except USER_AUTHENTICATED is replaced by SIGNATURE_CREATED.

CertType

License

MIT