Quick Start

Generate Your First Contract

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

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

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.

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

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.

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"
  }
}

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": "[email protected]",
  "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

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": "[email protected]",
    "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": "[email protected]",
    "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:

PLANILLA (Standard)
PART TIME
SUBSIDIO (Substitution)

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"
}

Part-time employment contracts with flexible hours.Uses the same fields as PLANILLA but set contractType: "PART TIME".

Temporary substitution contracts require additional fields:

{
  // ... all PLANILLA fields, plus:
  replacementFor: string,        // Required
  reasonForSubstitution: string, // Required
  timeForCompany: string,        // Required
  workingCondition: string,      // Required
  probationaryPeriod: string,    // Required
  contractType: "SUBSIDIO"
}

SUBSIDIO contracts will fail validation if any of the additional fields are missing.

Validation Rules

The API validates all employee data using Zod schemas. Common validation rules:

Field	Validation
`dni`	Exactly 8 numeric digits
`email`	Valid email format
`name`, `lastNameFather`, `lastNameMother`	2-50 characters, letters only
`salary`	Must be greater than 0
`entryDate`, `endDate`	Format: DD/MM/YYYY
`contractType`	Must be: PLANILLA, PART TIME, or SUBSIDIO

Common Issues and Solutions

Error: DNI debe tener exactamente 8 dígitos numéricos

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

Error: Fecha debe estar en formato DD/MM/YYYY

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

Puppeteer fails to launch on Linux

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

Maximum 50 employees per batch error

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:

Check the server logs for detailed error messages
Verify your employee data against the validation schemas
Review the Installation Guide for system requirements
Consult the API Reference for endpoint specifications

Get Started

Core Concepts

Guides

Generate Your First Contract

Understanding Contract Types

Validation Rules

Common Issues and Solutions

Next Steps

Full Installation Guide

API Reference

Configuration

Need Help?

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Generate Your First Contract

​Understanding Contract Types

​Validation Rules

​Common Issues and Solutions

​Next Steps

Full Installation Guide

API Reference

Configuration

​Need Help?

Build docs developers (and LLMs) love

Generate Your First Contract

Understanding Contract Types

Validation Rules

Common Issues and Solutions

Next Steps

Need Help?