Česká Pošta AE115

Popis #

Tento modul rozšiřuje systém o funkce specifické pro integraci České pošty, jako například exportní funkce, generování kódů balíků, tisk adresních štítku a další. Tento modul navazuje na modul AE056 Tvorba balíků a export dat pro přepravce.

Odkazy na externí webové stránky jsou platné k 23.06.2022.

Export CSV #

Tato úprava implementuje možnost exportu souboru CSV z balíku pro dopravce Česká pošta. Do výběrového pole Typ přepravy byla přidána možnost Česká pošta. Pokud je tato možnost vybrána a tak je při zapsání balíku automaticky exportován soubor CSV k uživateli. Dále je možné soubor exportovat z karty zapsaného balíku pomocí funkce Export CSV České pošty.

Karta balíku #

Pokud je na Kartě balíku vybrán Kód služby přepravce, který má nastaven Typ přepravy Česká pošta", na kartě jsou nově k dispozici:

Velikostní kategorie balíku #

Pole Velikostní kategorie balíku bylo přidáno za rozměry v kategorii Obecné

• Výpočetní pole - nelze upravit, jeho hodnota se počítá automaticky
• Dle oficiálních podkladů České pošty se dle nejdelší strany určuje velikostní kategorie
• S do 35 cm
• M do 50 cm
• L do 100 cm
• XL do 240 cm
• Pokud je nejdelší strana delší než 240 cm, na Kartě balíku se zobrazí notifikace s upozorněním a při generování čísla balíku dojde k chybě

Generování kódu balíku (ID dopravce) #

Akce Vygenerovat ID dopravce byla přidána do kategorie Akce

• Lze spustit pouze, pokud Balík nemá v poli ID Dopravce přiřazené žádné číslo.
• Dle Technické dokumentace pro podání zásilek smluvním podavatelem se vygeneruje číslo balíku.
• Číslo balíku se skládá z:
  • Označení zásilky (ČP) z Nastavení služby přepravce
  • Číselné části Čísla podavatele z Nastavení prodeje a pohledávek
  • Čísla z Číselné řady nastavené v poli Expediční číslo přepravy z Nastavení služby přepravce
  • Kontrolní číslice (vypočtené dle metodou MODULO 11 dle technické dokumentace ČP)
  • Písmene z Čísla podavatele z Nastavení prodeje a pohledávek
• Pokud kterékoliv pole, z kterého se číslo skládá není vyplněno, zobrazí se chyba.
• Tato akce se zároveň automaticky spustí před spuštěním akce Sestavy -> Vytisknout štítek

Adresní štítek #

Pro tisk štítků se využívá modul AE046 Integrace tiskáren na štítky.

Při první instalaci rozšíření se automaticky založí adresní štítek. Výchozí kód štítku je ČESKÁ POŠTA ADRESNÍ. Výchozí štítek je možné možné manuálně vytvořit naplánováním úlohy pro proceduru 80012 "ART AA CP Install". Text vyplněný do pole Řetězec parametrů se použije jako Kód šablony.

Na výchozím štítku se zobrazují informace:

• Z Karty Balíku
  • Název
  • Adresa
  • Adresa 2
  • Město
  • PSČ
  • Telefonní číslo
  • Skutečná hmotnost
  • Platba dobírkou (Doklad/Bezdoklad)
  • Částka dobírkou
  • ID Dopravce (Číslo balíku)
  • Velikostní kategorie
• Z Karty Lokace vybrané na Kartě Balíku
  • Název
  • Adresa
  • Adresa 2
  • Město
  • PSČ
  • Telefonní číslo
• Z Nastavení služby přepravce pro Službu přepravce vybranou na Kartě balíku
  • PSČ podací pošty

Rozměry výchozího štítku jsou 101x127mm a štítek je vytvořen v rozlišení 8dpmm.

Nastavení #

Nastavení prodeje a pohledávek #

V Nastavení prodeje a pohledávek jsou v nové kategorii Obecné -> Česká pošta k dispozici pole:

