MyClub/eshop/packeta.md

Comprehensive Guide to Integrating Packeta into Your Custom E-Shop
This guide provides a step-by-step overview of integrating Packeta's delivery services into your fully custom e-shop. Packeta is a digital platform for packet delivery, offering home delivery and pick-up points/boxes worldwide through a single interface. It's designed for e-shops to streamline shipping, with features like cash-on-delivery (COD), age verification, and reverse logistics. The integration involves using their API for backend operations and a widget for frontend selection of delivery options. Implementation can vary based on your e-shop's tech stack (e.g., PHP, Node.js, Python backend), but I'll provide general REST/XML examples using curl and Python, as the API is primarily XML-based. Assume your e-shop can make HTTP requests and handle JavaScript for the widget.
Prerequisites

Basic knowledge of REST APIs, XML, and JavaScript.
A custom e-shop with a checkout process, order management, and backend capable of API calls.
Register for a Packeta account at https://client.packeta.com to get your API key (a 16-character string). This is required for authentication.
For testing, use your standard account (no charges for undispatched packets) or create a test account in the client section. No separate sandbox URL—use the production endpoint for testing.

API Overview
Packeta's API supports two equivalent interfaces:

REST/XML: Send POST requests with XML bodies to https://www.zasilkovna.cz/api/rest.
SOAP: Use the WSDL at https://www.zasilkovna.cz/api/soap.wsdl (or bugfix version: https://www.zasilkovna.cz/api/soap-php-bugfix.wsdl).

All requests require your apiPassword as the first element. Responses are XML. There are no webhooks for real-time updates—poll for status changes using tracking methods.
Basic curl example for REST/XML:
textcurl -X POST https://www.zasilkovna.cz/api/rest \
  -H "Content-Type: text/xml" \
  -d '@request.xml'
Where request.xml contains the XML payload.
Available Delivery Services
Packeta offers several services suitable for e-shops:

Pick-up Delivery: Customers pick up at Packeta pick-up points (PUDOs) or Z-BOXes (24/7 automated boxes). Supports COD and age verification. Not all points allow packet drop-off—filter using attributes if managing lists manually.
Home Delivery: Delivered by various carriers to customer addresses. Use a specific carrier's addressId or "Best Delivery Solution" (BDS) for automatic carrier selection (not available in all countries). Supports COD; some carriers require direct labels.
Carrier Pick-up Delivery: Use external carriers' pick-up points/boxes. Filter by carrier IDs.
Reverse Logistics (Returns): Includes Claim Assistant (unique return labels/passwords) and Return Packets (single code for all returns).

For pick-up points and carriers, Packeta provides data feeds (e.g., CSV/JSON exports) for lists if you don't use the widget. These are updated regularly—download daily for accuracy. Check the Packeta docs or client section for exact URLs (e.g., carriers list for addressId values and PUDOs for point details). If implementing without the widget, parse these feeds to display options in your checkout.
Step 1: Integrate the Pick-up Point Widget (Frontend)
For pick-up delivery, use Packeta's widget to let customers select a PUDO or Z-BOX during checkout. This is the recommended approach for custom e-shops, as it handles mapping, filtering, and geolocation without you managing thousands of points.
Setup

Include the widget library in your checkout page:text<script src="https://widget.packeta.com/v6/www/js/library.js"></script>
Configure in the Packeta client section: Set allowed countries, categories, and carriers (changes take ~90 minutes).
Launch the widget when Packeta delivery is selected (modal or inline).

Code Example (JavaScript - Modal Mode)
JavaScript// Trigger on delivery option select
function openPacketaWidget() {
  Packeta.Widget.pick(
    'YOUR_16_CHAR_API_KEY',  // Replace with your API key
    function(point) {
      if (point) {
        // Save selected point to order (use point.id as addressId in createPacket)
        console.log('Selected Point ID:', point.id, 'Name:', point.name);
        // e.g., send to backend via AJAX: { addressId: point.id, type: point.type }
      } else {
        console.log('Widget cancelled');
      }
    },
    {
      language: 'en',  // UI language (e.g., 'en', 'cs')
      country: 'cz,sk',  // Filter countries (ISO codes)
      weight: 5,  // Filter by package weight (kg)
      // Other options: vendors (array), claimAssistant: 'yes', packetConsignment: 'yes', etc.
    }
  );
}
Inline Mode Example
JavaScriptconst container = document.getElementById('packeta-container');  // Your DIV with width/height
Packeta.Widget.pick('YOUR_API_KEY', callbackFunction, options, container);
Validation
After selection, validate the point by POSTing to https://widget.packeta.com/v6/pps/api/widget/v1/validate with JSON body: { apiKey, options, point: { id: pointId } }. Response includes isValid and errors.
Customization

Filter by weight, dimensions, location (latitude/longitude).
Use appIdentity for your e-shop name/version (e.g., 'custom-eshop-v1.0').
For geolocation, use HTTPS and add allow="geolocation" to iframe sandbox.

