n8n-nodes-novaposhta

This is an n8n community node that integrates with the Nova Poshta API.

Nova Poshta is a Ukrainian logistics and delivery service. This node lets you manage counterparties, addresses, shipments, registries, scan sheets, tracking, and reference data from n8n workflows.

Installation
Features
Operations
Credentials
Compatibility
Usage
Field notes
Development
Troubleshooting
Resources

Installation

Follow the installation guide in the n8n community nodes documentation.

Features

• Full Nova Poshta JSON API integration via n8n credentials
• Multiple resources in one node (shipments, addresses, counterparties, tracking, registries)
• Consistent error handling and response parsing
• Uses the official API base URL: https://api.novaposhta.ua/v2.0/json/

Operations

The node exposes these resources and operations:

• Additional Service
  • Check Possibility Create Return
  • Get Return Reasons
  • Get Return Reasons Subtypes
  • Order Cargo Return
  • Get Return Orders List
  • Check Possibility Change EW
  • Save
  • Delete
• Address
  • Search Settlements
  • Get Warehouses
  • Get Streets
  • Save Address
• Common
  • Get Cargo Types
  • Get Cargo Description List
  • Get Payment Forms
  • Get Types of Payers
  • Get Types of Payers for Redelivery
  • Get Package Types
  • Get Tires Wheels List
  • Get Pallets List
  • Get Service Types
  • Get Ownership Forms List
  • Get Time Intervals
  • Get Backward Delivery Cargo Types
• Contact Person
  • Create
  • Update
  • Delete
  • Get
• Counterparty
  • Create
  • Get
  • Update
  • Delete
• Document
  • Create
  • Get
  • Delete
  • Generate Report
• Loyalty
  • Get Card Info
  • Get Card Balance
• Payment
  • Get Cards
  • Get Control
• Registry
  • Create
  • Update
  • Delete
  • Get
• Scan Sheet
  • Insert Documents
  • Get Scan Sheet
  • Delete Scan Sheet
  • Remove Documents
  • Get Scan Sheet List
• Tracking
  • Track

Credentials

This node requires a Nova Poshta API key.

1. Create an account and generate an API key in the Nova Poshta personal cabinet.
2. In n8n, create a credential of type "Nova Poshta API" and paste the key.

Credential test request calls Common.getPalletsList to verify access.

Compatibility

• Uses n8n Nodes API version 1.
• Compatible with n8n 1.x. Tested with n8n 1.82.0.

Usage

Typical flow for creating a shipment:

1. Create or retrieve counterparties (sender/recipient).
2. Create contact persons for each counterparty.
3. Create or fetch addresses/warehouses.
4. Create a document (shipment).
5. Track the shipment with the Tracking resource.

Field notes

• Phone numbers use the 380XXXXXXXXX format in the node UI.
• Tracking supports a comma-separated list of numbers (up to 100).
• Many operations require reference IDs returned by earlier calls (for example counterpartyRef, contactPersonRef, documentRefs).
• Date fields use ISO 8601 values (n8n dateTime input).

Development

Prerequisites:

• Node.js >= 18.10
• pnpm >= 9.1

Common commands:

pnpm install
pnpm build
pnpm dev
pnpm lint
pnpm lintfix
pnpm format

To test the node locally in n8n, follow the official guide: Run your node locally.

Troubleshooting

• If requests fail, verify the API key and that the key has access to the required methods.
• For "resource not supported" errors, double-check the selected resource and operation in the node parameters.
• The API returns success: false with error messages; these are surfaced in the node error output.

Resources

• n8n community nodes documentation
• Nova Poshta API documentation
• Project repository

License

MIT