API Overview

Introduction

The Macondo Link Manager API is a RESTful service built with Fastify and Prisma for managing shortened links, tracking analytics, and organizing marketing campaigns.

Base URL

All API requests should be made to:

https://li.mcd.ppg.br

For local development:

http://localhost:3333

Architecture

The API is built with:

Fastify: High-performance Node.js web framework
Prisma: Type-safe ORM for database operations
Zod: Schema validation for requests and responses
PostgreSQL: Primary database

Available Resources

The API provides the following resource groups:

Authentication

Google OAuth 2.0 login and JWT-based session management

Links

Create, manage, and track shortened links

Clients

Manage agency clients and their campaigns

Campaigns

Organize links into marketing campaigns

Dashboard

Analytics and reporting endpoints

Users

User profile and session information

Request Format

All requests should use JSON format with the appropriate Content-Type header:

Content-Type: application/json

Example Request

curl -X POST https://li.mcd.ppg.br/links \
  -H "Content-Type: application/json" \
  -H "Cookie: macondo.token=YOUR_JWT_TOKEN" \
  -d '{
    "originalUrl": "https://example.com/long-url",
    "clientId": "123e4567-e89b-12d3-a456-426614174000",
    "campaignId": "987fcdeb-51a2-43f7-9abc-123456789def",
    "tags": ["social", "facebook"]
  }'

Response Format

All responses are returned in JSON format.

Success Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "originalUrl": "https://example.com/long-url",
  "shortCode": "abc123",
  "clientId": "123e4567-e89b-12d3-a456-426614174000",
  "campaignId": "987fcdeb-51a2-43f7-9abc-123456789def",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Error Handling

The API uses standard HTTP status codes and returns detailed error messages.

Error Response Structure

{
  "message": "Error description"
}

Common Status Codes

Status Code	Description
`200`	Success
`201`	Resource created successfully
`204`	Success with no content (e.g., deletions)
`400`	Bad request - validation error
`401`	Unauthorized - missing or invalid authentication
`403`	Forbidden - insufficient permissions
`404`	Resource not found
`409`	Conflict - resource already exists
`500`	Internal server error
`503`	Service unavailable

Validation Errors

Validation errors include detailed information about what failed:

{
  "message": "Erro de validação.",
  "issues": {
    "originalUrl": "Invalid URL format",
    "clientId": "Required field"
  }
}

Domain Errors

Resource-specific errors:

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

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

{
  "message": "Campanha não encontrada."
}

CORS Configuration

The API is configured to accept requests from the configured frontend URL with credentials support:

Allowed Methods: GET, POST, PUT, DELETE, OPTIONS
Credentials: Enabled (cookies are sent/received)
Allowed Origin: Configured via FRONTEND_URL environment variable

The API uses cookie-based authentication, so ensure your client includes credentials in cross-origin requests.

Rate Limiting

Currently, there are no explicit rate limits enforced at the application level. However, standard infrastructure rate limiting may apply.

Always implement client-side throttling and error handling to ensure resilient integrations.

Health Check

Check the API and database status:

Endpoint

GET /health

Success Response (200)

{
  "status": "ok",
  "dbConnection": "healthy"
}

Error Response (503)

{
  "status": "error",
  "dbConnection": "unhealthy"
}

Example

curl https://li.mcd.ppg.br/health

Interactive Documentation

Explore and test the API using the built-in Swagger UI:

https://li.mcd.ppg.br/docs

The Swagger documentation provides:

Complete endpoint reference
Request/response schemas
Interactive “Try it out” functionality
Request examples
Response samples

Open Swagger Documentation

Test API endpoints in your browser

Request Tracking

All requests include a unique request ID in the response headers:

x-request-id: abc123-def456-ghi789

Include this ID when reporting issues for faster debugging.

Next Steps

Authentication

Learn how to authenticate and manage sessions

Create Your First Link

Start creating and managing shortened links

Overview

Endpoints

Introduction

Base URL

Architecture

Available Resources

Authentication

Links

Clients

Campaigns

Dashboard

Users

Request Format

Example Request

Response Format

Success Response

Error Handling

Error Response Structure

Common Status Codes

Validation Errors

Domain Errors

CORS Configuration

Rate Limiting

Health Check

Endpoint

Success Response (200)

Error Response (503)

Example

Interactive Documentation

Open Swagger Documentation

Request Tracking

Next Steps

Authentication

Create Your First Link

Build docs developers (and LLMs) love

Overview

Endpoints

​Introduction

​Base URL

​Architecture

​Available Resources

Authentication

Links

Clients

Campaigns

Dashboard

Users

​Request Format

​Example Request

​Response Format

​Success Response

​Error Handling

​Error Response Structure

​Common Status Codes

​Validation Errors

​Domain Errors

​CORS Configuration

​Rate Limiting

​Health Check

​Endpoint

​Success Response (200)

​Error Response (503)

​Example

​Interactive Documentation

Open Swagger Documentation

​Request Tracking

​Next Steps

Authentication

Create Your First Link

Build docs developers (and LLMs) love

Introduction

Base URL

Architecture

Available Resources

Request Format

Example Request

Response Format

Success Response

Error Handling

Error Response Structure

Common Status Codes

Validation Errors

Domain Errors

CORS Configuration

Rate Limiting

Health Check

Endpoint

Success Response (200)

Error Response (503)

Example

Interactive Documentation

Request Tracking

Next Steps