PHP library for integration with the New Mail API
Hello friends.
I want to share a PHP library (SDK) for integration with API 2 New Mail (NP). But first, a few words about the New Mail.
New Mail is a leader in express delivery and transportation of goods throughout Ukraine. New Mail has many services, which makes it a leader in the Ukrainian transportation market. Warehouses are in all cities of Ukraine, very fast courier service. The main services that the company nada: delivery and return of goods in retail chains; delivery of palletized cargo; return shipping; cash on delivery; car call; storage of cargo; packing of cargo, delivery of cargo in the city and so on. To simplify the creation of TTN, you can use the company's API, which will make it possible to optimize the creation of TTN.
SDK features :
Before you start working with the SDK, you need to get the API key. We follow the link https://my.novaposhta.ua , log in to your personal account. Further, rm Nalashtuvannya -> API 2.0 . Press the button New key , copy the created key.
Possible data transfer formats (format specified in the setFormat method):
By default, the format will be set JSONRPC2.
The documentation of the NP work is divided into models:
Working with model methods: save, update, delete. Fill the model with the desired values ​​and call the desired method. Example:
Work with static methods. In methods to transfer object MethodParameters :
Or you can use the MethodParameters classes that inherit from the MethodParameters class. Classes have parameter setters that can be passed to a static model method. Names of classes with parameters are added from two parts, with the name of the model ( ApiModels ) and the name of the static method of the model. Usage example:
I hope the SDK will help you to integrate with the New Mail API.
Good luck!
I want to share a PHP library (SDK) for integration with API 2 New Mail (NP). But first, a few words about the New Mail.
New Mail is a leader in express delivery and transportation of goods throughout Ukraine. New Mail has many services, which makes it a leader in the Ukrainian transportation market. Warehouses are in all cities of Ukraine, very fast courier service. The main services that the company nada: delivery and return of goods in retail chains; delivery of palletized cargo; return shipping; cash on delivery; car call; storage of cargo; packing of cargo, delivery of cargo in the city and so on. To simplify the creation of TTN, you can use the company's API, which will make it possible to optimize the creation of TTN.
SDK features :
- Work with addresses
- Work with reference books
- Work with counterparties
- Methods for obtaining printed forms of documents
- Working with Express Consignment Registers
- Work with express invoices:
- create express invoices
- edit the data in the created express waybills (before sending the item)
- delete / cancel created express waybills (before sending the parcel)
- upload document lists using filters
- track shipment statuses
Connect Library (SDK)
Method 1 (composer)
')
Create the file composer.json in the root of your project:
Install composer:
Connect autoloader composer:
Method 2 (git)
Clone repository:
Connect autoloader SDK:
')
Create the file composer.json in the root of your project:
{ "require": { "serj1chen/nova-poshta-sdk-php": "2.0.*" } } Install composer:
$ curl -sS https://getcomposer.org/installer | php $ php composer.phar install Connect autoloader composer:
include_once "vendor/autoload.php"; Method 2 (git)
Clone repository:
git clone git://github.com/serj1chen/nova-poshta-sdk-php Connect autoloader SDK:
include_once "nova-poshta-sdk-php/lib/NovaPoshta/bootstrap.php"; Before you start working with the SDK, you need to get the API key. We follow the link https://my.novaposhta.ua , log in to your personal account. Further, rm Nalashtuvannya -> API 2.0 . Press the button New key , copy the created key.
SDK setup
use NovaPoshta\Config; Config::setApiKey('< >'); Config::setFormat(Config::FORMAT_JSONRPC2); Config::setLanguage(Config::LANGUAGE_UA); Possible data transfer formats (format specified in the setFormat method):
- FORMAT_JSON
- FORMAT_JSONRPC2 (recommended)
- FORMAT_XML
By default, the format will be set JSONRPC2.
Work with SDK models
The documentation of the NP work is divided into models:
- Address: model for working with addresses. Examples of working with a model
- Common: model for working with reference books. Examples of working with a model
- ContactPerson: a model for creating a contact person. Examples of working with a model
- Counterparty: model for working with counterparty data. Examples of working with a model
- InternetDocument: a model for posting. Examples of working with a model
- ScanSheet: model for working with register of reception-transfer of shipments. Examples of working with a model
Working with model methods
Working with model methods: save, update, delete. Fill the model with the desired values ​​and call the desired method. Example:
use NovaPoshta\ApiModels\Counterparty; $counterparty = new Counterparty(); $counterparty->setCounterpartyProperty('Recipient'); $counterparty->setCityRef('db5c88d0-391c-11dd-90d9-001a92567626'); $counterparty->setCounterpartyType('PrivatePerson'); $counterparty->setFirstName(''); $counterparty->setLastName(''); $counterparty->setMiddleName(''); $counterparty->setPhone('+380661122333'); $counterparty->setEmail('test@i.ua'); $result = $counterparty->save(); Work with static methods. In methods to transfer object MethodParameters :
use NovaPoshta\ApiModels\Counterparty; use NovaPoshta\MethodParameters\MethodParameters; $data = new MethodParameters(); $data->CounterpartyProperty = 'Recipient'; $data->Page = 1; $data->CityRef = '8d5a980d-391c-11dd-90d9-001a92567626'; $data->FindByString = ''; $result = Counterparty::getCounterparties($data); Or you can use the MethodParameters classes that inherit from the MethodParameters class. Classes have parameter setters that can be passed to a static model method. Names of classes with parameters are added from two parts, with the name of the model ( ApiModels ) and the name of the static method of the model. Usage example:
use NovaPoshta\ApiModels\Counterparty; use NovaPoshta\MethodParameters\MethodParameters; use NovaPoshta\MethodParameters\Counterparty_getCounterparties; $data = new Counterparty_getCounterparties(); $data->setCounterpartyProperty('Recipient'); $data->setPage(1); $data->setCityRef('8d5a980d-391c-11dd-90d9-001a92567626'); $data->setFindByString(''); $result = Counterparty::getCounterparties($data); Request logging
If you need to log data send / receive requests. You need to create a class that inherits from Logger.php and pass an instance of this class to the setClassLogger method of the Config.php file.
The setOriginalData Method: New Mail API request / response. Parameters: toData - request (type: string ); fromData - the answer (type: string ).
SetData Method: New Mail API's request / response for the SDK format. Parameters: toData - request (object: DataContainer ); fromData - the answer (object: DataContainerResponse ).
use NovaPoshta\Logger; use NovaPoshta\Config; class Logger_example extends Logger { public static function setOriginalData($toData, $fromData) { // ... } public static function setData($toData, $fromData) { // ... } } Config::setClassLogger($ new Logger_example()); The setOriginalData Method: New Mail API request / response. Parameters: toData - request (type: string ); fromData - the answer (type: string ).
SetData Method: New Mail API's request / response for the SDK format. Parameters: toData - request (object: DataContainer ); fromData - the answer (object: DataContainerResponse ).
Creations of the express consignment note (TTN)
Choose the sender's city:
Choose the city of the recipient:
Select the type of counterparty:
Create the recipient’s business partner:
If there is no sender’s counterparty in the city of Poltava, we create the sender’s counterparty there. Counterparty will be created in a few minutes:
If you have a counterparty sender, then we receive it as the recipient’s counterparty, only here: setCounterpartyProperty is passed to \ NovaPoshta \ ApiModels \ Counterparty :: SENDER . The cloneLoyaltyCounterpartySender method can be used only if you are a customer of loyalty, if you are a corporate customer, then you should already have a counterparty sender in the desired city.
Now we’ll get the sender’s counterparty:
We will get contact persons for contractors:
For the sender’s counterparty, we will receive the dispatch warehouse
Create an address for the recipient:
Now we get the type of service:
Choosing a payer:
Form of payment:
Type of Cargo:
We have selected all the data that we need to create EH. Create an EN:
Get a link to print EN:
After printing EN, glue EN on the box and ship the goods))
$data = new \NovaPoshta\MethodParameters\Address_getCities(); $data->setFindByString(''); $result = \NovaPoshta\ApiModels\Address::getCities($data); $citySender = $result->data[0]->Ref; Choose the city of the recipient:
$result = \NovaPoshta\ApiModels\Address::getCities(); // $cityRecipient = $result->data[60]->Ref; Select the type of counterparty:
$result = \NovaPoshta\ApiModels\Common::getTypesOfCounterparties(); $counterpartyType = $result->data[1]->Ref; // PrivatePerson Create the recipient’s business partner:
$counterparty = new \NovaPoshta\ApiModels\Counterparty(); $counterparty->setCounterpartyProperty(\NovaPoshta\ApiModels\Counterparty::RECIPIENT); $counterparty->setCityRef($cityRecipient); $counterparty->setCounterpartyType($counterpartyType); $counterparty->setFirstName(''); $counterparty->setLastName(''); $counterparty->setMiddleName(''); $counterparty->setPhone('+380661122333'); $counterparty->setEmail('test@i.ua'); $result = $counterparty->save(); $counterpartyRecipient = $result->data[0]->Ref; If there is no sender’s counterparty in the city of Poltava, we create the sender’s counterparty there. Counterparty will be created in a few minutes:
$data = new \NovaPoshta\MethodParameters\Counterparty_cloneLoyaltyCounterpartySender(); $data->setCityRef($citySender); $result = \NovaPoshta\ApiModels\Counterparty::cloneLoyaltyCounterpartySender($data); If you have a counterparty sender, then we receive it as the recipient’s counterparty, only here: setCounterpartyProperty is passed to \ NovaPoshta \ ApiModels \ Counterparty :: SENDER . The cloneLoyaltyCounterpartySender method can be used only if you are a customer of loyalty, if you are a corporate customer, then you should already have a counterparty sender in the desired city.
Now we’ll get the sender’s counterparty:
$data = new \NovaPoshta\MethodParameters\Counterparty_getCounterparties(); $data->setCityRef($citySender); $data->setCounterpartyProperty(\NovaPoshta\ApiModels\Counterparty::SENDER); $result = \NovaPoshta\ApiModels\Counterparty::getCounterparties($data); $counterpartySender = $result->data[0]->Ref; We will get contact persons for contractors:
$data = new \NovaPoshta\MethodParameters\Counterparty_getCounterpartyContactPersons(); $data->setRef($counterpartySender); $result = \NovaPoshta\ApiModels\Counterparty::getCounterpartyContactPersons($data); $contactPersonSender = $result->data[0]->Ref; $data = new \NovaPoshta\MethodParameters\Counterparty_getCounterpartyContactPersons(); $data->setRef($counterpartyRecipient); $result = \NovaPoshta\ApiModels\Counterparty::getCounterpartyContactPersons($data); $contactPersonRecipient = $result->data[0]->Ref; For the sender’s counterparty, we will receive the dispatch warehouse
$data = new \NovaPoshta\MethodParameters\Address_getWarehouses(); $data->setCityRef($citySender); $result = \NovaPoshta\ApiModels\Address::getWarehouses($data); $addressSender = $result->data[5]->Ref; Create an address for the recipient:
$address = new \NovaPoshta\ApiModels\Address(); $address->setCounterpartyRef($counterpartyRecipient); $address->setBuildingNumber('2/2'); $address->setFlat('22'); $address->setNote(' '); $address->setStreetRef('c55c9056-4148-11dd-9198-001d60451983'); $result = $address->save(); $addressRecipient = $result->data[0]->Ref; Now we get the type of service:
$result = \NovaPoshta\ApiModels\Common::getServiceTypes(); $serviceType = $result->data[3]->Ref; // : WarehouseDoors Choosing a payer:
$result = \NovaPoshta\ApiModels\Common::getTypesOfPayers(); $payerType = $result->data[1]->Ref; // : Recipient Form of payment:
$result = \NovaPoshta\ApiModels\Common::getPaymentForms(); $paymentMethod = $result->data[1]->Ref; // : Cash Type of Cargo:
$result = \NovaPoshta\ApiModels\Common::getCargoTypes(); $cargoType = $result->data[0]->Ref; // : Cargo We have selected all the data that we need to create EH. Create an EN:
// $sender = new \NovaPoshta\Models\CounterpartyContact(); $sender->setCity($citySender) ->setRef($counterpartySender) ->setAddress($addressSender) ->setContact($contactPersonSender) ->setPhone('+380660000000'); // $recipient = new \NovaPoshta\Models\CounterpartyContact(); $recipient->setCity($cityRecipient) ->setRef($counterpartyRecipient) ->setAddress($addressRecipient) ->setContact($contactPersonRecipient) ->setPhone('+380660000000'); // $result = \NovaPoshta\ApiModels\Common::getTypesOfPayersForRedelivery(); $redeliveryPayer = $result->data[1]->Ref; // $result = \NovaPoshta\ApiModels\Common::getBackwardDeliveryCargoTypes(); $redeliveryCargoType = $result->data[1]->Ref; // $backwardDeliveryData = new \NovaPoshta\Models\BackwardDeliveryData(); $backwardDeliveryData->setPayerType($redeliveryPayer); $backwardDeliveryData->setCargoType($redeliveryCargoType); $backwardDeliveryData->setRedeliveryString(452); $internetDocument = new \NovaPoshta\ApiModels\InternetDocument(); $internetDocument->setSender($sender) ->setRecipient($recipient) ->setServiceType($serviceType) ->setPayerType($payerType) ->setPaymentMethod($paymentMethod) ->setCargoType($cargoType) ->setWeight(1) ->setSeatsAmount(1) ->setCost(452) ->setDescription('') ->setDateTime('10.09.2015') ->addBackwardDeliveryData($backwardDeliveryData); $result = $internetDocument->save(); $refInternetDocument = $result->data[0]->Ref; Get a link to print EN:
$data = new \NovaPoshta\MethodParameters\InternetDocument_printDocument(); $data->addDocumentRef($refInternetDocument); $data->setCopies(\NovaPoshta\ApiModels\InternetDocument::PRINT_COPIES_FOURFOLD); $link = \NovaPoshta\ApiModels\InternetDocument::printDocument($data); After printing EN, glue EN on the box and ship the goods))
I hope the SDK will help you to integrate with the New Mail API.
Good luck!
Source: https://habr.com/ru/post/264209/
All Articles