• Číslo podavatele - Určuje technické číslo podavatele, které zákazníkovi přiřadila Česká pošta. Číslo musí být dle Technické dokumentace pro podání zásilek smluvním podavatelem v jednom z následujícíh formátů:
  • Pro podavatele s ročním objemem podání nad 1 000 000 zásilek
    • Fxx, Exx, Pxx
  • Pro podavatele s ročním objemem podání do 1 000 000 zásilek
    • Uxxx, Txxx
  • Pro podavatele s ročním objemem podání do 100 000 zásilek
    • Cxxxx, Bxxxx
  • Pro podavatele s ročním objemem podání do 10 000 zásilek
    • Mxxxxx, Lxxxxx
• Exportovat CSV pro Českou poštu - aktivuje automatický export při zapsání balíku

Nastavení služby přepravce #

V Nastavení služby přepravce které je dostupné z jednotlivých Služeb přepravce je nyní možné v poli Typ přepravy vybrat hodnotu "Česká pošta". Po vybrání této hodnoty se na kartě dále zobrazí pole:

• Označení zásilky - Kód o maximálně dvou znacích, dle kterého se poté generuje kód balíku (ID dopravce na Kartě balíku)
• PSČ podací pošty - Zobrauje se na adresním štítku

API Implementace (125556, 125751) #

Popis #

Tato část zahrnuje informace o odesílání balíků České poště přes jejich API služby.

Implementované služby zahrnují sendParcels (Odesílání balíků České poště) a consignmentSK (Odesílání balíků Slovenské poště prostřednictvím České pošty).

Povinná data a nastavení před používáním #

Před používáním a nastavením služeb v Business Central je nejprve třeba:

• Založit účet Pošta Online
• Kontaktovat obchodního manažera pro váš region, který vám přidělí customerID (DŮLEŽITÉ), a se kterým aktivujete B2B profil a získáte potřebné údaje pro API jako ID CČK, API token a API klíč.
• Pro službu sendParcels je třeba si s Poštou dohodnout typy služeb, např. Balík do ruky, Balík na poštu, Balík na balíkovnu.
• Pro službu consignmentSK je také třeba s Českou poštou zajistit číselnou řadu pro čárové kódy zásilek. (Česká pošta tuto číselnou řadu přiřazuje na požádání do cca týdne).

Služba sendParcels (125556) #

Přepravce #

Aby BC přepravce používal službu sendParcels, je třeba mu v poli Implementace přepravce zvolit možnost Česká pošta (API).

Služby přepravce #

Pro službu sendParcels je nutné nastavit a využívat alespoň jeden typ služby, tj např. Balík do ruky. Aby služba fungovala, je třeba vyplnit pole ID služby přepravce.

Modul aktuálně podporuje následující typy služeb: Název | ID služby přepravce --------|------------- Balík do ruky | DR Balík na poštu | NP Balík na balíkovnu | NB

Služba consignmentSK (125751) #

Přepravce #

Aby BC přepravce používal službu consignmentSK, je třeba mu v poli Implementace přepravce zvolit možnost Česká pošta (SK API).

Služby přepravce #

Pro správné fungování je třeba si založit libovolně pojemnovanou službu přepravce, např CONSIGNMENT, která se pak vyplní v nastavení.

Nastavení přepravce #

Pro obě služby a pro každý typ služby je nutné založit zvlášť Nastavení přepravce. V nastavení přepravce se po správném výběru implementace zpřístupní sekce Česká pošta:

• Označení zásilky - pro sendParcels vyplnit hodnotu z ID služby přepravce, pro consignmentSK se nevyplňuje.
• Číslo podavatele - customerID, nasmlouvané s obchodním manažerem
• PSČ podací pošty - nasmlouvané s obchodním manažerem
• API Token - vygeneruje se v B2B profilu
• API Klíč - B2B profilu
• API URI
  • pro službu sendParcels
    • https://b2b.postaonline.cz:444/restservices/ZSKService/v1/
    • Zdroj : Technická dokumentace B2B-ZSKService
  • pro službu consignmentSK
    • https://b2b.postaonline.cz:444/restservices/CSGService/v1/
    • Zdroj : Technická dokumentace B2B-CSGService
