inpost

package module
v0.0.0-...-e965007 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 9, 2026 License: MIT Imports: 12 Imported by: 1

Documentation

Overview

Package inpost provides a Go client for the InPost ShipX API.

Standalone package licensed under MIT.

Features (planned):

  • Bearer token authentication (Legacy ShipX)
  • Shipment creation (paczkomat + courier)
  • Label generation (PDF, EPL, ZPL)
  • Status tracking and webhook handling
  • Parcel size validation (A, B, C)

Index

Constants

View Source 
const MaxParcelWeightKg = 25.0

MaxParcelWeightKg is the maximum weight for an InPost parcel (25 kg).

Variables

View Source 
var (
	ErrUnauthorized = errors.New("inpost: unauthorized")
	ErrNotFound     = errors.New("inpost: not found")
	ErrServerError  = errors.New("inpost: server error")
	ErrValidation   = errors.New("inpost: validation error")
)

Sentinel errors for API responses.

View Source 
var (
	ErrWeightExceeded     = errors.New("inpost: parcel weight exceeds 25 kg")
	ErrInvalidTemplate    = errors.New("inpost: invalid parcel template")
	ErrMissingTargetPoint = errors.New("inpost: target_point required for locker delivery")
	ErrMissingAddress     = errors.New("inpost: address required for courier delivery")
	ErrMissingReceiver    = errors.New("inpost: receiver name and phone are required")
)

Validation errors returned by ValidateCreateShipment.

View Source 
var ParcelDimensions = map[ParcelTemplate]Dimensions{
	ParcelSmall:  {Height: 80, Width: 380, Length: 640},
	ParcelMedium: {Height: 190, Width: 380, Length: 640},
	ParcelLarge:  {Height: 410, Width: 380, Length: 640},
}

ParcelDimensions maps standard templates to their maximum dimensions in mm.

Functions

func MapStatus 

func MapStatus(inpostStatus string) (openomsStatus string, ok bool)

MapStatus translates an InPost shipment status to the corresponding OpenOMS shipment_status string.

func ValidateCreateShipment 

func ValidateCreateShipment(req *CreateShipmentRequest) error

ValidateCreateShipment checks a CreateShipmentRequest for common errors before sending it to the API.

func VerifyWebhook 

func VerifyWebhook(secret string, signature string, body []byte) error

VerifyWebhook verifies the HMAC-SHA256 signature of a webhook payload. The signature is expected to be a hex-encoded string.

Types

type APIError 

type APIError struct {
	StatusCode int               `json:"-"`
	Message    string            `json:"message"`
	Details    map[string]any    `json:"details"`
	Keys       map[string]string `json:"keys"`
}

APIError represents an error response from the InPost API.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Unwrap 

func (e *APIError) Unwrap() error

type Address 

type Address struct {
	Street      string `json:"street"`
	City        string `json:"city"`
	PostCode    string `json:"post_code"`
	CountryCode string `json:"country_code"`
}

Address is a physical mailing address.

type Client 

type Client struct {
	Shipments      *ShipmentService
	Labels         *LabelService
	Points         *PointService
	Tracking       *TrackingService
	DispatchOrders *DispatchOrderService
	// contains filtered or unexported fields
}

Client is an InPost ShipX API client.

func NewClient 

func NewClient(token, organizationID string, opts ...Option) *Client

NewClient creates a new InPost API client.

type CreateDispatchOrderRequest 

type CreateDispatchOrderRequest struct {
	Shipments []int64               `json:"shipments"`
	Address   *DispatchOrderAddress `json:"address"`
	Name      string                `json:"name"`
	Phone     string                `json:"phone"`
	Email     string                `json:"email"`
	Comment   string                `json:"comment,omitempty"`
}

CreateDispatchOrderRequest is the payload sent to create a new dispatch order.

type CreateShipmentRequest 

