Nova Poshta Golang API client

A simple API client for Nova Poshta written in Go.

API documentation

https://developers.novaposhta.ua/documentation

Go Versions Supported

We currently support Go versions 1.20 and newer.

Installation

go get github.com/platx/go-nova-poshta

Usage

Initialize client

You should get your_api_token in the Nova Poshta security settings page

Basic config

package main

import (
    "net/http"

    "github.com/platx/go-nova-poshta"
    "github.com/platx/go-nova-poshta/adapter"
)

func main() {
    client := go_nova_poshta.NewClient(adapter.NewConfig("your_api_token"))
}

Custom config

You are able to customize optional settings, like this:

package main

import (
    "log"
    "net/http"

    "github.com/platx/go-nova-poshta"
    "github.com/platx/go-nova-poshta/adapter"
)

func main() {
    client := go_nova_poshta.NewClient(adapter.NewConfig(
        "your_api_token",                           // required
        adapter.WithHTTPClient(http.DefaultClient), // custom http client to send requests
        adapter.WithFormat("json"),                 // or "xml"
        adapter.WithDebug(true),                    // debug mode
        adapter.WithLogger(...),          // custom logger
    ))
}

Call API methods

Client uses models (method groups) to call methods. Each model has a set of methods to work with it.

For example, you want to get list of cities from Nova Poshta API. You should use Address model and GetCities method, like this:

package main

import (
    "fmt"
	
    "github.com/platx/go-nova-poshta"
    "github.com/platx/go-nova-poshta/adapter"
    "github.com/platx/go-nova-poshta/api/address"
    "github.com/platx/go-nova-poshta/utils"
)

func main() {
    client := go_nova_poshta.NewClient(adapter.NewConfig("your_api_token"))

    cities, err := client.Address().GetCities(address.GetCitiesRequest{
        FindByString: utils.PTR("Київ"),
        Page: utils.PTR(1),
        Limit: utils.PTR(10),
    })
	
    if err != nil {
        panic(err)
    }
	
    fmt.Println(cities)
}

All available models and methods