• ID CČK - nasmlouvané s obchodním manažerem ČP
• Číslo podacího místa - identifikace adresy odesílatele, adresa odesílatele se posílá přes API předem, aby se zjednodušil proces. Před používáním API je nutné ho založit, viz níže.

Dále je třeba věnovat zvýšenou pozornost sekci Externí informace. Je NUTNÉ mít pro služby správně vyplněné číselné řady, jsou totiž podstatné pro tvorbu kódů balíků.

• Pro službu sendParcels a všechny její typy služeb, je třeba mít zvolené řadu/řady o délce přesně 6 čísel, tj počáteční číslo např. 000001. Systém poté sám generuje kód balíku, proces probíhá stejně jako pro CSV export, více informací je tedy sepsáno již výše, v sekci Generování kódu balíku (ID dopravce).
• Pro službu consignmentSK řadu přiděluje sama Česká pošta, avšak i tak dobré ověřit, že se skládá z 2 počátečních písmen a pokračuje přesně 8 číslicemi.

Založení podacího místa #

Pro fungování API je třeba si založit podací místo, později identifikované pomocí pole Číslo podacího místa. K tomu slouží akce Založení nového podacího místa v Nastavení přepravce. Číslo podacího místa je možné zkopírovat, vložit a používat i v dalších nastaveních přepravce, není nutné pro každé nastavení zakládat nové.

DŮLEŽITÉ pro založení podacího místa:

• V případě Výchozí odesílatel = Lokace, musí být ve vybrané lokaci vyplněno:
  • Název lokace
  • Adresa
  • Město
  • Kód země/oblasti
  • PSČ
  • Nepovinné - Telefoní číslo, Email - pro avízo SMS/Emailem
• V případě Výchozí odesílatel = Nastavení přepravce, musí být v sekci Adresa & kontakt odesílatele vyplněno :
  • Název odesílatele
  • Adresa odesílatele
  • Město odesílatele
  • Kód země/oblasti odesílatele
  • PSČ
  • Nepovinné - Telefoní číslo, Email - pro avízo SMS/Emailem
• V obou případech MUSÍ být v informacích o společnosti správně nastavený bankovní účet ve formátu ČÍSLO_ÚČTU/KÓD_BANKY nebo PŘEDČÍSLÍ-ČÍSLO_ÚČTU/KÓD_BANKY.

Dokumentaci k zakládání podacího místa lze nalézt v odkazech na dokumentaci služeb.

Používání služeb #

Při změně stavu uzávěrky přepravních jednotek s přepravcem, jenž podporuje službu sendParcels či consignmentSK, se data ihned odešlou přes API. Poté je nutné nastavit úlohu, která se pokusí stáhnout data o zpracování o všech odeslaných balících. Úloha bude pouštět CU 80144 "ART AA CP Run GET Job", která je společná pro službu sendParcels a consignmentSK.

Výsledek odesílání dat a dotazování na zpracování, se propisuje do položek protokolu odeslaných dat (v sekci Související). Jakékoliv chyby se zaznamenají právě zde.

Výsledek operace může být dvojího typu - INFO nebo CHYBA.

• INFO představuje upozornění na např. změněnou adresu nebo drobné nepřesnosti, které však nepředstavují větší komplikaci pro odeslání nebo zpracování dat.
• CHYBA je při odesílání informace o chybě, která nedovoluje data odeslat, u kontroly zpracování se pak jedná například o špatný formát dat, neplatnou hmotnost zásilky, neplatnou adresu, apod.

Dostupný seznam chyb je k vidění v dokumentaci, v sekci Přehled chybových hlášek.

Adresní štítek (132186) #

Při první instalaci rozšíření se pro službu ConsignmentSK automaticky založí výchozí adresní štítek SP - Expres Kurýr.

Příklad štítku

V trasách přepravce je nutné správně vyplnit CP Název Uzlu, pro správný tisk štítků (= CP Nodename, v případě neexistenci trasy se parametr do štítku vůbec nevytiskne).

Informace pro vývojáře #

Dokumentace #

Služba sendParcels #

Přehledová dokumentace B2B-ZSKService

Technická dokumentace B2B-ZSKService

Služba consignmentSK #