type CreateShipmentRequest struct {
	Receiver         Receiver          `json:"receiver"`
	Parcels          []Parcel          `json:"parcels"`
	Service          ServiceType       `json:"service"`
	Reference        string            `json:"reference,omitempty"`
	Comments         string            `json:"comments,omitempty"`
	CustomAttributes *CustomAttributes `json:"custom_attributes,omitempty"`
}

CreateShipmentRequest is the payload sent to create a new shipment.

type CustomAttributes 

type CustomAttributes struct {
	TargetPoint   string `json:"target_point,omitempty"`
	SendingMethod string `json:"sending_method,omitempty"`
}

CustomAttributes holds service-specific attributes.

type Dimensions 

type Dimensions struct {
	Height float64 `json:"height"`
	Width  float64 `json:"width"`
	Length float64 `json:"length"`
}

Dimensions holds parcel measurements in millimeters.

type DispatchOrder 

type DispatchOrder struct {
	ID        int64                 `json:"id"`
	Status    string                `json:"status"`
	Shipments []int64               `json:"shipments"`
	Address   *DispatchOrderAddress `json:"address"`
	Name      string                `json:"name"`
	Phone     string                `json:"phone"`
	Email     string                `json:"email"`
	Comment   string                `json:"comment"`
	CreatedAt string                `json:"created_at"`
	UpdatedAt string                `json:"updated_at"`
}

DispatchOrder is the API response for a dispatch order resource.

type DispatchOrderAddress 

type DispatchOrderAddress struct {
	Street         string `json:"street"`
	BuildingNumber string `json:"building_number"`
	City           string `json:"city"`
	PostCode       string `json:"post_code"`
	CountryCode    string `json:"country_code"`
}

DispatchOrderAddress is the pickup address for a dispatch order.

type DispatchOrderService 

type DispatchOrderService struct {
	// contains filtered or unexported fields
}

DispatchOrderService handles dispatch-order-related API operations.

func (*DispatchOrderService) Create 

func (s *DispatchOrderService) Create(ctx context.Context, req *CreateDispatchOrderRequest) (*DispatchOrder, error)

Create creates a new dispatch order for the given shipments.

func (*DispatchOrderService) Delete 

func (s *DispatchOrderService) Delete(ctx context.Context, id int64) error

Delete cancels a dispatch order by its ID.

func (*DispatchOrderService) Get 

func (s *DispatchOrderService) Get(ctx context.Context, id int64) (*DispatchOrder, error)

Get retrieves a dispatch order by its ID.

type LabelFormat 

type LabelFormat string

LabelFormat specifies the label output format. 

const (
	LabelPDF LabelFormat = "Pdf"
	LabelZPL LabelFormat = "Zpl"
	LabelEPL LabelFormat = "Epl"
)

Label format constants.

type LabelPageFormat 

type LabelPageFormat string

LabelPageFormat specifies the label page size. 

const (
	LabelPageNormal LabelPageFormat = "normal" // A6
	LabelPageA4     LabelPageFormat = "A4"
)

Label page format constants.

type LabelService 

type LabelService struct {
	// contains filtered or unexported fields
}

LabelService handles label-related API operations.

func (*LabelService) Generate 

func (s *LabelService) Generate(ctx context.Context, shipmentIDs []int64, format LabelFormat, pageFormat LabelPageFormat) ([]byte, error)

Generate creates labels for one or more shipments. Returns raw binary data.

func (*LabelService) Get 

func (s *LabelService) Get(ctx context.Context, shipmentID int64, format LabelFormat) ([]byte, error)

Get retrieves the label for a single shipment. Returns raw binary data.

type Offer 

type Offer struct {
	ID      int64        `json:"id"`
	Service OfferService `json:"service"`
	Status  string       `json:"status"`
	Rate    *float64     `json:"rate"` // nullable
}

Offer represents a shipping offer returned during shipment creation.

type OfferService 

type OfferService struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

OfferService identifies the service of an offer.

type Option 

type Option func(*Client)

Option configures a Client.

func WithBaseURL 

func WithBaseURL(url string) Option

WithBaseURL sets a custom base URL (useful for testing).

