# Uniorder: egy API minden küldeményhez

Az Uniorder egyetlen végpontkészlet, amelyen keresztül az integráció a fiók minden küldeményének árajánlatát kéri le, létrehozza, kinyomtatja, követi és lemondja, függetlenül attól, hogyan teljesül a küldemény. Egy árajánlat visszaadja a vállalkozás saját kiszállítását, kérésre pedig a fiók összes fuvarozói címkeszolgáltatását, mindegyiket `rate_id` értékkel. A rendelés a kiválasztott `rate_id` visszaküldésével jön létre; a kérésben semmi más nem választja ki a szolgáltatást.

## 1. Mit készíthet vele

- **Pénztár, amely egyszerre kínál minden szállítási lehetőséget.** A vásárló megadja a címet, a pénztár egyetlen végpontot hív meg, és az oldal a helyi kiszállítást a UPS, a Canada Post és a fiók által használt többi fuvarozó mellett listázza, mindegyiket az árával.
- **Rendeléskezelő vagy ERP-csatlakozó egyetlen kódútvonallal.** Minden csatorna rendelései ugyanazokon a létrehozási, lekérdezési, címke-, követési és lemondási hívásokon mennek keresztül. A csatlakozónak nincs szüksége külön logikára a helyi kiszállításhoz és a fuvarozói címkékhez.
- **Éjszakai tömeges feldolgozás.** Legfeljebb 500 küldemény árajánlata vagy létrehozása történik egy sorba állított feladatban, az eredmények pedig a feladat azonosítójával olvashatók vissza.
- **Ügyfélszolgálati képernyő.** Az ügyintéző megkeres egy rendelést, újranyomtatja a címkéjét, elolvassa a követési idővonalát és lemondja, minden rendelésnél ugyanazzal a négy hívással.

## 2. Amit az Uniorder elvégez Ön helyett

| Uniorder nélkül | Uniorderrel |
|---|---|
| Egy API a helyi kiszállítási rendelésekhez és egy másik a fuvarozói címkékhez, mindegyik saját mezőkkel és válaszokkal | Egy kérésforma (`from_*`, `to_*`, `packages`) és egy válaszforma minden szolgáltatáshoz |
| Az integráció dönti el, melyik fuvarozói API-t hívja meg | Az árajánlat minden szolgáltatást listáz; a kiválasztott díj `rate_id` értéke dönt |
| Szolgáltatásonként külön címke-, követési és lemondási végpontok | A `GET /label`, a `GET /tracking` és a `POST /cancel` minden rendelésnél működik |
| Kötegelt létrehozás csak helyi kiszállításhoz érhető el | Kötegelt árajánlat és kötegelt létrehozás minden szolgáltatáshoz, szinkron vagy sorba állított módon |

Az Uniorder nem váltja fel a meglévő végpontokat; ezek továbbra is elérhetők és változatlanok. Új integrációhoz ez az ajánlott belépési pont.

## 3. Végponttérkép, abban a sorrendben, ahogy az integráció használja

| Lépés | Cél | REST | GraphQL |
|---|---|---|---|
| 1 | Hozzáférési token beszerzése | `POST /api/v1/user/login` | `userLogin` |
| 2 | Árajánlat minden szolgáltatásra | `POST /api/v1/uniorder/rate` | `uniorderRate` |
| 3 | A rendelés létrehozása a kiválasztott díjjal | `POST /api/v1/uniorder` | `uniorderCreate` |
| 4 | A címke nyomtatása | `GET /api/v1/uniorder/{orderId}/label` | `uniorderLabel` |
| 5 | A rendelés lekérdezése | `GET /api/v1/uniorder/{orderId}` | `uniorder` |
| 6 | A rendelés követése | `GET /api/v1/uniorder/{orderId}/tracking` | `uniorderTracking` |
| 7 | A rendelés lemondása | `POST /api/v1/uniorder/{orderId}/cancel` | `uniorderCancel` |
| — | A létrehozáskor meg nem vásárolható címke megvásárlása | `POST /api/v1/uniorder/{orderId}/label` | `uniorderPurchaseLabel` |
| — | Legfeljebb 20 sor árajánlata vagy létrehozása egyszerre | `POST /api/v1/uniorder/rate/batch`, `POST /api/v1/uniorder/batch` | `uniorderRateBatch`, `uniorderCreateBatch` |
| — | Legfeljebb 500 sor sorba állítása | `POST /api/v1/uniorder/rate/batch-async`, `POST /api/v1/uniorder/batch-async`, `GET /api/v1/uniorder/jobs/{jobId}` | `uniorderRateBatchAsync`, `uniorderCreateBatchAsync`, `uniorderJob` |