Technická dokumentace B2B-CSGService

Implementace modulu AE056 #

Služba sendParcels je implementována v CU CzechPostAPIImp, služba consignmentSK pak v CU CPSKAPIImp. Obě služby jsou implementací interface Shipping Agent Provider z modulu AA-AE056. Jelikož velká většina funkcí je stejná, jsou společné funkce shrnuty v CU CPAPIImplMgt, včetně funkcí pro autorizaci requestů.

API Requesty #

POST pro sendParcels je zpracován v CU CPPOSTsendParcels, POST pro consignmentSK pak v CU CPPOSTconsingmentSK (nejedná se o překlep, služba consignmentSK je poštou v requestu takto špatně pojmenována).

V Nastavení přepravce je možné určit časový rozdíl pro API, pokud se currentdatetime() liší od skutečného času. Lze tak řešit chyby při odesílání requestů, pokud "čas nesedí".

GET je pro obě služby stejný. Hromadně jej volá CU CPRunGETJob, pro jednotlivý záznam se spouští CU CPGETSendParcels.

Autentikace a nastavení služby pro produkci #

Zde na oficiálních stránkách české pošty, se lze přihlásit na zákaznický portál pro firmy, a spravovat nastavení B2B služeb. Jsou zde k dispozici veškteré údaje, tzn. apiToken, secretKey apod.

Některé informace jako například customer ID, se smlouvají s poštou napřímo, je nutné je tedy získat přímo od zákazníka.

Podrobné informace v sekci Povinná data a nastavení před používáním.

Autentikace pro testování přes platformu postman #

ZDE k datu 2024-06-25 funkční postman kolekce k testování. NEOBSAHUJE údaje jako apiToken nebo secretKey.

V BC je autentikace kompletně zpracovávána prostřednictvím funkce InitRequestAndSetAuth v codeunit 80151 "ART AA CP API Impl. Mgt.". Pro testování je však vhodné použít například nástroj postman. Tato sekce popisuje, jak si správně nastavit hlavičky autentikace a prerequestscript k testování.

Tento odkaz obsahuje testovací účty pro B2B-ZSKService & B2B-CSGService. Vyzkoušel jsem pro obě služby, funkční k datu 2024-06-25. Zde lze nalézt potřebný apiToken, secretKey pro testování.

Náledující číselnou řadu lze s prvním testovacím účtem použít pro testování služby consignmentSK: EV80700500 až EV80700600.

Česká pošta používá basic auth s vlastním šifrováním, proto je třeba si v postmanovi nastavit prerequestscript, který vytvoří požadované autentikační hlavičky. Prerequest z dokumentace je zdá se nefunkční, zde je příklad funkčního (k datu 2024-06-25):

const apiToken = ""; // String (z dokumentace nebo ČP B2B portálu)
const secret = ""; // String (z dokumentace nebo ČP B2B portálu)

// Create random UUID
var uuid = require('uuid');
const nonce = uuid.v4() // Náhodný GUID nebo UUID (BC si pokaždé generuje nový GUID)

var moment = require('moment');
var timestamp = moment().unix();
var payload = pm.request.body.toString();
var cryptojs = require('crypto-js')
var authContent = cryptojs.SHA256(payload).toString();
var signature = cryptojs.HmacSHA256(authContent + ';' + timestamp + ';' + nonce, secret);
var signature64 = cryptojs.enc.Base64.stringify(signature);

var authorization = 'CP-HMAC-SHA256' + ' nonce=' + JSON.stringify(nonce) + ' signature=' + JSON.stringify(signature64);

pm.globals.set('Api-Token',apiToken);
pm.globals.set('Authorization-Timestamp',timestamp);
pm.globals.set('Authorization-content-SHA256',authContent);
pm.globals.set('Authorization',authorization);

Je NUTNÉ si založit a správně pojmenovat hlavičky pro autentikaci. Zde příklad jak by to mělo vypadat (via postman headers bulk edit):

Api-Token:{{Api-Token}}
Authorization-Timestamp:{{Authorization-Timestamp}}
Authorization-content-SHA256:{{Authorization-content-SHA256}}
Authorization:{{Authorization}}