Step 2: Create Packets/Shipments (Backend)
When an order is placed, create a packet using the API. Use the addressId from the widget (for PUDOs) or carrier list (for home).
Code Example (XML for createPacket - Pick-up or Home)
XML<createPacket>
  <apiPassword>YOUR_API_PASSWORD</apiPassword>
  <packetAttributes>
    <number>ORDER-123</number>  <!-- Your order ID -->
    <name>John</name>
    <surname>Doe</surname>
    <email>john@example.com</email>
    <phone>+420123456789</phone>  <!-- Optional -->
    <addressId>95</addressId>  <!-- PUDO ID from widget or carrier addressId -->
    <value>100.00</value>  <!-- Packet value -->
    <currency>CZK</currency>
    <weight>2</weight>  <!-- In kg -->
    <eshop>YourEshopName</eshop>  <!-- Your shop identifier -->
    <!-- Optional: cod (COD amount), adultContent (true for age 18+), etc. -->
  </packetAttributes>
</createPacket>
Send via curl or backend. Response XML: <packetId>1234567890</packetId>. Store this in your database.
Python Example (Using requests)
Pythonimport requests

xml_payload = """
<createPacket>
  <apiPassword>YOUR_API_PASSWORD</apiPassword>
  <packetAttributes>
    <number>ORDER-123</number>
    <name>John</name>
    <surname>Doe</surname>
    <email>john@example.com</email>
    <addressId>95</addressId>
    <value>100.00</value>
    <currency>CZK</currency>
    <weight>2</weight>
    <eshop>YourEshopName</eshop>
  </packetAttributes>
</createPacket>
"""

headers = {'Content-Type': 'text/xml'}
response = requests.post('https://www.zasilkovna.cz/api/rest', data=xml_payload, headers=headers)
if response.status_code == 200:
  # Parse XML for packetId (use xml.etree.ElementTree)
  from xml.etree import ElementTree as ET
  root = ET.fromstring(response.text)
  packet_id = root.find('.//packetId').text
  print(f'Packet created: {packet_id}')
else:
  print('Error:', response.text)
Validation Before Creation
Use packetAttributesValid with the same attributes to check for errors before creating.
For Multiple Packets
Use createShipment with array of packetIds.
Step 3: Generate Labels
After packet creation, generate a label for printing.
XML Example (packetLabelPdf)
XML<packetLabelPdf>
  <apiPassword>YOUR_API_PASSWORD</apiPassword>
  <packetId>1234567890</packetId>
  <format>A6 on A4</format>  <!-- Options: A6 on A6, A7 on A4, etc. -->
  <offset>0</offset>  <!-- Label position on page -->
</packetLabelPdf>
Response: Binary PDF. Save and provide to your packing team.
For external carriers, use packetCourierLabelPdf with courierNumber.
Python: Similar to above, save response.content to file.
Step 4: Tracking and Status Updates
Poll for updates using packetStatus or packetTracking.
XML Example (packetStatus)
XML<packetStatus>
  <apiPassword>YOUR_API_PASSWORD</apiPassword>
  <packetId>1234567890</packetId>
</packetStatus>
Response: Current status (e.g., code, date, text).
Integrate into your e-shop's order dashboard—e.g., cron job to update statuses.
For external carriers, use packetCourierTracking.
Step 5: Handling Cancellations
If order cancelled before submission, use cancelPacket.
XML<cancelPacket>
  <apiPassword>YOUR_API_PASSWORD</apiPassword>
  <packetId>1234567890</packetId>
</cancelPacket>
```<grok-card data-id="bb18aa" data-type="citation_card"></grok-card>

### Step 6: Reverse Logistics (Returns)
For customer returns:
- **Claim Assistant**: Create unique return with `createPacketClaimWithPassword`.
  XML Example:
  ```xml
  <createPacketClaimWithPassword>
    <apiPassword>YOUR_API_PASSWORD</apiPassword>
    <claimWithPasswordAttributes>
      <id>RETURN-123</id>  <!-- Unique return ID -->
      <number>ORDER-123</number>
      <email>john@example.com</email>
      <value>100.00</value>
      <currency>CZK</currency>
      <eshop>YourEshopName</eshop>
      <sendEmailToCustomer>true</sendEmailToCustomer>  <!-- Optional: Send label to customer -->
    </claimWithPasswordAttributes>
  </createPacketClaimWithPassword>
Response: Packet details. Provide password to customer for drop-off at PUDO.

Return Packet: Generate a single return code in the client section and share with all customers for label-free returns.

Validate claims with packetClaimAttributesValid.
Additional Tips

Error Handling: API throws faults (e.g., PacketAttributesFault)—parse responses for errors.
Data Feeds: For custom lists (e.g., carriers for home delivery or PUDOs without widget), download Packeta's exports from the docs or client section (typically CSV/JSON, updated daily). Use them to populate dropdowns if needed.
International: Filter by country in widget/options. Check carrier support for BDS/COD.
Security: Store API key securely; use HTTPS.
Testing: Create test packets, generate labels, track, and cancel without real dispatch.
Limitations: No webhooks—implement polling. For large volumes, batch methods like packetsLabelsPdf.
Full API methods are listed in the Packeta docs—refer to /docs/api-reference/api-methods for advanced features like B2B packets or storage extensions.

This guide covers the core integration. If your e-shop uses a specific framework (e.g., Laravel, Express), adapt the examples accordingly. For any missing details (e.g., exact data feed URLs), check the official docs or contact Packeta support. If you provide more details about your tech stack, I can refine the examples!