n8n-nodes-ship24 1.0.2

package/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Ship24
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# n8n-nodes-ship24
+
+Automate global shipment tracking inside n8n using the Ship24 API.
+
+The Ship24 node enables production-grade shipment tracking workflows
+including bulk tracker creation, structured result retrieval, multi-item
+processing, and robust error handling.
+
+------------------------------------------------------------------------
+
+## About Ship24
+
+Ship24 is a global shipment tracking API supporting 1500+ couriers and
+marketplaces worldwide.
+
+This node allows n8n users to:
+
+-   Create shipment trackers
+-   Retrieve tracking results
+-   Update tracker subscription status
+-   Process bulk shipments
+-   Automate delivery workflows at scale
+
+------------------------------------------------------------------------
+
+## Features
+
+-   Single tracker creation
+-   Bulk tracker creation (automatic chunking up to 100 per request)
+-   Create and immediately fetch tracking results
+-   Retrieve results by tracking number
+-   Retrieve results by tracker ID
+-   Update tracker subscription status
+-   Full n8n multi-item support
+-   Structured per-item error handling
+-   `continueOnFail` support
+-   Utility mode for advanced API access
+
+------------------------------------------------------------------------
+
+## Installation
+
+### Community Node Installation
+
+1.  Open n8n.
+2.  Go to **Settings → Community Nodes**.
+3.  Click **Install**.
+4.  Enter:
+
+```{=html}
+<!-- -->
+```
+    n8n-nodes-ship24
+
+5.  Restart n8n if required.
+
+------------------------------------------------------------------------
+
+## Credentials Setup
+
+This node requires a Ship24 API key.
+
+1.  In n8n, create new credentials.
+2.  Select **Ship24 API**.
+3.  Enter your API key.
+4.  Save.
+
+![Credentials Setup](docs/images/credentials-setup.png)
+
+------------------------------------------------------------------------
+
+## Node Overview
+
+![Node Overview](docs/images/node-overview.png)
+
+The node provides two resources:
+
+-   **Tracker**
+-   **Utility**
+
+------------------------------------------------------------------------
+
+# Tracker Resource
+
+## Create
+
+Create shipment trackers.
+
+Supports:
+
+-   Single per item
+-   Bulk mode (up to 100 tracking numbers per API request)
+
+![Create operation](docs/images/create-operation.png)
+
+### Bulk Mode Behaviour
+
+If more than 100 items are provided, the node automatically splits them
+into multiple API calls.
+
+  Input Items     API Calls
+  ------------- -----------
+  80                      1
+  150                     2
+  250                     3
+
+Each input item returns exactly one output item.
+
+![Bulk Mode](docs/images/bulk-mode.png)
+
+------------------------------------------------------------------------
+
+## Create and Get Results
+
+Creates a tracker and immediately retrieves tracking results.
+
+Useful when:
+
+-   You need tracking data immediately
+-   You want simplified output for automation workflows
+
+![Create and Get Results](docs/images/create-tracker-get-results.png)
+
+------------------------------------------------------------------------
+
+## Update
+
+Update tracker subscription status (`isSubscribed` only).
+
+-   Requires a valid `trackerId` (UUID)
+-   Performs UUID validation before the API call
+
+![Update Tracker](docs/images/update-tracker.png)
+
+------------------------------------------------------------------------
+
+## Get Results
+
+Retrieve tracking data:
+
+-   By tracking number
+-   By tracker ID
+
+![Get Results](docs/images/get-results-by-trackerId.png)
+
+------------------------------------------------------------------------
+
+# Utility Resource
+
+The Utility resource allows advanced API access.
+
+You can:
+
+-   Define HTTP method
+-   Define path
+-   Provide custom request body
+-   Provide query parameters
+
+![Utility Resource](docs/images/utility-call.png)
+
+------------------------------------------------------------------------
+
+## Response Modes
+
+### Raw Mode
+
+This node returns the full Ship24 API response (raw mode).
+
+------------------------------------------------------------------------
+
+## Multi-Item Behaviour
+
+This node fully supports n8n multi-item processing:
+
+-   One output item per input item
+-   Bulk operations preserve input-to-output mapping
+-   No silent drops
+-   Large workflows (50+ items) supported
+
+------------------------------------------------------------------------
+
+## Error Handling
+
+The node includes structured error handling for:
+
+-   401 Unauthorized
+-   404 Not Found
+-   429 Rate limit
+-   Invalid UUID format
+-   Empty tracking number
+-   Bulk mapping failures
+
+With `continueOnFail` enabled, per-item failures return structured
+objects:
+
+``` json
+{
+  "success": false,
+  "error": {
+    "type": "request_error",
+    "message": "..."
+  }
+}
+```
+
+This allows resilient workflow design without unexpected crashes.
+
+------------------------------------------------------------------------
+
+## Performance Notes
+
+-   Bulk mode automatically chunks at 100 items per API request.
+-   Large workflows are processed sequentially per chunk.
+
+------------------------------------------------------------------------
+
+## Development
+
+### Build
+
+``` bash
+npm run build
+```
+
+### Lint
+
+``` bash
+npm run lint
+```
+
+### Local package test
+
+``` bash
+npm pack
+```
+
+------------------------------------------------------------------------
+
+## License
+
+MIT

