README

This module contains logic to connect Omniva OMX API from Magento2.

Reference: https://www.omniva.lv/wp-content/uploads/sites/6/2024/10/OMX-API-Manual-for-Customers_nov.pdf

Installation

Put content of the repository to app/code/Halex/OMX folder

Main Features

Sandbox/Live API configuration
Create B2C shipments
Get Shipping Label
Event-Id based tracking events sync using CRON
receiverAddressee/senderAddressee, receiverAddressee/address senderAddressee/address Interfaces and data models
Magento event on tracking events success sync

Examples

Create B2C Shipment

Endpoint: /api/v01/omx/shipments/business-to-client

<?php

namespace Vendor\Package\Model;

use Halex\OMX\Api\Data\OmxShippingInterfaceFactory;
use Halex\OMX\Model\Client;

class HalexOmxCreateShipmentService {
    private Client $omxClient;
    private OmxShippingInterfaceFactory $omxShippingFactory;
    
    public function __construct(
        Client $omxClient,
        OmxShippingInterfaceFactory $omxShippingFactory
    ) {
        $this->omxClient = $omxClient;
        $this->omxShippingFactory = $omxShippingFactory;
    }
    
    public function createShipment() {
        $senderShipping = $this->omxShippingFactory->create();
        $senderShipping->setContactEmail('sender_email@gmail.com')
            ->setContactMobile('+37122332233')
            ->setAltName('Sender Company Name')
            ->setIsUseSenderAddressForReturn(true)
            ->setPersonName('Sender Name');

        $senderAddress = $senderShipping->getAddress();

        $senderAddress->setCountry('LV')
            ->setDeliveryPoint('Riga')
            ->setPostalCode('1069')
            ->setStreet('Brivibas Iela')
            ->setHouseNumber('230a');

        $senderShipping->setAddress($senderAddress);

        $receiverShipping = $this->omxShippingFactory->create();
        $receiverShipping->setContactEmail('receiver_email@gmail.com')
             ->setContactPhone('+37122332233')
             ->setContactMobile('+37122332233')
             ->setPersonName('Reciever Name');

        $receiverAddress = $receiverShipping->getAddress();
        $receiverAddress->setCountry($orderShippingAddress->getCountryId());

        // Omniva Terminal
        $receiverAddress->setOffloadPostalCode('9061');

        $receiverShipping->setAddress($receiverAddress);

        $response = $this->omxClient->createShipmentB2C(
            $senderShipping,
            $receiverShipping,
            $order->getIncrementId(),
            'Order #123456789'
        );
        
        //Handle response from OMX
    }
}

Response:

[
    "resultCode"=> "OK",
    "provider"=> "EEPOST",
    "savedShipments" => [
        "barcode" => "CC404769673EE",
        "clientItemId" => "12345"
    ],
    "failedShipments" => []
]

Get Shipping Label

Endpoint: /api/v01/omx/shipments/package-labels

$shippingLabelResponse = $this->omxClient->getShippingLabels(['CC404769673EE']);

Response (Base64 PDF):

[
    "failedAddressCards" => [],
    "successAddressCards" => [
        "barcode": "CC404769673EE",
        "fileData": "JVBERi0x..."
    ]
]

Tracking Events

Table: omx_tracking_events
Collection Model: \Halex\OMX\Model\ResourceModel\OmxTrackingEvent\Collection
Sync event: omx_tracking_events_sync_done (Data: tracking_events - array of synced entities)

Cron configured to run every 5 minutes and sync tracking events from /api/v01/omx/shipments?size=100&fromTrackEventId=0 endpoint. It's automatically set last fromTrackEventId based on the last entity in database

Other endpoints will be implemented soon, keep posted :)

halexm2 / omniva-omx

Maintainers

Details