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 YOUR_API_PASSWORD ORDER-123 John Doe john@example.com +420123456789 95 100.00 CZK 2 YourEshopName Send via curl or backend. Response XML: 1234567890. Store this in your database. Python Example (Using requests) Pythonimport requests

xml_payload = """ YOUR_API_PASSWORD ORDER-123 John Doe john@example.com 95 100.00 CZK 2 YourEshopName """

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 YOUR_API_PASSWORD 1234567890 A6 on A4 0 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 YOUR_API_PASSWORD 1234567890 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 YOUR_API_PASSWORD 1234567890

### 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!