[REST kézikönyv](/api/documentation#/paths/v1-uniorder-rate/post) · [GraphQL kézikönyv](/api/graphql/documentation#/orders/uniorderRate)

A lépésenkénti kérések, válaszok és ellenőrzések az **Árajánlat és rendelés egy folyamatban** útmutatóban találhatók.

## 4. Példa: pénztár, amely minden lehetőséget kínál

Egy montreali virágüzlet online értékesít. A pénztárban egyszer kér árajánlatot a csomagra, a címkefuvarozókkal együtt:

```bash
curl -X POST https://YOUR_HOST/api/v1/uniorder/rate \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_name": "Fleurs du Plateau", "from_telephone": "5145550100",
    "from_address": "4500 Rue Saint-Denis", "from_city": "Montreal", "from_province": "QC", "from_country": "CA", "from_postcode": "H2J2L3",
    "to_name": "Jane Recipient", "to_telephone": "5145550199",
    "to_address": "6841 Rue Saint-Denis", "to_city": "Montreal", "to_province": "QC", "to_country": "CA", "to_postcode": "H2S2S3",
    "quote_labels": true,
    "packages": [{ "weight": 1.2, "weight_unit": 2, "length": 40, "width": 25, "height": 25, "dimension_unit": 2 }]
  }'
```

A válasz egy `self_delivery` díjat és fuvarozói szolgáltatásonként egy `label_service` díjat listáz. A pénztár ezeket lehetőségekként jeleníti meg; a vásárló az aznapi helyi kiszállítást választja. A rendelés ennek a díjnak a `rate_id` értékével, valamint ugyanazokkal a címekkel és csomagokkal jön létre:

```bash
curl -X POST https://YOUR_HOST/api/v1/uniorder \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-10045" \
  -d '{
    "rate_id": "eyJpdiI6Ik1rT2Z...",
    "ref": "WEB-10045",
    "from_name": "Fleurs du Plateau", "from_telephone": "5145550100",
    "from_address": "4500 Rue Saint-Denis", "from_city": "Montreal", "from_province": "QC", "from_country": "CA", "from_postcode": "H2J2L3",
    "to_name": "Jane Recipient", "to_telephone": "5145550199",
    "to_address": "6841 Rue Saint-Denis", "to_city": "Montreal", "to_province": "QC", "to_country": "CA", "to_postcode": "H2S2S3",
    "packages": [{ "weight": 1.2, "weight_unit": 2, "length": 40, "width": 25, "height": 25, "dimension_unit": 2 }]
  }'
```

A válasz visszaadja a rendelés `id` értékét és követési számait. Az üzlet a `GET /api/v1/uniorder/{orderId}/label` hívással nyomtatja ki a címkét, és a vásárló rendelési oldalán a `GET /api/v1/uniorder/{orderId}/tracking` hívásból származó idővonalat jeleníti meg.

## 5. Példa: minden éjjel szállító ERP

Egy ERP 22:00-kor exportálja a nap rendeléseit. A címeket a `POST /api/v1/uniorder/rate/batch-async` végpontra küldi, addig olvassa a feladatot, amíg a `status` értéke `done` nem lesz, a saját szabályai szerint minden sorhoz kiválaszt egy díjat, majd a kiválasztott sorokat a `POST /api/v1/uniorder/batch-async` végpontra küldi. Minden eredmény tartalmazza a sor `reference` értékét, így az ERP minden eredményt a saját rendelési sorához rendel. A `rate_id` 30 percig érvényes, ezért a létrehozási feladatot röviddel az árajánlati feladat befejezése után kell elküldeni.

## 6. Példa: ügyfélszolgálati képernyő

Ügyfélhívás esetén az ügyintéző képernyője a `GET /api/v1/uniorder/{orderId}` hívással kéri le az állapotot és a címeket, a `GET /api/v1/uniorder/{orderId}/tracking` hívással az idővonalat és a kézbesítés igazolását, és a `POST /api/v1/uniorder/{orderId}/cancel` hívással lemondja a rendelést, amikor a vásárló eláll a vásárlástól. Ugyanezek a hívások érvényesek a kiszállítási rendelésre és a címkerendelésre; a `type` mező különbözteti meg őket.

```bash
curl https://YOUR_HOST/api/v1/uniorder/123456/tracking \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

Ugyanez a rendelés GraphQL-en keresztül ([GraphQL kézikönyv](/api/graphql/documentation#/orders/uniorder)):

```graphql
query {
  uniorder(order_id: 123456)
}
```

## 7. Tervezési szabályok

- **A `rate_id` dönti el a szolgáltatást.** 30 percig érvényes, és csak az árajánlatot kérő fiókra.
- **A rendelés árazása a létrehozáskor történik.** A `shipping_price` a felszámított ár; a `quoted_price` az árajánlat ára. A kettő eltérhet.
- **Címkerendelés nem vész el.** Ha a címke a létrehozáskor nem vásárolható meg, a rendelés megmarad, és a válasz `LABEL_PURCHASE_FAILED` a rendelés `id` értékével; a címke később a `POST /api/v1/uniorder/{orderId}/label` hívással vásárolható meg.
- **Az újrapróbálkozás biztonságos.** Minden létrehozási hívásnál küldjön `Idempotency-Key` fejlécet; egy már lemondott rendelés ismételt lemondása `already_cancelled` `true` értéket ad.
- **Az állapotok egységesek.** A kiszállítási rendelés állapota `pending`, `in_transit`, `out_for_delivery`, `delivered`, `exception` vagy `cancelled`; a címkerendelés állapota `label_pending`, `label_purchased` vagy `cancelled`, és a csomag helyét a fuvarozó követése jelzi.

## 8. Élesítési ellenőrzőlista

- [ ] A fiók rendelkezik API-jogosultsággal, és a token a szerveren van tárolva, nem böngészőben.
- [ ] Az árajánlatok teljes feladói és címzetti címmel készülnek.
- [ ] A rendelések az árajánlatot követő 30 percen belül, `Idempotency-Key` fejléccel jönnek létre.
- [ ] A `LABEL_PURCHASE_FAILED` kezelése a címke későbbi megvásárlásával történik, soha nem a rendelés ismételt létrehozásával.
- [ ] A követés a `GET /api/v1/uniorder/{orderId}/tracking` hívásból olvasható ki, vagy webhookokon keresztül érkezik.
- [ ] A lemondási kérés az `ORDER_STATUS_NOT_CANCELLABLE` és az `ORDER_CANCEL_REFUSED` esetén változatlanul hagyja a rendelést.