Link Management - Macondo Link Manager

Overview

The link management system is the core feature of Macondo Link Manager. Create shortened URLs, organize them by clients and campaigns, tag them for easy filtering, and generate QR codes for sharing.

Short URLs

Generate unique short codes automatically

QR Codes

Create scannable QR codes for any link

Organization

Associate links with clients and campaigns

Tagging

Categorize links with flexible tags

Creating Links

Create a new shortened link by providing the destination URL and organizational details.

API Endpoint

POST /links
Content-Type: application/json

{
  "originalUrl": "https://example.com/very-long-url",
  "clientId": "uuid-of-client",
  "campaignId": "uuid-of-campaign",  // optional
  "tags": ["social", "instagram"]     // optional
}

Required Fields

originalUrl

string

required

The full destination URL where users will be redirected. Must be a valid URL with protocol.

clientId

string (uuid)

required

The UUID of the client this link belongs to. Client must exist.

Optional Fields

campaignId

string (uuid)

The UUID of the campaign this link is associated with. Can be null for links not tied to a specific campaign.

Response

Successful creation returns a 201 Created status with the link object:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "originalUrl": "https://example.com/very-long-url",
  "shortCode": "a1B2c3",
  "userId": "user-uuid",
  "clientId": "client-uuid",
  "campaignId": "campaign-uuid",
  "createdAt": "2024-03-09T10:30:00Z",
  "updatedAt": "2024-03-09T10:30:00Z",
  "client": {
    "name": "Client Name"
  },
  "campaign": {
    "name": "Campaign Name"
  },
  "_count": {
    "clicks": 0
  },
  "tags": [
    { "id": "tag-uuid-1", "name": "social" },
    { "id": "tag-uuid-2", "name": "instagram" }
  ]
}

The shortCode is automatically generated using a cryptographically secure random string generator. The system ensures uniqueness by checking for collisions and regenerating if necessary.

Short Code Generation

Short codes are the unique identifiers that make up your shortened URLs.

Generation Algorithm

Character Set: alphanumeric (a-z, A-Z, 0-9)
Length: 6 characters
Possible Combinations: 62^6 = ~56 billion unique codes
Collision Handling: Automatic retry with new code if collision detected

URL Format

Shortened links follow this pattern:

https://yourdomain.com/{shortCode}

Example:

https://macondo.link/a1B2c3

Short codes are case-sensitive. a1B2c3 and A1b2C3 are different codes.

Listing Links

Retrieve all links with optional filtering capabilities.

API Endpoint

GET /links?clientId={uuid}&campaignId={uuid}&search={text}

Query Parameters

Parameter	Type	Description
`clientId`	UUID	Filter by specific client
`campaignId`	UUID	Filter by specific campaign
`search`	string	Search in URLs and metadata

Examples

curl https://api.macondo.link/links \
  -H "Cookie: macondo.token=YOUR_TOKEN"

Viewing Link Details

Get complete information about a specific link, including related data.

API Endpoint

GET /links/:id

Response

Returns detailed link information including:

Full link metadata
Associated client and campaign names
Applied tags
Total click count

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "originalUrl": "https://example.com/destination",
  "shortCode": "a1B2c3",
  "userId": "user-uuid",
  "clientId": "client-uuid",
  "campaignId": "campaign-uuid",
  "createdAt": "2024-03-09T10:30:00Z",
  "updatedAt": "2024-03-09T12:45:00Z",
  "client": {
    "name": "Acme Corporation"
  },
  "campaign": {
    "name": "Spring Sale 2024"
  },
  "_count": {
    "clicks": 1247
  },
  "tags": [
    { "id": "tag-uuid-1", "name": "social" },
    { "id": "tag-uuid-2", "name": "paid" }
  ]
}

Editing Links

Update link properties after creation.

API Endpoint

PUT /links/:id
Content-Type: application/json

{
  "originalUrl": "https://new-destination.com",
  "clientId": "different-client-uuid",
  "campaignId": null,
  "tags": ["updated", "tags"]
}

All fields are optional in the update request. Only provide the fields you want to change.

Updatable Fields

originalUrl

string

Change the destination URL. The short code remains the same.

clientId

string (uuid)

Move the link to a different client. The new client must exist.

campaignId

string (uuid) | null

Change the campaign association or set to null to remove campaign link.

Response

Returns 200 OK with the updated link object.

Deleting Links

Permanently remove a link and all associated click data.

API Endpoint

DELETE /links/:id

Response

Returns 204 No Content on successful deletion.

Deletion is permanent and cannot be undone. All click analytics data for this link will also be deleted. The short code will become available for reuse.