package/dist/credentials/Ship24Api.credentials.d.ts

@@ -0,0 +1,15 @@
+import type { ICredentialType, INodeProperties, Icon, IHttpRequestMethods } from 'n8n-workflow';
+export declare class Ship24Api implements ICredentialType {
+    name: string;
+    displayName: string;
+    icon: Icon;
+    documentationUrl: string;
+    test: {
+        request: {
+            baseURL: string;
+            url: string;
+            method: IHttpRequestMethods;
+        };
+    };
+    properties: INodeProperties[];
+}

package/dist/credentials/Ship24Api.credentials.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ship24Api = void 0;
+class Ship24Api {
+    constructor() {
+        this.name = 'ship24Api';
+        this.displayName = 'Ship24 API';
+        this.icon = 'file:ship24.svg';
+        this.documentationUrl = 'https://docs.ship24.com';
+        this.test = {
+            request: {
+                baseURL: 'https://api.ship24.com/public/v1',
+                url: '/couriers',
+                method: 'GET',
+            },
+        };
+        this.properties = [
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Your Ship24 API key. It will be sent as a Bearer token in the Authorization header.',
+            },
+        ];
+    }
+}
+exports.Ship24Api = Ship24Api;
+//# sourceMappingURL=Ship24Api.credentials.js.map

package/dist/credentials/Ship24Api.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ship24Api.credentials.js","sourceRoot":"","sources":["../../credentials/Ship24Api.credentials.ts"],"names":[],"mappings":";;;AAEA,MAAa,SAAS;IAAtB;QACC,SAAI,GAAG,WAAW,CAAC;QACnB,gBAAW,GAAG,YAAY,CAAC;QAC3B,SAAI,GAAS,iBAAiB,CAAC;QAC/B,qBAAgB,GAAG,yBAAyB,CAAC;QAE7C,SAAI,GAAG;YACN,OAAO,EAAE;gBACR,OAAO,EAAE,kCAAkC;gBAC3C,GAAG,EAAE,WAAW;gBAChB,MAAM,EAAE,KAA4B;aACpC;SACD,CAAC;QAEF,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,qFAAqF;aAClG;SACD,CAAC;IACH,CAAC;CAAA;AAzBD,8BAyBC"}

