Endpoint
Uploads an Excel file containing employee data, validates it against the required schema, and returns the parsed employee records.
Request
{
"Content-Type": "multipart/form-data"
}
Body Parameters
Excel file (.xlsx) containing employee contract data. The file must contain specific headers and follow the expected format.
NOMBRE or Nombre completo - Employee’s first nameAPELLIDO PATERNO - Father’s last nameAPELLIDO MATERNO - Mother’s last nameDNI - Document number (8 digits)EMAIL or Correo - Email address
Location:
DIRECCIÓN or DOMICILIO - Full addressPROVINCIA - ProvinceDISTRITO - DistrictDEPARTAMENTO - Department
Employment Details:
CARGO - Position/Job titlePLAYA or ESTACIONAMIENTO - Work location/parkingSUELDO - Salary (numeric)SUELDO EN LETRAS - Salary in wordsINICIO or FECHA DE INGRESO - Start date (DD/MM/YYYY)FIN or FECHA DE TERMINO - End date (DD/MM/YYYY)TIPO DE CONTRATO - Contract type (PLANILLA, PART TIME, or SUBSIDIO)
Optional Fields:
GENERO or SEXO - GenderFECHA DE NACIMIENTO - Birth date (DD/MM/YYYY)
Required for SUBSIDIO contracts only:
SUPLENCIA DE - Name of person being replacedMOTIVO DE SUPLENCIA - Reason for replacementTIEMPO EN EMPRESA - Time at companyCONDICION LABORAL - Working conditionPERIODO DE PRUEBA - Probationary period
Response
Indicates if the upload was successful
Success message with number of employees imported
Total number of records in the Excel file
Array of validated employee recordsShow Employee object properties
PLANILLA, PART TIME, or SUBSIDIO
Name of person being replaced (SUBSIDIO only)
Reason for replacement (SUBSIDIO only)
Time at company (SUBSIDIO only)
Working condition (SUBSIDIO only)
Probationary period (SUBSIDIO only)
Example
curl -X POST https://api.kontrak.com/api/excel/upload \
-H "Content-Type: multipart/form-data" \
-F "excel=@/path/to/employees.xlsx"
Success Response
{
"success": true,
"message": "Se importaron 15 empleados correctamente.",
"data": {
"totalRecords": 15,
"employees": [
{
"name": "Juan",
"lastNameFather": "Pérez",
"lastNameMother": "García",
"dni": "12345678",
"email": "[email protected]",
"address": "Av. Principal 123",
"province": "Lima",
"district": "Miraflores",
"department": "Lima",
"position": "Operario",
"subDivisionOrParking": "Playa 1",
"salary": 1500,
"salaryInWords": "Mil quinientos soles",
"entryDate": "01/03/2024",
"endDate": "31/12/2024",
"contractType": "PLANILLA",
"sex": "M",
"birthDate": "15/06/1990"
}
]
}
}
Error Responses
No File Provided
{
"success": false,
"message": "No se recibió ningún archivo Excel."
}
{
"success": false,
"message": "La estructura del archivo es incorrecta. Faltan columnas obligatorias.",
"context": {
"validationErrors": [
{
"row": 1,
"field": "NOMBRE",
"message": "Encabezado requerido no encontrado en el archivo."
},
{
"row": 1,
"field": "DNI",
"message": "Encabezado requerido no encontrado en el archivo."
}
]
}
}
Validation Errors
{
"success": false,
"message": "No se pudo procesar el archivo. Se encontraron 3 errores.",
"context": {
"validationErrors": [
{
"row": 2,
"field": "dni",
"message": "DNI debe tener exactamente 8 dígitos numéricos."
},
{
"row": 3,
"field": "email",
"message": "El correo es requerido"
},
{
"row": 5,
"field": "salary",
"message": "El sueldo debe ser mayor a 0"
}
]
}
}
Corrupt File
{
"success": false,
"message": "El archivo Excel está corrupto o no es un archivo válido"
}
Notes
- The file must be in
.xlsx format (Excel 2007+)
- Date format must be
DD/MM/YYYY
- DNI must be exactly 8 digits
- Salary must be a positive number
- Maximum 50 employees per batch
- The first row must contain the headers
- Empty rows are automatically skipped
- Header matching is case-insensitive and accent-insensitive