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.

​
Endpoint

Uploads an Excel file containing employee data, validates it against the required schema, and returns the parsed employee records.

​
Request

​
Headers

{
  "Content-Type": "multipart/form-data"
}

​
Body Parameters

​
excel
file
required
Excel file (.xlsx) containing employee contract data. The file must contain specific headers and follow the expected format.

​
Required Excel Headers

The Excel file must contain the following columns (case-insensitive, accent-insensitive): Basic Information:
  • NOMBRE or Nombre completo - Employee’s first name
  • APELLIDO PATERNO - Father’s last name
  • APELLIDO MATERNO - Mother’s last name
  • DNI - Document number (8 digits)
  • EMAIL or Correo - Email address
Location:
  • DIRECCIÓN or DOMICILIO - Full address
  • PROVINCIA - Province
  • DISTRITO - District
  • DEPARTAMENTO - Department
Employment Details:
  • CARGO - Position/Job title
  • PLAYA or ESTACIONAMIENTO - Work location/parking
  • SUELDO - Salary (numeric)
  • SUELDO EN LETRAS - Salary in words
  • INICIO 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 - Gender
  • FECHA DE NACIMIENTO - Birth date (DD/MM/YYYY)
Required for SUBSIDIO contracts only:
  • SUPLENCIA DE - Name of person being replaced
  • MOTIVO DE SUPLENCIA - Reason for replacement
  • TIEMPO EN EMPRESA - Time at company
  • CONDICION LABORAL - Working condition
  • PERIODO DE PRUEBA - Probationary period

​
Response

​
success
boolean
Indicates if the upload was successful
​
message
string
Success message with number of employees imported
​
data
object

​
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": "juan.perez@example.com",
        "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."
}

​
Invalid Headers

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

Build docs developers (and LLMs) love

Get started for freeTalk to us