it-delmax/laravel-eotpremnica

Laravel 12 SDK for Serbian eOtpremnica (electronic dispatch note) API by Ministry of Finance

v1.0.0 2025-12-18 08:04 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.8
• illuminate/contracts: ^11.0|^12.0
• illuminate/http: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• laravel/framework: ^11.0|^12.0
• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0
• phpstan/phpstan: ^2.0

MIT

• Nikola Marčić

• api
• laravel
• dispatch
• serbia
• mfin
• eotpremnica

README

Laravel 12 SDK za eOtpremnica API Ministarstva Finansija Republike Srbije.

Instalacija

composer require it-delmax/laravel-eotpremnica

Konfiguracija

Publikuj config fajl:

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

Dodaj u .env:

EOTPREMNICA_API_KEY=your-api-key
EOTPREMNICA_ENV=demo  # ili 'production'

Korišćenje

Facade

use ItDelmax\EOtpremnica\Facades\EOtpremnica;

// Pregled aktivnih kompanija
$companies = EOtpremnica::companies()->getActiveCompanies();

// Provera da li je kompanija registrovana
$isRegistered = EOtpremnica::companies()->isRegistered('123456789');

// Pronađi kompaniju po PIB-u
$company = EOtpremnica::companies()->findByVat('123456789');

Dependency Injection

use ItDelmax\EOtpremnica\EOtpremnica;

class DespatchAdviceController
{
    public function __construct(
        protected EOtpremnica $eOtpremnica,
    ) {}

    public function show(string $id)
    {
        $despatchAdvice = $this->eOtpremnica
            ->asSupplier()
            ->getDespatchAdvice($id);

        return $despatchAdvice->toArray();
    }
}

Direktna instanca

use ItDelmax\EOtpremnica\EOtpremnica;

$client = new EOtpremnica(
    apiKey: 'your-api-key',
    environment: 'demo',
);

API Grupe

SDK pokriva sve API endpointe:

Companies (Kompanije)

// Lista svih aktivnih kompanija
$companies = EOtpremnica::companies()->getActiveCompanies();

// Pronađi po PIB-u
$company = EOtpremnica::companies()->findByVat('123456789');

// Pronađi po matičnom broju
$company = EOtpremnica::companies()->findByRegistrationCode('12345678');

// Proveri registraciju
$isRegistered = EOtpremnica::companies()->isRegistered('123456789');

Supplier Documents (Dokumenti dobavljača)

Koristi kada si pošiljalac robe:

// Preuzmi otpremnicu
$despatchAdvice = EOtpremnica::asSupplier()->getDespatchAdvice($uuid);

// Preuzmi prijemnicu
$receiptAdvice = EOtpremnica::asSupplier()->getReceiptAdvice($uuid);

// Download XML
$xml = EOtpremnica::asSupplier()->downloadDespatchAdviceXml($uuid);

// Download PDF
$pdf = EOtpremnica::asSupplier()->downloadDespatchAdvicePdf($uuid);

// Download potpisa
$signature = EOtpremnica::asSupplier()->downloadDespatchAdviceSignature($uuid);

// Praćenje promena
$changes = EOtpremnica::asSupplier()->getChanges(new DateTime('2024-01-15'));

// Sve promene sa automatskom paginacijom
$allChanges = EOtpremnica::asSupplier()->getAllChanges(new DateTime('2024-01-15'));

Customer Documents (Dokumenti kupca)

Koristi kada si primalac robe:

// Preuzmi otpremnicu
$despatchAdvice = EOtpremnica::asCustomer()->getDespatchAdvice($uuid);

// Preuzmi prijemnicu
$receiptAdvice = EOtpremnica::asCustomer()->getReceiptAdvice($uuid);

// Download fajlova
$xml = EOtpremnica::asCustomer()->downloadDespatchAdviceXml($uuid);
$pdf = EOtpremnica::asCustomer()->downloadReceiptAdvicePdf($uuid);
$signature = EOtpremnica::asCustomer()->downloadReceiptAdviceSignature($uuid);

