Upload Excel for Addendum - Kontrak Backend

Overview

This endpoint allows you to upload an Excel file containing employee addendum information. The system will validate the data and return a structured response with employee details ready for addendum generation.

Request

Headers

Content-Type

string

required

Must be multipart/form-data

Body Parameters

excel

file

required

Excel file containing employee addendum dataAllowed formats: .xlsx, .xls, .csvMaximum file size: 10MB (10,485,760 bytes)MIME types accepted:

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
application/vnd.ms-excel
application/excel
application/x-excel
application/x-msexcel

Excel File Structure

The Excel file must contain the following columns (field names are flexible - aliases are accepted):

Required Fields

division

string

required

Division or work areaAliases: DIVISION, división, division, area, AREA, DivisionValidation: Required, trimmed string

documentNumber

string

required

Employee’s document number (DNI)Aliases: Numero Documento, dni, documento, NÚMERO DE DOCUMENTO, Num. DocumentoValidation: Must be exactly 8 digits

worker

string

required

Full name of the employeeAliases: TRABAJADOR, trabajador, nombres y apellidos, empleado, colaborador, TrabajadorValidation: Required string

entryDate

string

required

Employee’s original entry date to the companyAliases: fecha de ingreso, fechadeingreso, fecha_de_ingreso, entrydate, entry_date, fecha ingreso, Fecha IngresoFormat: DD/MM/YYYYExample: 15/03/2024

start

string

required

Original contract start dateAliases: INICIO, inicio, InicioFormat: DD/MM/YYYYExample: 01/01/2024

end

string

required

Original contract end dateAliases: FECHA FIN, fecha fin, fin contrato, termino, Fin, FIN, finFormat: DD/MM/YYYYExample: 31/12/2024

startAddendum

string

required

Addendum effective start dateAliases: INICIO ADENDA, inicio adenda, fecha inicio adenda, vigencia desde, Inicio AdendaFormat: DD/MM/YYYYExample: 01/01/2025

endAddendum

string

required

Addendum effective end dateAliases: FIN ADENDA, fin adenda, fecha fin adenda, vigencia hastaFormat: DD/MM/YYYYExample: 31/12/2025

address

string

required

Employee’s addressAliases: dirección, direccion, address, direccion completa, DOMICILIO, domicilio, DirecciónValidation:

Minimum 5 characters
Maximum 200 characters
Trimmed

province

string

required

Province where the employee residesAliases: provincia, province, PROVINCIA, ProvinciaValidation: Minimum 2 characters, trimmed

district

string

required

District where the employee residesAliases: distrito, district, Distrito, DISTRITOValidation: Minimum 2 characters, trimmed

department

string

required

Department where the employee residesAliases: departamento, department, division, Departamento, DEPARTAMENTOValidation: Minimum 2 characters, trimmed

salary

number

required

Employee’s salary amountAliases: salario, salary, sueldo, remuneracion, remuneración, Sueldo, SUELDOValidation: Must be a positive number greater than 0Example: 2500.00

salaryInWords

string

required

Employee’s salary written in wordsAliases: salario en letras, salarioenletras, salario_en_letras, salaryinwords, salary_in_words, sueldo en letras, Sueldo en LetrasValidation:

Minimum 5 characters
Maximum 100 characters
Trimmed

Example: Dos mil quinientos soles

Excel File Notes

The first row should contain column headers
Empty rows are automatically skipped
Column names are case-insensitive and flexible (multiple aliases accepted)
Maximum 80 employees per batch
All date fields must be in DD/MM/YYYY format

Response

success

boolean

required

Indicates if the operation was successful

data

object

required

Contains the processed employee data

data.totalRecords

number

Total number of employee records processed

data.employees

array

Array of employee objects with validated addendum data

data.employees[].division

string

Employee’s division or work area

data.employees[].documentNumber

string

Employee’s DNI (8 digits)

data.employees[].worker

string

Full name of the employee

