Nova Poshta

Nova Poshta is Ukraine's largest parcel carrier. This adapter calls its public API 2.0, a single JSON endpoint (https://api.novaposhta.ua/v2.0/json/) where every call names a model and a method in the request body.

Getting credentials Tracking, city and branch search, price and delivery-date calculation work without a key. Only nova_poshta_list_shipments (your own waybills) needs one. To create it, sign in to the Nova Poshta business account at new.novaposhta.ua, open Settings → Security and click Create key, accept the API terms and copy the key into NOVA_POSHTA_API_KEY. A key is valid for one year; an expired key makes every call fail with "API key expired", including the ones that work without a key, so renew it or clear the variable.

Workflow

1. nova_poshta_track_parcels takes up to 100 waybill (TTN) numbers. Add the sender's or recipient's phone to a number to get the full record (recipient, address, payment); without it Nova Poshta returns only the status and a warning asking for the phone.
2. Resolve a city name with nova_poshta_search_settlements. Its DeliveryCity field is the city reference that nova_poshta_list_warehouses, nova_poshta_get_delivery_price and nova_poshta_get_delivery_date expect (Ref is the settlement, a different id).
3. Price and date need a service type: Warehouse = branch, Doors = address, Postomat = parcel locker.

Formats and gotchas

• Dates are DD.MM.YYYY, e.g. 07.10.2026. Weight is in kg, declared value (cost) in UAH.
• Nova Poshta answers HTTP 200 even when a call fails: always read success. When it is false, errors (and errorCodes) say why, e.g. "Weight is invalid". warnings can carry useful notes on a successful call.
• A tracking number that does not exist still returns success with Status "Номер не знайдено" (number not found) and StatusCode 3.
• Texts come in Ukrainian; many records also carry a Russian DescriptionRu.

Pagination and limits: list methods take page (from 1) and limit; info.totalCount gives the total where Nova Poshta reports it. No quota is published; keep pages small and avoid bulk loops.

Cloud reachability: api.novaposhta.ua is public over HTTPS, so AnythingMCP Cloud and self-hosted installs reach it directly.