QR Code Generation

Generate QR codes for your shortened links to enable easy scanning and sharing.

How It Works

QR code generation is handled entirely on the frontend using the react-qr-code library. No API calls are required.

Access share dialog

Open the share dialog for any link in the web interface

QR code auto-generates

The QR code is generated automatically using the short URL

Copy or download

Copy the QR code as PNG or download as SVG

Features

PNG Copy

Copy QR code as image to clipboard

SVG Download

Download high-quality vector format

Customizable Size

Adjust QR code dimensions as needed

Client-Side

No server processing required

Technical Details

The QR code component uses these properties:

<QRCode 
  value="https://macondo.link/a1B2c3"  // The shortened URL
  size={180}                            // Size in pixels
  id="qr-code"                          // Element identifier
/>

QR codes automatically include the https:// protocol to ensure proper scanning on all devices.

Link Analytics

View detailed metrics for individual links.

API Endpoint

GET /links/:id/metrics?days=30

Query Parameters

days

number

default:"30"

Number of days to include in metrics (1-365)

Response

{
  "clicksByDate": [
    { "date": "2024-03-01", "count": 45 },
    { "date": "2024-03-02", "count": 38 }
  ],
  "topBrowsers": [
    { "browser": "Chrome", "count": 234 },
    { "browser": "Safari", "count": 156 }
  ],
  "topCountries": [
    { "country": "Brazil", "count": 189 },
    { "country": "Uruguay", "count": 143 }
  ],
  "topCities": [
    { "city": "São Paulo", "count": 98 },
    { "city": "Montevideo", "count": 87 }
  ]
}

See the Analytics page for more details on metrics.

Association with Clients and Campaigns

Client Association

Every link must be associated with a client. This is a required field that helps organize links by customer or project.

{
  "clientId": "client-uuid"  // Required
}

Campaign Association

Links can optionally be associated with a campaign for more granular organization:

{
  "campaignId": "campaign-uuid"  // Optional
}

Or explicitly set to null for links without campaigns:

{
  "campaignId": null
}

Organizational Hierarchy

Client (Required)
  └─ Campaign (Optional)
      └─ Links

When a campaign is deleted, links associated with it have their campaignId set to null but remain associated with the client.

Error Handling

Common Errors

Status Code	Error	Description
`404`	Client not found	The specified `clientId` doesn’t exist
`404`	Campaign not found	The specified `campaignId` doesn’t exist
`404`	Link not found	The specified link `id` doesn’t exist
`400`	Invalid URL	The `originalUrl` is not a valid URL format
`401`	Unauthorized	Authentication required or token expired

Example Error Response

{
  "message": "Cliente não encontrado."
}

Best Practices

Use Descriptive Tags

Tag links with meaningful categories for easier filtering and reporting

Associate Campaigns

Link to campaigns when possible for better analytics segmentation

Update URLs Carefully

When updating destination URLs, ensure redirects still make sense to users

Monitor Click Metrics

Regularly check link analytics to optimize your campaigns

Get Started

Core Features

Guides

​Overview

Short URLs

QR Codes

Organization

Tagging

​Creating Links

​API Endpoint

​Required Fields

​Optional Fields

​Response

​Short Code Generation

​Generation Algorithm

​URL Format

​Listing Links

​API Endpoint

​Query Parameters

​Examples

​Viewing Link Details

​API Endpoint

​Response

​Editing Links

​API Endpoint

​Updatable Fields

​Response

​Deleting Links

​API Endpoint

​Response

​QR Code Generation

​How It Works

​Features

PNG Copy

SVG Download

Customizable Size

Client-Side

​Technical Details

​Link Analytics

​API Endpoint

​Query Parameters

​Response

​Association with Clients and Campaigns

​Client Association

​Campaign Association

​Organizational Hierarchy

​Error Handling

​Common Errors

​Example Error Response

​Best Practices

Use Descriptive Tags

Associate Campaigns

Update URLs Carefully

Monitor Click Metrics

Build docs developers (and LLMs) love

Overview

Creating Links

API Endpoint

Required Fields

Optional Fields

Response

Short Code Generation

Generation Algorithm

URL Format

Listing Links

API Endpoint

Query Parameters

Examples

Viewing Link Details

API Endpoint

Response

Editing Links

API Endpoint

Updatable Fields

Response

Deleting Links

API Endpoint

Response

QR Code Generation

How It Works

Features

Technical Details

Link Analytics

API Endpoint

Query Parameters

Response

Association with Clients and Campaigns

Client Association

Campaign Association

Organizational Hierarchy

Error Handling

Common Errors

Example Error Response

Best Practices