Carrier Documents (Dokumenti prevoznika)

Koristi kada si prevoznik robe:

$despatchAdvice = EOtpremnica::asCarrier()->getDespatchAdvice($uuid);
$xml = EOtpremnica::asCarrier()->downloadDespatchAdviceXml($uuid);
$changes = EOtpremnica::asCarrier()->getChanges();

Document Requests (Slanje dokumenata)

use Ramsey\Uuid\Uuid;

// Pošalji XML dokument
$requestId = Uuid::uuid4()->toString();

// Iz stringa
EOtpremnica::requests()->submitXml($requestId, $xmlContent);

// Iz fajla
EOtpremnica::requests()->submitFromPath($requestId, '/path/to/document.xml');

// Iz UploadedFile (npr. iz forme)
EOtpremnica::requests()->submit($requestId, $request->file('document'));

// Praćenje statusa
$changes = EOtpremnica::requests()->getChanges(now());

XML Validator

// Validiraj XML
$results = EOtpremnica::validator()->validateXml($xmlContent);

foreach ($results as $result) {
    if (!$result->isValid) {
        foreach ($result->getErrors() as $error) {
            echo "{$error->code}: {$error->description}\n";
        }
    }
}

// Brza provera validnosti
if (EOtpremnica::validator()->isValid($xmlContent)) {
    // XML je validan
}

// Dohvati sve moguće validacione poruke
$messages = EOtpremnica::validator()->getDespatchAdviceValidationMessages();

Webhook Notifications

// Pretplati se na webhook notifikacije
$subscription = EOtpremnica::webhook()->subscribe();

echo "Subscription key: {$subscription->subscriptionKey}";
echo "Valid until: {$subscription->validToUtc->format('Y-m-d')}";

Data Transfer Objects (DTO)

Sve metode vraćaju tipizirane DTO objekte:

$despatchAdvice = EOtpremnica::asSupplier()->getDespatchAdvice($uuid);

$despatchAdvice->id;                        // string (UUID)
$despatchAdvice->createdDateUtc;            // DateTimeImmutable
$despatchAdvice->status;                    // SupplierDespatchAdviceStatus enum
$despatchAdvice->status->label();           // "Poslato", "Otkazano", etc.
$despatchAdvice->statusDateUtc;             // DateTimeImmutable
$despatchAdvice->cancelReason;              // ?string
$despatchAdvice->transportationStartDate;  // ?DateTimeImmutable
$despatchAdvice->deliveryConfirmationDateUtc; // ?DateTimeImmutable

// Helper metode
$despatchAdvice->isCancelled();  // bool
$despatchAdvice->isDelivered();  // bool
$despatchAdvice->toArray();      // array

Enums

use ItDelmax\EOtpremnica\Enums\SupplierDespatchAdviceStatus;
use ItDelmax\EOtpremnica\Enums\DocumentType;

// Status enum
$status = SupplierDespatchAdviceStatus::Sent;
$status->value;    // 'Sent'
$status->label();  // 'Poslato'
$status->isFinal(); // false

// Document type enum
$type = DocumentType::DespatchAdvice;
$type->label(); // 'Otpremnica'

Error Handling

use ItDelmax\EOtpremnica\Exceptions\EOtpremnicaException;
use ItDelmax\EOtpremnica\Exceptions\AuthenticationException;
use ItDelmax\EOtpremnica\Exceptions\NotFoundException;

try {
    $despatchAdvice = EOtpremnica::asSupplier()->getDespatchAdvice($uuid);
} catch (AuthenticationException $e) {
    // Pogrešan API ključ
} catch (NotFoundException $e) {
    // Dokument nije pronađen
} catch (EOtpremnicaException $e) {
    // Ostale greške
    $problemDetails = $e->getProblemDetails();
    $statusCode = $e->getStatusCode();
}

Logging

Omogući logovanje API poziva u .env:

EOTPREMNICA_LOG_ENABLED=true
EOTPREMNICA_LOG_CHANNEL=stack

Testiranje

composer test

Licenca

MIT License

Autor

Delmax d.o.o.