Model	Method	Request params	Response data	Usage	Documentation
Address	SearchSettlements	address.SearchSettlementsReq	address.SearchSettlementRes	client.Address().SearchSettlements(address.SearchSettlementsReq{})	Link
Address	SearchSettlementStreets	address.SearchSettlementStreetsReq	address.SearchSettlementStreetsRes	client.Address().SearchSettlementStreets(address.SearchSettlementStreetsReq{})	Link
Address	Save	address.CreateReq	address.SaveRes	client.Address().Save(address.CreateReq{})	Link
Address	Update	address.UpdateReq	address.SaveRes	client.Address().Update(address.UpdateReq{})	Link
Address	Delete	address.DeleteReq	address.DeleteRes	client.Address().Delete(address.DeleteReq{})	Link
Address	GetSettlements	address.GetSettlementsReq	address.GetSettlementsRes	client.Address().GetSettlements(address.GetSettlementsReq{})	Link
Address	GetCities	address.GetCitiesReq	address.GetCitiesRes	client.Address().GetCities(address.GetCitiesReq{})	Link
Address	GetAreas	-	address.GetAreasRes	client.Address().GetAreas()	Link
Address	GetWarehouses	address.GetWarehousesReq	address.GetWarehousesRes	client.Address().GetWarehouses(address.GetWarehousesReq{})	Link
Address	GetWarehouseTypes	-	address.GetWarehouseTypesRes	client.Address().GetWarehouseTypes()	Link
Address	GetStreet	address.GetStreetReq	address.GetStreetRes	client.Address().GetStreet(address.GetStreetReq{})	Link
Counterparty	SavePrivatePerson	counterparty.SavePrivatePersonReq	counterparty.SaveRes	client.Counterparty().SavePrivatePerson(counterparty.SavePrivatePersonReq{})	Link
Counterparty	SaveThirdPerson	counterparty.SaveThirdPerson	counterparty.SaveRes	client.Counterparty().SaveThirdPerson(counterparty.SaveThirdPerson{})	Link
Counterparty	SaveOrganization	counterparty.SaveOrganizationReq	counterparty.SaveRes	client.Counterparty().SaveOrganization(counterparty.SaveOrganizationReq{})	Link
Counterparty	Update	counterparty.UpdateReq	counterparty.SaveRes	client.Counterparty().Update(counterparty.UpdateReq{})	Link
Counterparty	Delete	counterparty.DeleteReq	counterparty.DeleteRes	client.Counterparty().Delete(counterparty.DeleteReq{})	Link
ContactPerson	Save	contactperson.CreateReq	contactperson.SaveRes	client.ContactPerson().Save(contactperson.CreateReq{})	Link
ContactPerson	Update	contactperson.UpdateReq	contactperson.SaveRes	client.ContactPerson().Update(contactperson.UpdateReq{})	Link
ContactPerson	Delete	contactperson.DeleteReq	contactperson.DeleteRes	client.ContactPerson().Delete(contactperson.DeleteReq{})	Link
ScanSheet	GetScanSheetList	-	scansheet.GetScanSheetListRes	client.ScanSheet().GetScanSheetList()	Link
ScanSheet	GetScanSheet	scansheet.GetScanSheetReq	scansheet.GetScanSheetRes	client.ScanSheet().GetScanSheet(scansheet.GetScanSheetReq{})	Link
ScanSheet	InsertDocuments	scansheet.InsertDocumentsReq	scansheet.InsertDocumentsRes	client.ScanSheet().InsertDocuments(scansheet.InsertDocumentsReq{})	Link
ScanSheet	RemoveDocuments	scansheet.RemoveDocumentsReq	scansheet.RemoveDocumentsRes	client.ScanSheet().RemoveDocuments(scansheet.RemoveDocumentsReq{})	Link
ScanSheet	DeleteScanSheet	scansheet.DeleteScanSheetReq	scansheet.DeleteScanSheetRes	client.ScanSheet().DeleteScanSheet(scansheet.DeleteScanSheetReq{})	Link
Common	GetTimeIntervals	common.GetTimeIntervalsReq	common.GetTimeIntervalsRes	client.Common().GetTimeIntervals(contactperson.GetTimeIntervalsReq{})	Link
Common	GetCargoTypes	-	common.ListItemsRes[enum.CargoType]	client.Common().GetCargoTypes()	Link
Common	GetBackwardDeliveryCargoTypes	-	common.ListItemsRes[enum.CargoType]	client.Common().GetBackwardDeliveryCargoTypes()	Link
Common	GetPalletsList	-	common.GetPalletsListRes	client.Common().GetPalletsList()	Link
Common	GetTypesOfPayersForRedelivery	-	common.ListItemsRes[string]	client.Common().GetTypesOfPayersForRedelivery()	Link
Common	GetPackList	-	common.GetPackListRes	client.Common().GetPackList()	Link
Common	GetTiresWheelsList	-	common.GetTiresWheelsListRes	client.Common().GetTiresWheelsList()	Link
Common	GetCargoDescriptionList	-	common.GetCargoDescriptionListRes	client.Common().GetCargoDescriptionList()	Link
Common	GetMessageCodeText	-	common.GetMessageCodeTextRes	client.Common().GetMessageCodeText()	Link
Common	GetServiceTypes	-	common.ListItemsRes[enum.ServiceType]	client.Common().GetServiceTypes()	Link
Common	GetOwnershipFormsList	-	common.GetOwnershipFormsListRes	client.Common().GetOwnershipFormsList()	Link
AdditionalService	CheckPossibilityCreateReturn	additionalservice.CheckPossibilityCreateReturnReq	additionalservice.CheckPossibilityCreateReturnRes	client.AdditionalService().CheckPossibilityCreateReturn(additionalservice.CheckPossibilityCreateReturnReq{})	Link
AdditionalService	GetReturnReasons	-	additionalservice.GetReturnReasonsRes	client.AdditionalService().GetReturnReasons()	Link
AdditionalService	GetReturnReasonsSubtypes	additionalservice.GetReturnReasonsSubtypesReq	additionalservice.GetReturnReasonsSubtypesRes	client.AdditionalService().GetReturnReasonsSubtypes(additionalservice.GetReturnReasonsSubtypesReq{})	Link
AdditionalService	CheckPossibilityForRedirecting	additionalservice.CheckPossibilityCreateReturnReq	additionalservice.CheckPossibilityForRedirectingRes	client.AdditionalService().CheckPossibilityForRedirecting(additionalservice.CheckPossibilityCreateReturnReq{})	Link
AdditionalService	CheckPossibilityChangeEW	additionalservice.CheckPossibilityChangeEWReq	additionalservice.CheckPossibilityChangeEWRes	client.AdditionalService().CheckPossibilityChangeEW(additionalservice.CheckPossibilityChangeEWReq{})	Link
AdditionalService	SaveReturn	additionalservice.SaveReturnReq	additionalservice.SaveRes	client.AdditionalService().SaveReturn(additionalservice.SaveReturnReq{})	Link
AdditionalService	SaveReturnNewAddress	additionalservice.SaveReturnNewAddressReq	additionalservice.SaveRes	client.AdditionalService().SaveReturnNewAddress(additionalservice.SaveReturnNewAddressReq{})	Link
AdditionalService	SaveReturnNewWarehouse	additionalservice.SaveReturnNewWarehouseReq	additionalservice.SaveRes	client.AdditionalService().SaveReturnNewWarehouse(additionalservice.SaveReturnNewWarehouseReq{})	Link
AdditionalService	SaveRedirecting	additionalservice.SaveRedirectingReq	additionalservice.SaveRes	client.AdditionalService().SaveRedirecting(additionalservice.SaveRedirectingReq{})	Link
AdditionalService	SaveChangeEW	additionalservice.SaveChangeEWReq	additionalservice.SaveRes	client.AdditionalService().SaveChangeEW(additionalservice.SaveChangeEWReq{})	Link
AdditionalService	Delete	additionalservice.DeleteReq	additionalservice.DeleteRes	client.AdditionalService().Delete(additionalservice.DeleteReq{})	Link
AdditionalService	GetReturnOrdersList	additionalservice.GetOrdersListReq	additionalservice.GetOrdersListRes	client.AdditionalService().GetReturnOrdersList(additionalservice.GetOrdersListReq{})	Link
AdditionalService	GetChangeEWOrdersList	additionalservice.GetOrdersListReq	additionalservice.GetOrdersListRes	client.AdditionalService().GetChangeEWOrdersList(additionalservice.GetOrdersListReq{})	Link
AdditionalService	GetRedirectionOrdersList	additionalservice.GetOrdersListReq	additionalservice.GetOrdersListRes	client.AdditionalService().GetRedirectionOrdersList(additionalservice.GetOrdersListReq{})	Link
InternetDocument	GetDocumentPrice	internetdocument.GetDocumentPriceReq	internetdocument.GetDocumentPriceRes	client.InternetDocument().GetDocumentPrice(internetdocument.GetDocumentPriceReq{})	Link
InternetDocument	GetDocumentDeliveryDate	internetdocument.GetDocumentDeliveryDateReq	internetdocument.GetDocumentDeliveryDateRes	client.InternetDocument().GetDocumentDeliveryDate(internetdocument.GetDocumentDeliveryDateReq{})	Link
InternetDocument	Save	internetdocument.SaveReq	internetdocument.SaveRes	client.InternetDocument().Save(internetdocument.SaveReq{})	Link
InternetDocument	SavePostomat	internetdocument.PostomatSaveReq	internetdocument.SaveRes	client.InternetDocument().SavePostomat(internetdocument.PostomatSaveReq{})	Link
InternetDocument	SaveWarehouse	internetdocument.WarehouseSaveReq	internetdocument.SaveRes	client.InternetDocument().SaveWarehouse(internetdocument.WarehouseSaveReq{})	Link
InternetDocument	SaveAddress	internetdocument.AddressSaveReq	internetdocument.SaveRes	client.InternetDocument().SaveAddress(internetdocument.AddressSaveReq{})	Link
InternetDocument	Update	internetdocument.UpdateReq	internetdocument.SaveRes	client.InternetDocument().Update(internetdocument.UpdateReq{})	Link
InternetDocument	Delete	internetdocument.DeleteReq	internetdocument.DeleteRes	client.InternetDocument().Delete(internetdocument.DeleteReq{})	Link
InternetDocument	GetDocumentList	internetdocument.GetDocumentListReq	internetdocument.GetDocumentListRes	client.InternetDocument().GetDocumentList(internetdocument.GetDocumentListReq{})	Link
TrackingDocument	GetStatusDocuments	trackingdocument.GetStatusDocumentsReq	trackingdocument.GetStatusDocumentsRes	client.TrackingDocument().GetStatusDocuments(trackingdocument.GetStatusDocumentsReq{})	Link

Custom API calls

If you are not ok with the provided API models/methods, you can always make your own custom calls. For example, if you want to make a call to the Address model with getCities method, you can do it like this:

package main

import (
    "fmt"
	
    "github.com/platx/go-nova-poshta"
    "github.com/platx/go-nova-poshta/adapter"
)

func main() {
    client := go_nova_poshta.NewClient(adapter.NewConfig("your_api_token"))

    req := map[string]any{
        "FindByString": "Київ",
        "Limit":        10,
        "Page":         1,
    }

    var res []map[string]any

    err := client.Custom().Call("Address", "getCities", req, &res)

    if err != nil {
        panic(err)
    }

    fmt.Println(res)
}

P.S. In this case you have take care for the request/response structs by yourself.