Skip to main content

​
Introduction

The Kontrak API is a REST API designed for generating employment contracts and processing employee data through Excel files. It provides endpoints for contract generation, Excel data processing, and addendum creation.

​
Base URL

The API is accessible at: 
http://localhost:3000/api
In production, replace localhost:3000 with your deployed server URL.

​
API Version

Current version: v1.0.0 The API follows a simple versioning approach. Version information is returned in the root health check endpoint.

​
Request/Response Format

All API endpoints accept and return JSON data unless otherwise specified.

​
Standard Response Structure

Successful responses follow this structure: 
{
  "success": true,
  "message": "Operation completed successfully",
  "data": {}
}
Error responses follow this structure: 
{
  "success": false,
  "message": "Error description",
  "errors": []
}

​
Available Endpoints

The API is organized into three main resource groups:

Contracts

Generate and preview employment contracts in PDF and ZIP formats

Excel Processing

Upload and process Excel files, generate specialized Excel reports

Addendum

Process addendum data from Excel files

​
Contract Endpoints

  • POST /api/contracts/download-zip - Generate and download contracts as ZIP
  • POST /api/contracts/preview - Preview a contract PDF

​
Excel Processing Endpoints

  • POST /api/excel/upload - Upload and process Excel file with employee data
  • POST /api/excel/download-lawlife - Generate Law Life Excel report
  • POST /api/excel/download-sctr - Generate SCTR Excel report
  • POST /api/excel/download-photocheck - Generate photocheck/ID card Excel

​
Addendum Endpoints

  • POST /api/addendum/upload - Process Excel file to extract addendum data

​
Health Check

The API provides two health check endpoints:

​
Root Health Check

GET /
Returns comprehensive API information including version, status, and available endpoints. 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"
  }
}

​
API Health Check

GET /api/health
Returns basic server health status. Response: 
{
  "success": true,
  "message": "Server is running",
  "timestamp": "2026-03-05T10:30:00.000Z",
  "path": "/api/health"
}

​
File Upload Limits

The API enforces the following file upload limits:
  • Maximum file size: 10 MB (configurable via MAX_FILE_SIZE environment variable)
  • Maximum files per request: 1
  • Allowed file types: .xlsx, .xls, .csv
  • Maximum employees per batch: 1,000 (configurable via MAX_EMPLOYEES environment variable)
Exceeding file size or employee limits will result in a 400 Bad Request error.

​
CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) for the following HTTP methods:
  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
Allowed origins are configured via the CORS_ORIGINS environment variable (default: http://localhost:5173).

​
Error Handling

The API uses standard HTTP status codes:
Status CodeDescription
200Success
400Bad Request - Invalid input or validation error
404Not Found - Endpoint does not exist
500Internal Server Error

​
Validation Errors

Validation errors return detailed information about invalid fields: 
{
  "success": false,
  "message": "La solicitud no se pudo procesar",
  "errors": [
    {
      "field": "body.employeeData.name",
      "message": "Required field is missing"
    }
  ]
}

​
Rate Limiting

Currently, the API does not implement rate limiting. For production deployments, it is recommended to add rate limiting middleware to prevent abuse.

​
Next Steps

Authentication

Learn about API security and authentication

Contract Endpoints

Explore contract generation endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us