func WithHTTPClient 

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets the HTTP client used for API requests.

func WithPointsBaseURL 

func WithPointsBaseURL(url string) Option

WithPointsBaseURL sets a custom base URL for the Points API (useful for testing).

func WithSandbox 

func WithSandbox() Option

WithSandbox configures the client to use the InPost sandbox environment.

type Parcel 

type Parcel struct {
	Template   ParcelTemplate `json:"template,omitempty"`
	Dimensions *Dimensions    `json:"dimensions,omitempty"`
	Weight     Weight         `json:"weight"`
}

Parcel describes a parcel to ship.

type ParcelResponse 

type ParcelResponse struct {
	ID         int64      `json:"id"`
	Template   string     `json:"template"`
	Dimensions Dimensions `json:"dimensions"`
	Weight     Weight     `json:"weight"`
}

ParcelResponse is a parcel as returned by the API.

type ParcelTemplate 

type ParcelTemplate string

ParcelTemplate identifies the standard locker parcel sizes. 

const (
	ParcelSmall  ParcelTemplate = "small"  // A: 8x38x64cm
	ParcelMedium ParcelTemplate = "medium" // B: 19x38x64cm
	ParcelLarge  ParcelTemplate = "large"  // C: 41x38x64cm
)

Standard locker parcel size templates.

type Point 

type Point struct {
	Name                string               `json:"name"`
	Type                []string             `json:"type"`
	Address             PointAddress         `json:"address"`
	AddressDetails      *PointAddressDetails `json:"address_details,omitempty"`
	Location            PointLocation        `json:"location"`
	LocationDescription string               `json:"location_description"`
	OpeningHours        string               `json:"opening_hours"`
	Status              string               `json:"status"`
}

Point represents an InPost pickup/delivery point (paczkomat).

type PointAddress 

type PointAddress struct {
	Line1 string `json:"line1"`
	Line2 string `json:"line2"`
}

PointAddress is the address of an InPost point.

type PointAddressDetails 

type PointAddressDetails struct {
	City           string `json:"city"`
	Province       string `json:"province"`
	PostCode       string `json:"post_code"`
	Street         string `json:"street"`
	BuildingNumber string `json:"building_number"`
}

PointAddressDetails contains structured address fields.

type PointLocation 

type PointLocation struct {
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
}

PointLocation holds GPS coordinates.

type PointSearchResponse 

type PointSearchResponse struct {
	Items      []Point `json:"items"`
	Count      int     `json:"count"`
	Page       int     `json:"page"`
	PerPage    int     `json:"per_page"`
	TotalPages int     `json:"total_pages"`
}

PointSearchResponse is the paginated response from the points search endpoint.

type PointService 

type PointService struct {
	// contains filtered or unexported fields
}

PointService handles InPost point/paczkomat search operations.

func (*PointService) Get 

func (s *PointService) Get(ctx context.Context, name string) (*Point, error)

Get retrieves a single point by its exact name (e.g., "WAW123M").

func (*PointService) Search 

func (s *PointService) Search(ctx context.Context, query string, pointType PointType, perPage int) (*PointSearchResponse, error)

Search searches for InPost points. If the query looks like a point code (e.g. "KRA01M"), it searches by exact name. Otherwise it searches by city name.

type PointType 

type PointType string

PointType identifies the type of InPost point. 

const (
	PointTypeParcelLocker PointType = "parcel_locker"
	PointTypePOP          PointType = "pop"
)

InPost point type constants.

type Receiver 

type Receiver struct {
	Name    string   `json:"name"`
	Phone   string   `json:"phone"`
	Email   string   `json:"email"`
	Address *Address `json:"address,omitempty"`
}

Receiver contains recipient details.

type SendingMethod 

type SendingMethod string

SendingMethod identifies how the sender hands over parcels to InPost. 

