Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/RaulQD/kontrak-backend/llms.txt

Use this file to discover all available pages before exploring further.

​
Generate Your First Contract

This guide will take you from zero to generating your first employment contract in under 10 minutes.
1

Prerequisites Check

Before starting, ensure you have the following installed:
  • Node.js: Version 18.0.0 or higher
  • npm: Version 8.0.0 or higher (comes with Node.js)
  • Git: For cloning the repository
Verify your installations:
node --version  # Should show v18.0.0 or higher
npm --version   # Should show 8.0.0 or higher
2

Clone and Install

Clone the repository and install dependencies:
# Clone the repository
git clone <your-repository-url>
cd kontrak-backend

# Install dependencies
npm install
This will install all required packages including Express, TypeScript, Puppeteer, and Zod.
3

Environment Setup

Create a .env file in the project root with the following configuration:
.env
# Server Configuration
NODE_ENV=development
PORT=3000
HOST=localhost

# CORS - Allowed origins (comma-separated)
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# File Limits
MAX_FILE_SIZE=10485760  # 10MB
MAX_EMPLOYEES=1000

# Temporary directory for file processing
TEMP_DIR=./temp
You can copy the example file: cp .env.example .env
4

Start the Development Server

Start the server in development mode:
npm run dev
You should see output similar to:
[INFO] Creando aplicacion Express...
[INFO] Inicializando servidor...
[INFO] =========== Server running on port 3000 ==========
[INFO] =========== Environment: development ==========
The server uses nodemon and ts-node in development mode, which automatically restarts on file changes.
5

Verify Installation

Test that the API is running by hitting the health check endpoint:
curl http://localhost:3000/
Expected response:
{
  "success": true,
  "message": "Kontrak API - Sistema de Generación de Contratos",
  "version": "1.0.0",
  "status": "running",
  "timestamp": "2026-03-05T10:30:00.000Z",
  "endpoints": {
    "uploadExcel": "POST /api/contracts/upload",
    "health": "GET /api/health"
  }
}
6

Generate Your First Contract

Now let’s generate a sample employment contract. Create a file called test-employee.json:
test-employee.json
{
  "name": "Juan",
  "lastNameFather": "Pérez",
  "lastNameMother": "García",
  "dni": "12345678",
  "email": "juan.perez@example.com",
  "birthDate": "15/05/1990",
  "sex": "M",
  "province": "Lima",
  "district": "Miraflores",
  "department": "Lima",
  "address": "Av. Larco 1234",
  "salary": 3000,
  "salaryInWords": "Tres mil con 00/100 soles",
  "position": "Desarrollador Senior",
  "entryDate": "01/04/2026",
  "endDate": "31/12/2026",
  "subDivisionOrParking": "Tecnología",
  "contractType": "PLANILLA"
}
Generate and preview the contract:
curl -X POST http://localhost:3000/api/contracts/preview \
  -H "Content-Type: application/json" \
  -d @test-employee.json \
  --output contract-preview.pdf
7

Generate Bulk Contracts

To generate multiple contracts at once, use the batch endpoint with an array of employees:
bulk-employees.json
[
  {
    "name": "Juan",
    "lastNameFather": "Pérez",
    "lastNameMother": "García",
    "dni": "12345678",
    "email": "juan.perez@example.com",
    "birthDate": "15/05/1990",
    "sex": "M",
    "province": "Lima",
    "district": "Miraflores",
    "department": "Lima",
    "address": "Av. Larco 1234",
    "salary": 3000,
    "salaryInWords": "Tres mil con 00/100 soles",
    "position": "Desarrollador Senior",
    "entryDate": "01/04/2026",
    "endDate": "31/12/2026",
    "subDivisionOrParking": "Tecnología",
    "contractType": "PLANILLA"
  },
  {
    "name": "María",
    "lastNameFather": "López",
    "lastNameMother": "Torres",
    "dni": "87654321",
    "email": "maria.lopez@example.com",
    "birthDate": "20/08/1992",
    "sex": "F",
    "province": "Lima",
    "district": "San Isidro",
    "department": "Lima",
    "address": "Calle Las Flores 567",
    "salary": 2000,
    "salaryInWords": "Dos mil con 00/100 soles",
    "position": "Diseñadora",
    "entryDate": "01/04/2026",
    "endDate": "31/12/2026",
    "subDivisionOrParking": "Diseño",
    "contractType": "PART TIME"
  }
]
Download all contracts as a ZIP:
curl -X POST http://localhost:3000/api/contracts/download-zip \
  -H "Content-Type: application/json" \
  -d @bulk-employees.json \
  --output contracts.zip
The ZIP file will contain organized folders for each contract type with all associated documents (contract, data processing agreement, and annexes).

​
Understanding Contract Types

Kontrak Backend supports three contract types, each with specific requirements:
Standard full-time employment contracts.Minimum Required Fields:
{
  name: string,
  lastNameFather: string,
  lastNameMother: string,
  dni: string,          // 8 digits
  email: string,
  birthDate: string,    // DD/MM/YYYY
  sex: string,
  address: string,
  province: string,
  district: string,
  department: string,
  salary: number,       // > 0
  salaryInWords: string,
  position: string,
  entryDate: string,    // DD/MM/YYYY
  endDate: string,      // DD/MM/YYYY
  subDivisionOrParking: string,
  contractType: "PLANILLA"
}

​
Validation Rules

The API validates all employee data using Zod schemas. Common validation rules:
FieldValidation
dniExactly 8 numeric digits
emailValid email format
name, lastNameFather, lastNameMother2-50 characters, letters only
salaryMust be greater than 0
entryDate, endDateFormat: DD/MM/YYYY
contractTypeMust be: PLANILLA, PART TIME, or SUBSIDIO

​
Common Issues and Solutions

Ensure the DNI field contains exactly 8 numeric characters with no spaces or special characters.
// ✅ Correct
"dni": "12345678"

// ❌ Incorrect
"dni": "1234567"   // Too short
"dni": "12-345-678" // Contains hyphens
Date fields must use the exact format DD/MM/YYYY with leading zeros.
// ✅ Correct
"entryDate": "01/04/2026"

// ❌ Incorrect
"entryDate": "1/4/2026"      // Missing leading zeros
"entryDate": "2026-04-01"    // Wrong format
If you’re on Linux and Puppeteer fails, install required dependencies:
# Ubuntu/Debian
sudo apt-get install -y \
  ca-certificates \
  fonts-liberation \
  libappindicator3-1 \
  libasound2 \
  libatk-bridge2.0-0 \
  libatk1.0-0 \
  libcups2 \
  libdbus-1-3 \
  libgdk-pixbuf2.0-0 \
  libnspr4 \
  libnss3 \
  libx11-xcb1 \
  libxcomposite1 \
  libxdamage1 \
  libxrandr2 \
  xdg-utils
The batch endpoint limits processing to 50 employees at a time for performance reasons.Split your data into smaller batches:
// Process in chunks of 50
const chunkSize = 50;
for (let i = 0; i < employees.length; i += chunkSize) {
  const chunk = employees.slice(i, i + chunkSize);
  // Process chunk...
}

​
Next Steps

Full Installation Guide

Detailed setup for production environments

API Reference

Complete API endpoint documentation

Configuration

Advanced configuration options

​
Need Help?

If you encounter any issues:
  1. Check the server logs for detailed error messages
  2. Verify your employee data against the validation schemas
  3. Review the Installation Guide for system requirements
  4. Consult the API Reference for endpoint specifications

Build docs developers (and LLMs) love

Get started for freeTalk to us