data.employees[].entryDate

string

Original entry date (DD/MM/YYYY)

data.employees[].start

string

Original contract start date (DD/MM/YYYY)

data.employees[].end

string

Original contract end date (DD/MM/YYYY)

data.employees[].startAddendum

string

Addendum start date (DD/MM/YYYY)

data.employees[].endAddendum

string

Addendum end date (DD/MM/YYYY)

data.employees[].address

string

Employee’s address

data.employees[].province

string

Employee’s province

data.employees[].district

string

Employee’s district

data.employees[].department

string

Employee’s department

data.employees[].salary

number

Employee’s salary amount

data.employees[].salaryInWords

string

Employee’s salary in words

Success Response Example

{
  "success": true,
  "data": {
    "totalRecords": 2,
    "employees": [
      {
        "division": "Recursos Humanos",
        "documentNumber": "12345678",
        "worker": "Juan Pérez García",
        "entryDate": "15/03/2023",
        "start": "01/01/2024",
        "end": "31/12/2024",
        "startAddendum": "01/01/2025",
        "endAddendum": "31/12/2025",
        "address": "Av. Los Héroes 123, San Isidro",
        "province": "Lima",
        "district": "San Isidro",
        "department": "Lima",
        "salary": 2500,
        "salaryInWords": "Dos mil quinientos soles"
      },
      {
        "division": "Ventas",
        "documentNumber": "87654321",
        "worker": "María López Rodríguez",
        "entryDate": "10/05/2023",
        "start": "01/02/2024",
        "end": "31/01/2025",
        "startAddendum": "01/02/2025",
        "endAddendum": "31/01/2026",
        "address": "Jr. Las Flores 456, Miraflores",
        "province": "Lima",
        "district": "Miraflores",
        "department": "Lima",
        "salary": 3000,
        "salaryInWords": "Tres mil soles"
      }
    ]
  }
}

Error Responses

No File Provided (400)

{
  "success": false,
  "message": "No se recibió ningún archivo. Envía un campo \"excel\""
}

Invalid File Type (400)

{
  "success": false,
  "message": "Tipo de archivo no permitidos .pdf. solo se permiten archivos Excel( .xlsx, .xls,.csv)"
}

Invalid File Extension (400)

{
  "success": false,
  "message": "Extensiones de archivo no permitidas: .txt. Solo se permiten: .xlsx, .xls, .csv"
}

File Too Large (400)

{
  "success": false,
  "message": "El archivo excede el tamaño máximo permitido de 10MB"
}

Validation Error (400)

{
  "success": false,
  "message": "Error de validación en los datos",
  "errors": [
    {
      "row": 2,
      "field": "documentNumber",
      "message": "DNI debe tener exactamente 8 dígitos."
    },
    {
      "row": 3,
      "field": "salary",
      "message": "El sueldo debe ser mayor a 0"
    }
  ]
}

Too Many Employees (400)

{
  "success": false,
  "message": "Máximo 80 empleados por lote"
}

Missing Required Field (400)

{
  "success": false,
  "message": "Campo requerido faltante: division",
  "errors": [
    {
      "row": 5,
      "field": "division",
      "message": "Division es requerido."
    }
  ]
}

Invalid Date Format (400)

{
  "success": false,
  "message": "Error de validación en los datos",
  "errors": [
    {
      "row": 4,
      "field": "entryDate",
      "message": "Fecha debe estar en formato DD/MM/YYYY"
    }
  ]
}

Example Requests

cURL

curl -X POST https://api.example.com/api/addendum/upload \
  -H "Content-Type: multipart/form-data" \
  -F "excel=@/path/to/addendum_employees.xlsx"

cURL with Authentication

curl -X POST https://api.example.com/api/addendum/upload \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "excel=@/path/to/addendum_employees.xlsx"

JavaScript (Fetch API)

const formData = new FormData();
const fileInput = document.querySelector('input[type="file"]');
formData.append('excel', fileInput.files[0]);

