Spree Packeta

Packeta (Zasilkovna) shipping integration for Spree Commerce. This gem provides SOAP API integration for packet creation, tracking, and label generation.

Features

• Phase 1 (Current):

  • SOAP client wrapper for Packeta API
  • Packet creation and tracking
  • Shipping method and calculator integration
  • Database tracking fields for shipments

• Planned Features:

  • Dynamic rate calculation from Packeta API
  • Label generation (PDF, PNG, ZPL)
  • COD (Cash on Delivery) support
  • Customs declarations
  • Admin interface for packet management

Installation

Add this line to your application's Gemfile:

gem 'spree_packeta', path: '/Users/oezr/Projects/spree_packeta'

And then execute:

bundle install

Run the installation generator:

bundle exec rails g spree_packeta:install

This will:

• Copy the migration files
• Create an initializer with configuration
• Optionally run migrations
• Optionally install the Packeta shipping method

Manual Installation

If you prefer to install components separately:

# Copy and run migrations
bundle exec rails spree_packeta:install:migrations
bundle exec rails db:migrate

# Install Packeta shipping method
bundle exec rake spree_packeta:install

# Check status
bundle exec rake spree_packeta:status

Configuration

Configure the gem in config/initializers/spree_packeta.rb:

SpreePacketa.configure do |config|
  # API credentials
  config.api_password = ENV['PACKETA_API_PASSWORD']

  # SOAP endpoint (production vs sandbox)
  config.soap_endpoint = ENV.fetch('PACKETA_SOAP_ENDPOINT',
                                    'http://www.zasilkovna.cz/api/soap')

  # WSDL path (can be local file or URL)
  config.wsdl_path = ENV.fetch('PACKETA_WSDL_PATH',
                                'http://www.zasilkovna.cz/api/soap.wsdl')

  # Default eshop identifier
  config.eshop = ENV['PACKETA_ESHOP']

  # Sender information for return labels
  config.sender_name = ENV['PACKETA_SENDER_NAME']
  config.sender_email = ENV['PACKETA_SENDER_EMAIL']
  config.sender_phone = ENV['PACKETA_SENDER_PHONE']

  # Rate caching duration (in seconds)
  config.rate_cache_duration = 3600 # 1 hour

  # Auto-create packets on shipment
  config.auto_create_packets = true

  # Sync tracking status interval
  config.tracking_sync_interval = 1.hour
end

Environment Variables

Add these to your .env file:

PACKETA_API_PASSWORD=your_api_password_here
PACKETA_ESHOP=your_eshop_identifier
PACKETA_SENDER_NAME=Your Store Name
PACKETA_SENDER_EMAIL=shipping@yourstore.com
PACKETA_SENDER_PHONE=+420123456789

# Optional: Use local WSDL file
PACKETA_WSDL_PATH=file:///path/to/soap.wsdl

Usage

Quick Start with Rake Tasks

The easiest way to set up Packeta:

# Install shipping method with default configuration
bundle exec rake spree_packeta:install

# Check installation status and configuration
bundle exec rake spree_packeta:status

# Remove shipping method if needed
bundle exec rake spree_packeta:uninstall

The install task will:

• Create "Packeta" shipping method
• Set up Czech Republic and EU zones
• Configure the Packeta calculator with default rates (99 CZK)
• Assign shipping categories and zones

Manual Setup via Admin Panel

If you prefer manual setup or need to customize:

1. Go to Settings → Shipping Methods
2. Click "New Shipping Method"
3. Fill in:
   • Name: Packeta
   • Admin Name: Packeta (Zásilkovna)
   • Code: packeta
   • Display: Both (or your preference)
   • Tracking URL: https://tracking.packeta.com/:tracking
   • Shipping Categories: Select applicable categories
   • Calculator: Choose "Packeta Shipping Calculator"
4. Configure calculator preferences:
   • Amount: Base shipping rate (e.g., 99.00)
   • Currency: CZK (or your currency)
5. Assign to zones (Czech Republic, EU, etc.)

Creating a Packet

The gem provides services for packet management:

# Create a packet from a shipment
service = SpreePacketa::Services::PacketCreator.new(shipment)
result = service.create_packet

# This will:
# - Extract shipment details
# - Call Packeta API to create packet
# - Store packet ID and barcode on shipment
# - Return packet details

Tracking

# Get current status
tracker = SpreePacketa::Services::Tracker.new(shipment)
status = tracker.current_status
# => { date_time: ..., status_code: ..., status_text: ..., branch_id: ... }

# Get full tracking history
history = tracker.tracking_history
# => [{ date_time: ..., status_code: ..., ... }, ...]

Direct SOAP API Access

For advanced use cases, you can use the SOAP operations directly:

# Initialize operations
ops = SpreePacketa::Soap::Operations.new

# Create a packet
packet = ops.create_packet(
  number: 'ORDER-12345',
  name: 'John',
  surname: 'Doe',
  email: 'john@example.com',
  phone: '+420123456789',
  address_id: 1234, # Packeta pickup point ID
  value: 1000.0,
  weight: 2.5,
  currency: 'CZK'
)
# => { id: 123456, barcode: '...', barcode_text: 'Z...' }

# Get packet status
status = ops.packet_status(packet[:id])
# => { status_code: 1, status_text: 'Packet created', ... }

# Get tracking history
history = ops.packet_tracking(packet[:id])
# => [{ date_time: ..., status_code: ..., ... }, ...]

Database Schema

The gem adds the following columns to spree_shipments:

Column	Type	Description
packeta_packet_id	bigint	Packeta packet ID
packeta_barcode	string	Packet barcode
packeta_tracking_url	string	Full tracking URL
packeta_status_code	integer	Latest status code
packeta_branch_id	integer	Current branch/pickup point ID
packeta_last_sync_at	datetime	Last tracking sync timestamp

Error Handling

The gem defines custom exceptions for different error scenarios:

begin
  ops.create_packet(attributes)
rescue SpreePacketa::AuthenticationError => e
  # Invalid API password
rescue SpreePacketa::ValidationError => e
  # Invalid packet attributes
rescue SpreePacketa::NotFoundError => e
  # Packet not found
rescue SpreePacketa::NetworkError => e
  # Network/connectivity issues
rescue SpreePacketa::ApiError => e
  # Other API errors
end

Development

After checking out the repo, run:

bundle install

Running Tests

bundle exec rspec

Console

bundle exec bin/console

Roadmap

Phase 2: Rate Calculation

• Dynamic rate calculation via Packeta API
• Zone-based pricing
• Service level support
• Rate caching

Phase 3: Label Generation

• PDF label generation
• Multiple format support (PNG, ZPL)
• Batch label generation
• Label storage

Phase 4: Advanced Features

• COD support
• Customs declarations
• Pickup point widget
• Return shipments
• Packet updates

Phase 5: Admin Interface

• Packeta settings page
• Packet management
• Bulk operations
• Tracking dashboard

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/spree_packeta.

License

The gem is available as open source under the terms of the MIT License.

Support

For issues specific to this gem, please open an issue on GitHub.

For Packeta API documentation and support, visit: https://www.zasilkovna.cz/api/