package/dist/credentials/ship24.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="131" height="37" viewBox="0 0 131 37">
+    <g fill="none" fill-rule="evenodd">
+        <path fill="#2A367F" d="M52.043 24.327c.423-1.167-.048-2.072-1.415-2.713l-2.341-1.053c-3.263-1.603-4.573-3.783-3.93-6.542.285-1.26.906-2.385 1.863-3.371.957-.988 2.178-1.754 3.665-2.302a12.99 12.99 0 0 1 4.7-.791c2.206.04 3.876.692 5.01 1.953.999 1.112 1.41 2.558 1.231 4.338a.798.798 0 0 1-.784.731h-3.7c-.435 0-.756-.372-.747-.81.011-.502-.085-.927-.29-1.275-.305-.522-.907-.793-1.805-.814a4.57 4.57 0 0 0-2.442.62c-.75.434-1.249 1.018-1.496 1.752-.371 1.034.246 1.88 1.85 2.542 1.604.661 2.755 1.23 3.454 1.706 2.197 1.477 3.007 3.471 2.426 5.983a7.404 7.404 0 0 1-1.827 3.426c-.915.981-2.081 1.741-3.499 2.279-1.419.537-2.95.796-4.598.774-1.205-.02-2.295-.212-3.268-.573-.974-.362-1.77-.888-2.391-1.581-1.133-1.257-1.576-2.87-1.324-4.84a.774.774 0 0 1 .775-.661l3.69.01c.467.002.811.412.774.881-.058.733.06 1.316.352 1.75.401.594 1.197.891 2.385.891.882 0 1.65-.203 2.31-.612a3.202 3.202 0 0 0 1.372-1.698M67.281 13.028c-.251.691.474 1.296 1.124.959.858-.445 1.736-.662 2.634-.65 1.663.04 2.796.656 3.399 1.844.602 1.189.617 2.802.046 4.837l-3.31 9.88a.785.785 0 0 1-.743.537h-3.402a.79.79 0 0 1-.742-1.044l3.168-9.447c.101-.352.167-.683.2-.994.102-1.024-.371-1.552-1.421-1.583-.84-.018-1.644.267-2.412.857a.815.815 0 0 0-.267.378l-3.908 11.302a.784.784 0 0 1-.74.53h-3.4a.79.79 0 0 1-.741-1.048l7.607-22.23a.784.784 0 0 1 .74-.532h3.377a.79.79 0 0 1 .735 1.063l-1.944 5.34zM79.694 9.43c.107-.754.478-1.384 1.113-1.89.634-.507 1.34-.76 2.12-.76.788 0 1.408.227 1.858.682.451.455.624 1.05.52 1.783-.109.765-.478 1.397-1.106 1.898a3.318 3.318 0 0 1-2.126.752c-.769 0-1.384-.225-1.846-.674-.46-.45-.639-1.047-.533-1.79m-2.39 21.004h-3.415a.79.79 0 0 1-.74-1.049l5.198-15.19a.784.784 0 0 1 .74-.533h3.415a.79.79 0 0 1 .74 1.048l-5.198 15.191a.784.784 0 0 1-.74.533M92.978 19.987c.237-1.705-.188-2.573-1.28-2.604-1.002-.06-1.92.335-2.753 1.181a.841.841 0 0 0-.19.31l-2.173 6.247a.765.765 0 0 0-.022.469c.228.741.838 1.121 1.83 1.14 1.787.03 3.153-1.524 4.096-4.666.261-.992.425-1.685.492-2.077m4.565 2.077c-.513 1.757-1.235 3.32-2.164 4.69-.93 1.368-1.965 2.387-3.11 3.053-1.142.667-2.346.984-3.612.953-.99-.028-1.81-.308-2.455-.84a.776.776 0 0 0-1.23.335l-2.208 6.109a.784.784 0 0 1-.736.52h-3.41a.79.79 0 0 1-.741-1.049l7.4-21.642a.784.784 0 0 1 .74-.532l3.024-.01a.79.79 0 0 1 .746 1.041l-.184.551c1.338-1.301 2.762-1.933 4.271-1.89 1.615.02 2.78.603 3.492 1.75.712 1.147.93 2.714.654 4.698-.089.64-.247 1.395-.477 2.263"/>
+        <path fill="#FBAF17" d="M110.323 30.435H96.8a.79.79 0 0 1-.745-1.036l.757-2.336a.791.791 0 0 1 .255-.372l9.046-7.309 1.278-1.1c2.006-1.736 3.068-3.375 3.186-4.914.091-1.199-.42-1.814-1.53-1.845-.787-.02-1.51.302-2.172.969-.55.555-.982 1.252-1.293 2.091a.776.776 0 0 1-.716.524l-3.427.021a.794.794 0 0 1-.749-1.06 9.442 9.442 0 0 1 1.624-2.816 10.196 10.196 0 0 1 3.549-2.752c1.399-.661 2.824-.986 4.277-.977 2.176.043 3.765.639 4.768 1.791 1.003 1.152 1.262 2.711.774 4.674-.289 1.158-.856 2.284-1.703 3.38-.848 1.095-2.004 2.247-3.47 3.456l-2.705 2.17-2.381 1.989c-.565.471-.236 1.396.497 1.399l5.207.018a.79.79 0 0 1 .741 1.038l-.8 2.453a.784.784 0 0 1-.745.544"/>
+        <path fill="#FBAF17" d="M118.385 21.59l2.444.02a.784.784 0 0 0 .742-.519l2.043-5.627c.067-.186-.168-.33-.3-.185l-5.191 5.703a.363.363 0 0 0 .262.608m9.152.024a.79.79 0 0 1 .741 1.048l-.836 2.45a.784.784 0 0 1-.741.533h-1.082a.784.784 0 0 0-.74.532l-1.28 3.726a.784.784 0 0 1-.74.531h-3.398a.79.79 0 0 1-.74-1.048l.924-2.693a.79.79 0 0 0-.74-1.048h-6.271a.789.789 0 0 1-.76-.984l.565-2.257a.79.79 0 0 1 .19-.35L125.909 7.91l.018-.108 4.13.062a.79.79 0 0 1 .729 1.048l-3.988 11.653a.79.79 0 0 0 .74 1.048M24.047 8.573l7.628 3.296 2.296 14.532-8.19-2.911zM25.065 23.24l-13.693 3.076L9.49 11.457 23 7.823z"/>
+        <path fill="#FBAF17" d="M32.766 26.577l-12.04 3.536-8.19-3.172 13.78-3.304z"/>
+        <path fill="#2A367F" d="M26.013 22.879l-1.83-13.952 7.494 3.311 1.678 13.64-7.342-3zm-5.255 6.578l-7.605-2.607 11.774-2.643c.106-.029.194-.048.286-.068l.2-.045 6.558 2.623-11.213 2.74zm-11.104-17.6l13.365-3.3 1.903 14.508-13.48 3.025-1.788-14.232zm24.923 14.888L32.734 11.77a.533.533 0 0 0-.31-.42l-8.53-3.769-.045-.038a.537.537 0 0 0-.275-.115l-.05-.008-.046-.018a.536.536 0 0 0-.197-.043.52.52 0 0 0-.125.015l-14.27 3.524a.53.53 0 0 0-.395.581l1.922 15.296c.025.2.163.37.352.435l9.797 3.358c.04.014.082.023.125.027l.044.002a.531.531 0 0 0 .124-.015l13.324-3.257a.529.529 0 0 0 .398-.58z"/>
+        <path fill="#2A367F" d="M6.592 14.703c.083.104 2.095 2.56 6.23 3.45a4.98 4.98 0 0 0 1.373.174c.232 0 .475-.012.742-.035 1.228-.107 2.096-.837 2.446-2.057.312-1.092.367-2.242.172-3.621-.24-1.687-.994-2.912-2.309-3.745-1.815-1.15-3.834-1.94-5.616-2.636-2.452-.958-4.966-1.94-7.065-3.617-.1-.08-.213-.127-.344-.18a4.326 4.326 0 0 1-.207-.088l-.438-.203.213.762c.048.173.087.313.129.452.272.892.598 1.826 1.317 2.57 1.09 1.127 5.03 3.184 6.504 3.717.432.156.805.32 1.14.499.243.13.328.345.261.658-.064.3-.27.496-.54.514a3.247 3.247 0 0 1-.223.009c-.2 0-.356-.024-.478-.074a47.52 47.52 0 0 1-2.285-1.031c-.318-.151-3.174-1.572-3.52-1.776l-.557-.328.238.604.088.23c.052.137.092.242.14.343.27.558 1.033 1.165 2.335 1.856.181.096.366.185.55.273.178.085.355.17.528.261.36.19.536.576.41.898-.111.286-.297.42-.583.42-.09 0-.19-.014-.299-.04-.05-.012-.261-.084-.448-.148-.27-.092-.575-.197-.717-.233l-.42-.11.158.408c.264.68.628 1.292 1.082 1.816l-.007.008zm7.756 4.978c-1.766 0-2.902-.412-4.105-.849l-.195-.07a6.652 6.652 0 0 1-.885-.438c-1.429-.847-3.98-2.65-5.016-5.203a14.16 14.16 0 0 0-.08-.19c-.171-.403-.32-.75-.186-1.154.084-.25-.201-.517-.213-.528-.653-.6-1.063-1.395-1.33-2.576l-.13-.578c-.113-.507-.226-1.014-.35-1.518a1.75 1.75 0 0 0-.264-.566C.883 4.99.586 3.828.272 2.597L.208 2.35a7.172 7.172 0 0 1-.195-1.042A2.117 2.117 0 0 1 .05.611C.138.234.39 0 .709 0c.144 0 .298.05.445.142C1.677.473 2.2.827 2.706 1.17c.342.231.685.463 1.03.69C5.8 3.217 8.134 4.145 10.193 4.964l.606.24c1.763.696 3.586 1.415 5.204 2.482 1.684 1.109 2.648 2.675 2.946 4.79.052.364.09.74.125 1.102l.052.504c-.024 1.07-.204 2.03-.55 2.937-.657 1.715-1.977 2.61-3.925 2.659l-.303.003z"/>
+        <path fill="#FEFEFE" d="M6.592 14.703c.083.104 2.095 2.56 6.23 3.45a4.98 4.98 0 0 0 1.373.174c.232 0 .475-.012.742-.035 1.228-.107 2.096-.837 2.446-2.057.312-1.092.367-2.242.172-3.621-.24-1.687-.994-2.912-2.309-3.745-1.815-1.15-3.834-1.94-5.616-2.636-2.452-.958-4.966-1.94-7.065-3.617-.1-.08-.213-.127-.344-.18a4.326 4.326 0 0 1-.207-.088l-.438-.203.213.762c.048.173.087.313.129.452.272.892.598 1.826 1.317 2.57 1.09 1.127 5.03 3.184 6.504 3.717.432.156.805.32 1.14.499.243.13.328.345.261.658-.064.3-.27.496-.54.514a3.247 3.247 0 0 1-.223.009c-.2 0-.356-.024-.478-.074a47.52 47.52 0 0 1-2.285-1.031c-.318-.151-3.174-1.572-3.52-1.776l-.557-.328.238.604.088.23c.052.137.092.242.14.343.27.558 1.033 1.165 2.335 1.856.181.096.366.185.55.273.178.085.355.17.528.261.36.19.536.576.41.898-.111.286-.297.42-.583.42-.09 0-.19-.014-.299-.04-.05-.012-.261-.084-.448-.148-.27-.092-.575-.197-.717-.233l-.42-.11.158.408c.264.68.628 1.292 1.082 1.816l-.007.008z"/>
+    </g>
+</svg>

package/dist/nodes/Ship24/Ship24.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class Ship24 implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}