fetch('https://api.example.com/api/addendum/upload', {
  method: 'POST',
  body: formData
})
  .then(response => response.json())
  .then(data => {
    console.log('Success:', data);
    console.log('Total records:', data.data.totalRecords);
    console.log('Employees:', data.data.employees);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Python (Requests)

import requests

url = 'https://api.example.com/api/addendum/upload'
files = {'excel': open('addendum_employees.xlsx', 'rb')}

response = requests.post(url, files=files)
data = response.json()

if data['success']:
    print(f"Total records: {data['data']['totalRecords']}")
    for employee in data['data']['employees']:
        print(f"Employee: {employee['worker']} - DNI: {employee['documentNumber']}")
else:
    print(f"Error: {data['message']}")

Node.js (Axios)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('excel', fs.createReadStream('addendum_employees.xlsx'));

axios.post('https://api.example.com/api/addendum/upload', form, {
  headers: form.getHeaders()
})
  .then(response => {
    console.log('Success:', response.data);
    console.log('Total records:', response.data.data.totalRecords);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Validation Rules Summary

Field	Type	Format	Min	Max	Special Rules
division	string	-	-	-	Required, trimmed
documentNumber	string	8 digits	-	-	Exactly 8 numeric digits
worker	string	-	-	-	Required
entryDate	string	DD/MM/YYYY	-	-	Valid date format
start	string	DD/MM/YYYY	-	-	Valid date format
end	string	DD/MM/YYYY	-	-	Valid date format
startAddendum	string	DD/MM/YYYY	-	-	Valid date format
endAddendum	string	DD/MM/YYYY	-	-	Valid date format
address	string	-	5 chars	200 chars	Trimmed
province	string	-	2 chars	-	Trimmed
district	string	-	2 chars	-	Trimmed
department	string	-	2 chars	-	Trimmed
salary	number	-	> 0	-	Must be positive
salaryInWords	string	-	5 chars	100 chars	Trimmed

Best Practices

File Preparation
- Use the first row for column headers
- Ensure all required fields are present
- Use consistent date formatting (DD/MM/YYYY)
- Verify DNI numbers are exactly 8 digits
- Remove any empty rows from your Excel file
Data Validation
- Validate salary values are positive numbers
- Check that all dates are in the correct format
- Ensure addresses meet minimum character requirements
- Verify salary in words matches the numeric value
Error Handling
- Check the response for validation errors
- Review the specific row and field mentioned in error messages
- Correct errors in the Excel file and re-upload
Performance
- Keep batch sizes under 80 employees
- Use compressed Excel files (.xlsx) for faster uploads
- Ensure file size is under 10MB limit

Upload Contract Excel - Upload Excel for contract generation
Generate Contracts - Generate contract PDFs

Overview

Contracts

Excel

Addendum

Documentation Index

​Overview

​Request

​Headers

​Body Parameters

​Excel File Structure

​Required Fields

​Excel File Notes

​Response

​Success Response Example

​Error Responses

​No File Provided (400)

​Invalid File Type (400)

​Invalid File Extension (400)

​File Too Large (400)

​Validation Error (400)

​Too Many Employees (400)

​Missing Required Field (400)

​Invalid Date Format (400)

​Example Requests

​cURL

​cURL with Authentication

​JavaScript (Fetch API)

​Python (Requests)

​Node.js (Axios)

​Validation Rules Summary

​Best Practices

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Request

Headers

Body Parameters

Excel File Structure

Required Fields

Excel File Notes

Response

Success Response Example

Error Responses

No File Provided (400)

Invalid File Type (400)

Invalid File Extension (400)

File Too Large (400)

Validation Error (400)

Too Many Employees (400)

Missing Required Field (400)

Invalid Date Format (400)

Example Requests

cURL

cURL with Authentication

JavaScript (Fetch API)

Python (Requests)

Node.js (Axios)

Validation Rules Summary

Best Practices

Related Endpoints