const (
	SendingMethodParcelLocker  SendingMethod = "parcel_locker"
	SendingMethodDispatchOrder SendingMethod = "dispatch_order"
	SendingMethodPOP           SendingMethod = "pop"
	SendingMethodAnyPoint      SendingMethod = "any_point"
	SendingMethodPOK           SendingMethod = "pok"
	SendingMethodBranch        SendingMethod = "branch"
)

Sending method constants.

type ServiceType 

type ServiceType string

ServiceType identifies the InPost shipping service. 

const (
	ServiceLockerStandard  ServiceType = "inpost_locker_standard"
	ServiceCourierStandard ServiceType = "inpost_courier_standard"
)

Supported InPost shipping service types.

type Shipment 

type Shipment struct {
	ID               int64             `json:"id"`
	Status           string            `json:"status"`
	TrackingNumber   string            `json:"tracking_number"`
	Service          string            `json:"service"`
	Receiver         Receiver          `json:"receiver"`
	Parcels          []ParcelResponse  `json:"parcels"`
	CustomAttributes *CustomAttributes `json:"custom_attributes"`
	Offers           []Offer           `json:"offers,omitempty"`
	Transactions     []Transaction     `json:"transactions,omitempty"`
	CreatedAt        string            `json:"created_at"`
	UpdatedAt        string            `json:"updated_at"`
}

Shipment is the API response for a shipment resource.

type ShipmentService 

type ShipmentService struct {
	// contains filtered or unexported fields
}

ShipmentService handles shipment-related API operations.

func (*ShipmentService) Buy 

func (s *ShipmentService) Buy(ctx context.Context, id int64, offerID int64) (*Shipment, error)

Buy confirms (buys/pays for) a shipment so that labels can be generated. InPost flow: Create → Buy → Get Label. In simplified mode (service specified), offerID can be 0 to auto-select.

func (*ShipmentService) Create 

func (s *ShipmentService) Create(ctx context.Context, req *CreateShipmentRequest) (*Shipment, error)

Create creates a new shipment in the InPost system.

func (*ShipmentService) Delete 

func (s *ShipmentService) Delete(ctx context.Context, id int64) error

Delete removes a shipment that has not yet been confirmed (bought). InPost ShipX only allows deletion of shipments in pre-confirmed statuses (e.g. "created", "offers_prepared", "offer_selected").

func (*ShipmentService) Get 

func (s *ShipmentService) Get(ctx context.Context, id int64) (*Shipment, error)

Get retrieves a shipment by its ID.

type TrackingDetail 

type TrackingDetail struct {
	Status       string `json:"status"`
	OriginStatus string `json:"origin_status"`
	Datetime     string `json:"datetime"`
	Agency       string `json:"agency"`
}

TrackingDetail represents a single tracking event from InPost.

type TrackingResponse 

type TrackingResponse struct {
	TrackingNumber  string           `json:"tracking_number"`
	Service         string           `json:"service"`
	TrackingDetails []TrackingDetail `json:"tracking_details"`
}

TrackingResponse is the response from the tracking endpoint.

type TrackingService 

type TrackingService struct {
	// contains filtered or unexported fields
}

TrackingService handles tracking-related API operations.

func (*TrackingService) Get 

func (s *TrackingService) Get(ctx context.Context, trackingNumber string) (*TrackingResponse, error)

Get retrieves tracking information for a shipment by its tracking number.

type Transaction 

type Transaction struct {
	ID      int64  `json:"id"`
	Status  string `json:"status"` // "success", "failure"
	OfferID int64  `json:"offer_id"`
}

Transaction represents a payment transaction for a shipment.

type WebhookEvent 

type WebhookEvent struct {
	Type    string          `json:"type"`
	Payload json.RawMessage `json:"payload"`
}

WebhookEvent represents an incoming InPost webhook event.

func ParseWebhookEvent 

func ParseWebhookEvent(body []byte) (*WebhookEvent, error)

ParseWebhookEvent parses the raw JSON body of a webhook into a WebhookEvent.

type Weight 

type Weight struct {
	Amount float64 `json:"amount"`
	Unit   string  `json:"unit"`
}

Weight holds parcel weight.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.