175 lines
6.5 KiB
Markdown
175 lines
6.5 KiB
Markdown
# Packeta (Zásilkovna) integration
|
||
|
||
Packeta delivers mainly to **pickup points** and **Z-BOX lockers** (plus
|
||
home delivery in some regions). It's the most common choice for SK/CZ eshops.
|
||
This repo is already **scaffolded** for Packeta's pickup-point picker — you
|
||
mostly need an API key to switch it on. Shipment creation via API is extra,
|
||
optional work.
|
||
|
||
---
|
||
|
||
## 1. Get a Packeta account & keys
|
||
|
||
1. Register a client account at <https://client.packeta.com> (Zásilkovna /
|
||
Packeta). For SK: <https://www.packeta.sk>.
|
||
2. In the client portal open **Client support → API / Nastavenia API** (or
|
||
"Integrations"). You get **two different secrets** — don't mix them up:
|
||
- **Web/Widget API key** — public-ish key used by the browser pickup-point
|
||
widget (`Packeta.Widget.pick`). This is the one this repo already uses.
|
||
- **API password (REST/SOAP)** — secret server key used to *create packets*
|
||
(shipments). Never expose this to the browser.
|
||
3. (For real shipping) configure your **sender/pickup address and label
|
||
format** in the portal.
|
||
|
||
---
|
||
|
||
## 2. Activate the pickup-point picker (already built)
|
||
|
||
The checkout template already loads the widget and wires the chosen point into
|
||
the order **whenever `packeta_api_key` is non-empty**
|
||
(`assets/views/shop/checkout.html`):
|
||
|
||
- loads `https://widget.packeta.com/v6/www/js/library.js`
|
||
- `Packeta.Widget.pick(packetaKey, point => …)` fills hidden
|
||
`pickup_point_id` + `pickup_point_name`
|
||
- if the key is empty it falls back to a plain text field
|
||
|
||
So to turn it on:
|
||
|
||
### a) Set the Web/Widget API key
|
||
|
||
Set the env var (read by `config/development.yaml` / `production.yaml` →
|
||
`settings.packeta_api_key`, exposed via `src/shared/settings.rs`):
|
||
|
||
```bash
|
||
# .env (development) or your production environment
|
||
PACKETA_API_KEY=your_web_widget_api_key
|
||
```
|
||
|
||
`config/development.yaml` already contains:
|
||
```yaml
|
||
settings:
|
||
packeta_api_key: {{ get_env(name="PACKETA_API_KEY", default="") }}
|
||
```
|
||
For production, add the same line under `settings:` in `config/production.yaml`
|
||
(it isn't there yet).
|
||
|
||
### b) Create a Packeta delivery option in the admin
|
||
|
||
Go to **`/admin/shipping`** → "Add delivery option":
|
||
- **Name**: e.g. `Packeta – pickup point`
|
||
- **Price**: your fee (e.g. `2.90`)
|
||
- ✅ **Requires pickup point** ← this makes the picker appear at checkout
|
||
- ✅ **Active**
|
||
|
||
The auto-generated `code` will be `packeta-pickup-point` (or similar). Customers
|
||
now see the option, click "Choose pickup point", pick on the map, and the order
|
||
stores `pickup_point_id` + `pickup_point_name`.
|
||
|
||
**At this point you have a working Packeta flow** — you read the pickup point on
|
||
the order in `/admin/orders` and create the parcel manually in the Packeta
|
||
portal. Many small shops stop here.
|
||
|
||
---
|
||
|
||
## 3. (Optional) Create shipments via API
|
||
|
||
Automate "register the parcel + get tracking + print label". Do the
|
||
[shared groundwork](README.md#shared-groundwork-do-this-once-before-any-carriers-api-step)
|
||
first (HTTP client, `integrations` module, `carrier` column, tracking columns).
|
||
|
||
### Endpoint & auth
|
||
|
||
- Packeta REST API base: `https://www.zasilkovna.cz/api/rest` (SOAP also
|
||
available at `http://www.zasilkovna.cz/api/soap.wsdl`).
|
||
- Auth = your **API password** (the server secret from step 1), sent in the
|
||
request body, **not** the widget key.
|
||
- Key operation: **`createPacket`**. You send sender id, recipient
|
||
name/email/phone, the chosen **pickup point id** (`addressId`), value, weight,
|
||
and COD amount; you receive a **packet id + barcode (tracking)**. A separate
|
||
**`packetLabelPdf`** call returns the label PDF.
|
||
|
||
### Store the secret
|
||
|
||
```bash
|
||
PACKETA_API_PASSWORD=your_secret_api_password
|
||
```
|
||
Add to `config/*.yaml` under `settings:`:
|
||
```yaml
|
||
packeta_api_password: {{ get_env(name="PACKETA_API_PASSWORD", default="") }}
|
||
```
|
||
|
||
### Client sketch (`src/integrations/packeta.rs`)
|
||
|
||
```rust
|
||
use loco_rs::prelude::*;
|
||
use crate::shared::settings;
|
||
|
||
// createPacket accepts XML; serde_json works for the JSON REST variant.
|
||
pub async fn create_shipment(ctx: &AppContext, req: super::ShipmentRequest<'_>)
|
||
-> Result<super::ShipmentResult>
|
||
{
|
||
let api_password = settings::get(ctx, "packeta_api_password")
|
||
.ok_or_else(|| Error::string("packeta_api_password not configured"))?;
|
||
|
||
// Packeta's createPacket is XML/SOAP-ish; build the body per their docs.
|
||
// number = your order_number
|
||
// name/surname = recipient
|
||
// addressId = req.pickup_point_id (the chosen point)
|
||
// cod = req.cod_cents / 100 (0 if not COD)
|
||
// value = goods value
|
||
// eshop = your sender label/id from the portal
|
||
let body = format!(r#"<createPacket>
|
||
<apiPassword>{api_password}</apiPassword>
|
||
<packetAttributes>
|
||
<number>{}</number>
|
||
<name>{}</name>
|
||
<email>{}</email>
|
||
<addressId>{}</addressId>
|
||
<cod>{}</cod>
|
||
<value>{}</value>
|
||
<weight>{}</weight>
|
||
<eshop>YOUR_SENDER_LABEL</eshop>
|
||
</packetAttributes>
|
||
</createPacket>"#,
|
||
req.order_number, req.recipient_name, req.email,
|
||
req.pickup_point_id.unwrap_or(""),
|
||
req.cod_cents as f64 / 100.0,
|
||
req.cod_cents as f64 / 100.0,
|
||
req.weight_grams);
|
||
|
||
let resp = reqwest::Client::new()
|
||
.post("https://www.zasilkovna.cz/api/rest")
|
||
.body(body)
|
||
.send().await.map_err(|e| Error::string(&e.to_string()))?
|
||
.text().await.map_err(|e| Error::string(&e.to_string()))?;
|
||
|
||
// Parse <id> (packet id) and <barcode> (tracking) out of the XML response.
|
||
// Then optionally call packetLabelPdf with that id to fetch the label.
|
||
todo!("parse resp into ShipmentResult")
|
||
}
|
||
```
|
||
|
||
Then call it from your admin "Create shipment" action for orders whose
|
||
`shipping_methods.carrier == "packeta"`, and save `tracking_number` /
|
||
`shipment_id` back on the order.
|
||
|
||
---
|
||
|
||
## 4. Testing
|
||
|
||
- Use the Packeta **sandbox/staging** portal if your account offers one, or a
|
||
test API password. Verify `createPacket` returns a packet id before going
|
||
live.
|
||
- Track the parcel at `https://tracking.packeta.com/...` using the returned
|
||
barcode.
|
||
|
||
## 5. Go-live checklist
|
||
|
||
- [ ] `PACKETA_API_KEY` (widget) set in production env
|
||
- [ ] `packeta_api_key` line added under `settings:` in `config/production.yaml`
|
||
- [ ] Packeta delivery option created in `/admin/shipping` with **Requires pickup point** ✅
|
||
- [ ] (If using API) `PACKETA_API_PASSWORD` set + `src/integrations/packeta.rs` implemented
|
||
- [ ] Sender address & label format configured in the Packeta portal
|
||
- [ ] Test order → pickup point saved on order → (API) tracking number stored
|