npm package: @net.christianto/n8n-nodes-shlink
Description: This is an n8n community node. It lets you use [Shlink](https://shlink.io/) in your n8n workflows.
Author: Gunawan "chez" Christianto
Latest version: 0.0.5

# @net.christianto/n8n-nodes-shlink

This is an n8n community node. It lets you use [Shlink](https://shlink.io/) in your n8n workflows.

[n8n](https://n8n.io/) is a [fair-code
licensed](https://docs.n8n.io/reference/license/) workflow automation platform.

## Installation

Follow these steps to install the node from the n8n UI:

1. Go to **Settings > Community Nodes**.
2. Select **Install**.
3. Enter `@net.christianto/n8n-nodes-shlink` in the **Enter npm package name**
   field.
4. Agree to the risks by selecting **I understand the risks of installing
   unverified code from a public source.**
5. Select **Install**.

## Getting Started

### Quick Setup

To start using the Shlink node in n8n:

1. **Add Credentials**
   - In n8n, go to **Settings > Credentials**
   - Search for "Shlink API Key"
   - Enter your Shlink instance URL and API key
   - Save the credentials

2. **Create a Workflow**
   - Add a new node to your workflow
   - Search for "Shlink" and select the Shlink node
   - Select your credentials
   - Choose an operation from the available options

3. **Configure and Execute**
   - Select the operation you want to perform (e.g., Create Short URL)
   - Fill in the required parameters
   - Run the workflow

### Basic Example Workflow

A typical workflow might include:

- **Trigger**: Webhook or scheduled event
- **Shlink Node**: Create a short URL or get statistics
- **Output**: Store results or send notifications

For detailed configuration of each operation, see the [Operations](#operations) section below.

## Operations

This node supports the following operations. For detailed API specifications, see the [Shlink API documentation](https://api-spec.shlink.io/).

### Manage Short URLs

Create, manage, and track shortened URLs on your Shlink instance:

- **Create**: Generate a new short URL from a long URL. You can customize the short code, set expiration dates, and configure limits on visits.
- **List**: Retrieve all short URLs configured on your Shlink instance. Supports filtering and pagination.
- **Get**: Fetch detailed information about a specific short URL, including visit statistics and configuration details.
- **Update**: Modify settings of an existing short URL, such as updating the target long URL, tags, or metadata.
- **Delete**: Remove a short URL from your Shlink instance.

### Manage Domains

Configure and manage domains used by your Shlink instance:

- **List**: View all domains configured on your Shlink instance.
- **Set Domain Redirect**: Configure where users are redirected when they access your domain without a specific short URL.
- **Update Domain Redirect**: Modify existing domain redirect rules.

Domains are essential for hosting multiple short URL bases on your Shlink instance.

### Manage Tags

Organize and track your short URLs using tags:

- **List**: Get all tags used across your short URLs.
- **Rename**: Change a tag name, which updates all associated short URLs.
- **Delete**: Remove a tag from your instance.
- **Statistics**: Get detailed statistics for a specific tag, including the number of associated short URLs and visit counts.

Tags help categorize and manage your short URLs efficiently.

### Track Visits

Monitor and analyze visit data for your short URLs:

- **Get Global Statistics**: View overall statistics for your Shlink instance, including total visits and URLs created.
- **Get URL Visits**: Retrieve visit data for a specific short URL with detailed metrics.
- **Get Tag Visits**: Get visit statistics aggregated by tag.
- **Get Domain Visits**: View visit data for a specific domain.
- **Orphan Visits - List**: View "orphan" visits (visits to invalid or deleted short URLs).
- **Orphan Visits - Delete**: Remove orphan visit records.
- **Delete URL Visit History**: Clear visit history for a specific short URL.

Visit tracking helps you understand how your short URLs are being used.

## Credentials

You'll need to provide an Instance URL and API Key to authenticate with your
Shlink instance. The instance URL should be the domain of your Shlink instance.
The API Key can be generated via CLI, please see the documentation in the
following link:

- Authentication:  
  https://shlink.io/documentation/api-docs/authentication/

- API Key Role:  
  https://shlink.io/documentation/api-docs/api-key-roles/

Once created, you can add the credentials to n8n by finding the Credentials
settings, then find "Shlink API Key".

![Shlink API Key Window](./.gitlab/ss-credential.png)

## Compatibility

This node currently tested against:
- **n8n** 1.101.2
- **Shlink Server** v4.2.0  
  with REST API version v3.

## Troubleshooting

### Authentication Issues

- **Invalid API Key**: Verify that your API key is correct and has the necessary permissions. Refer to [Shlink API Key Roles](https://shlink.io/documentation/api-docs/api-key-roles/) for role configuration.
- **Connection Refused**: Ensure your Shlink instance URL is correct and the server is running and accessible from your n8n instance.
- **Unauthorized Error**: Check that your API key hasn't expired or been revoked in your Shlink instance.

### API Errors

For detailed information about error responses from the Shlink API, see the [Shlink Error Management documentation](https://shlink.io/documentation/api-docs/error-management/).

Common error scenarios:
- **404 Not Found**: The requested short URL, domain, or tag doesn't exist.
- **400 Bad Request**: Invalid parameters were provided. Check the API documentation for required fields and formats.
- **409 Conflict**: The operation conflicts with existing data (e.g., duplicate short code).

### Troubleshooting Guide

For general troubleshooting steps and common issues with Shlink, see the [Shlink Troubleshooting Guide](https://shlink.io/documentation/troubleshooting/).

### Version Compatibility

This node is tested with Shlink Server v4.2.0. If you're using a different version:
- Check the [Shlink Release Notes](https://github.com/shlinkio/shlink/releases) for API changes
- Some operations may not be available in older Shlink versions
- Consider upgrading to a compatible version if you encounter "Method Not Allowed" errors

### Getting Help

If you encounter issues not covered above:
1. Check the Shlink documentation links provided
2. Review the n8n [community nodes documentation](https://docs.n8n.io/integrations/#community-nodes)
3. Report issues in the [project repository](https://gitlab.com/net.christianto/n8n-nodes-shlink/-/issues)

## Resources

* [n8n community nodes
  documentation](https://docs.n8n.io/integrations/#community-nodes)
* https://shlink.io/

## Version history

Currently only one version that has been published so far. I'll update this
section if I release a new version.

For the time being, you can check our [Release
page](https://gitlab.com/net.christianto/n8n-nodes-shlink/-/releases).