Datos de empleados

Los datos de empleado son la información laboral de un receptor que solo se usa en las facturas de nómina. Cada receptor tiene un solo registro de datos de empleado, así que primero crea el receptor y después sus datos de empleado.

Los datos de empleado son un subrecurso de las personas, en la ruta /api/v4/people/<personId>/employee. Los datos de empleado del owner del tenant solo los crea, actualiza o elimina el owner; si lo intenta otra persona, el endpoint responde 403.

Modelo datos de empleado

Las propiedades que empiezan con sat toman sus valores de los catálogos del SAT. Consulta sus claves en Catálogos CFDI 4.0 o con la API de catálogos.

Propiedades

Name
id
Type
string?
Description
Id asignado por Fiscalapi.
Name
employerPersonId
Type
string
required
Description
Id de la persona empleadora (patrón).
Name
employeePersonId
Type
string
required
Description
Id de la persona empleada.
Name
employeeNumber
Type
string
required
Description
Número de empleado asignado por el empleador.
Name
socialSecurityNumber
Type
string
required
Description
Número de seguridad social del empleado.
Name
laborRelationStartDate
Type
date
required
Description
Fecha de inicio de la relación laboral.
Name
satContractTypeId
Type
string
required
expandible
Description
Tipo de contrato entre el empleado y el empleador. Catálogo del SAT c_TipoContrato.
Type
enum:
Values
"01""02""03"
Name
satTaxRegimeTypeId
Type
string
required
expandible
Description
Tipo de régimen fiscal del empleado. Catálogo del SAT c_TipoRegimen.
Type
enum:
Values
"02""03""04"
Name
satWorkdayTypeId
Type
string
required
expandible
Description
Jornada de trabajo del empleado. Catálogo del SAT c_TipoJornada.
Type
enum:
Values
"01""02""03"
Name
satJobRiskId
Type
string
required
expandible
Description
Riesgo de trabajo del puesto del empleado. Catálogo del SAT c_RiesgoPuesto.
Type
enum:
Values
"1""2""3"
Name
satPaymentPeriodicityId
Type
string
required
expandible
Description
Periodicidad de pago del empleado. Catálogo del SAT c_PeriodicidadPago.
Type
enum:
Values
"01""02""03"
Name
satPayrollStateId
Type
string
required
expandible
Description
Entidad federativa donde el empleado labora. Catálogo del SAT c_Estado.
Type
enum:
Values
"AGU""BCN""BCS"
Name
seniority
Type
string
required
Description
Antigüedad del empleado como duración ISO 8601, en semanas o en años, meses y días. Ejemplo: P437W para 437 semanas o P1Y5M0D para 1 año y 5 meses.
Name
baseSalaryForContributions
Type
number
required
Description
Salario base de cotización o aportaciones del empleado. Debe estar entre 0 y 999,999,999,999.999999.
Name
integratedDailySalary
Type
number
required
Description
Salario diario integrado del empleado. Debe estar entre 0 y 999,999,999,999.999999.
Name
satBankId
Type
string?
expandible
Description
Banco donde el empleado recibe el pago de nómina. Catálogo del SAT c_Banco.
Type
enum:
Values
002006009
Name
satUnionizedStatusId
Type
string?
expandible
Description
Estado sindical del empleado. Catálogo del SAT c_Sindicalizado.
Type
enum:
Values
"Sí""No"
Name
position
Type
string?
Description
Puesto que ocupa el empleado.
Name
department
Type
string?
Description
Departamento donde labora el empleado.
Name
bankAccount
Type
string?
Description
Cuenta bancaria donde el empleado recibe el pago de nómina.
Name
subcontractorRfc
Type
string?
Description
RFC del subcontratista, cuando el empleado es subcontratado.
Name
timePercentage
Type
number?
Description
Porcentaje de tiempo de trabajo, cuando el empleado es subcontratado.

GET/api/v4/people/<personId>/employee

Obtener datos de empleado

Este endpoint obtiene los datos de empleado de una persona por su id.

Request

GET

/api/v4/people/<personId>/employee

curl --location 'https://test.fiscalapi.com/api/v4/people/<personId>/employee' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "employerPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
        "employeePersonId": "54fc14ae-c88f-4afc-996b-0574d63341e2",
        "employeeNumber": "123456789",
        "socialSecurityNumber": "0101010101",
        "laborRelationStartDate": "2020-01-12T00:00:00.000",
        "satContractType": {
            "id": "01",
            "description": "Contrato de trabajo por tiempo indeterminado",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satTaxRegimeType": {
            "id": "02",
            "description": "Sueldos (Incluye ingresos art. 94 LISR)",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satWorkdayType": null,
        "satJobRisk": {
            "id": "1",
            "description": "Clase I",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satPaymentPeriodicity": {
            "id": "04",
            "description": "Quincenal",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satBank": null,
        "satPayrollState": {
            "id": "JAL",
            "description": "Jalisco",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satUnionizedStatus": null,
        "department": null,
        "position": null,
        "seniority": "P1Y5M15D",
        "bankAccount": null,
        "baseSalaryForContributions": 520,
        "integratedDailySalary": 186,
        "subcontractorRfc": null,
        "timePercentage": 0
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

POST/api/v4/people/<personId>/employee

Crear datos de empleado

Este endpoint crea los datos de empleado de una persona. Cada persona tiene un solo registro de datos de empleado; si ya lo tiene, usa Actualizar datos de empleado.

Modelo

Name
employerPersonId
Type
string
required
Description
Id de la persona empleadora (patrón).
Name
employeePersonId
Type
string
required
Description
Id de la persona empleada.
Name
employeeNumber
Type
string
required
Description
Número de empleado asignado por el empleador.
Name
socialSecurityNumber
Type
string
required
Description
Número de seguridad social del empleado.
Name
laborRelationStartDate
Type
date
required
Description
Fecha de inicio de la relación laboral.
Name
satContractTypeId
Type
string
required
expandible
Description
Tipo de contrato entre el empleado y el empleador. Catálogo del SAT c_TipoContrato.
Type
enum:
Values
"01""02""03"
Name
satTaxRegimeTypeId
Type
string
required
expandible
Description
Tipo de régimen fiscal del empleado. Catálogo del SAT c_TipoRegimen.
Type
enum:
Values
"02""03""04"
Name
satWorkdayTypeId
Type
string
required
expandible
Description
Jornada de trabajo del empleado. Catálogo del SAT c_TipoJornada.
Type
enum:
Values
"01""02""03"
Name
satJobRiskId
Type
string
required
expandible
Description
Riesgo de trabajo del puesto del empleado. Catálogo del SAT c_RiesgoPuesto.
Type
enum:
Values
"1""2""3"
Name
satPaymentPeriodicityId
Type
string
required
expandible
Description
Periodicidad de pago del empleado. Catálogo del SAT c_PeriodicidadPago.
Type
enum:
Values
"01""02""03"
Name
satPayrollStateId
Type
string
required
expandible
Description
Entidad federativa donde el empleado labora. Catálogo del SAT c_Estado.
Type
enum:
Values
"AGU""BCN""BCS"
Name
seniority
Type
string
required
Description
Antigüedad del empleado como duración ISO 8601, en semanas o en años, meses y días. Ejemplo: P437W para 437 semanas o P1Y5M0D para 1 año y 5 meses.
Name
baseSalaryForContributions
Type
number
required
Description
Salario base de cotización o aportaciones del empleado. Debe estar entre 0 y 999,999,999,999.999999.
Name
integratedDailySalary
Type
number
required
Description
Salario diario integrado del empleado. Debe estar entre 0 y 999,999,999,999.999999.
Name
satBankId
Type
string?
expandible
Description
Banco donde el empleado recibe el pago de nómina. Catálogo del SAT c_Banco.
Type
enum:
Values
002006009
Name
satUnionizedStatusId
Type
string?
expandible
Description
Estado sindical del empleado. Catálogo del SAT c_Sindicalizado.
Type
enum:
Values
"Sí""No"
Name
position
Type
string?
Description
Puesto que ocupa el empleado.
Name
department
Type
string?
Description
Departamento donde labora el empleado.
Name
bankAccount
Type
string?
Description
Cuenta bancaria donde el empleado recibe el pago de nómina.
Name
subcontractorRfc
Type
string?
Description
RFC del subcontratista, cuando el empleado es subcontratado.
Name
timePercentage
Type
number?
Description
Porcentaje de tiempo de trabajo, cuando el empleado es subcontratado.

Errores

Todos los casos llegan como falla de validación en el campo que se indica.

Estado	Cuándo ocurre	Mensaje
400	La persona ya tiene datos de empleado. Falla en EmployeePersonId.	La persona ya tiene datos de empleado: modifícalos con PUT /api/v4/people/{personId}/employee.
400	baseSalaryForContributions es menor que 0. Falla en BaseSalaryForContributions.	SalarioBaseCotApor debe ser mayor o igual a 0.
400	baseSalaryForContributions es mayor que 999,999,999,999.999999. Falla en BaseSalaryForContributions.	SalarioBaseCotApor no puede ser mayor a 999999999999.999999.
400	integratedDailySalary es menor que 0. Falla en IntegratedDailySalary.	SalarioDiarioIntegrado debe ser mayor o igual a 0.
400	integratedDailySalary es mayor que 999,999,999,999.999999. Falla en IntegratedDailySalary.	SalarioDiarioIntegrado no puede ser mayor a 999999999999.999999.

Request

POST

/api/v4/people/<personId>/employee

curl --location 'https://test.fiscalapi.com/api/v4/people/54fc14ae-c88f-4afc-996b-0574d63341e2/employee' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '{
  "employerPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
  "employeePersonId": "54fc14ae-c88f-4afc-996b-0574d63341e2",
  "employeeNumber": "12345",
  "satContractTypeId": "01",
  "satTaxRegimeTypeId": "02",
  "satPaymentPeriodicityId": "04",
  "satPayrollStateId": "JAL",
  "socialSecurityNumber": "123456789012345",
  "laborRelationStartDate": "2023-01-15T00:00:00",
  "satWorkdayTypeId": "01",
  "satJobRiskId": "1",
  "satBankId": "002",
  "satUnionizedStatusId": "No",
  "department": "Recursos Humanos",
  "position": "Analista de Nóminas",
  "seniority": "P7Y3M7D",
  "bankAccount": "12345678901234567890",
  "baseSalaryForContributions": 490.22,
  "integratedDailySalary": 146.47,
  "subcontractorRfc": null,
  "timePercentage": null
}'

Response

{
    "data": {
        "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
        "employerRegistration": "B5510768108",
        "originEmployerTin": "URE180429TM6",
        "satFundSource": null,
        "ownResourceAmount": null,
        "id": "23f0b555-68bc-48fd-bb90-deb36ed25ef6",
        "createdAt": "2025-09-18T20:17:44.175",
        "updatedAt": "2025-09-18T20:17:44.175"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

PUT/api/v4/people/<personId>/employee

Actualizar datos de empleado

Este endpoint actualiza los datos de empleado de una persona por su id.

Modelo

Name
employerPersonId
Type
string
required
Description
Id de la persona empleadora (patrón).
Name
employeePersonId
Type
string
required
Description
Id de la persona empleada.
Name
employeeNumber
Type
string
required
Description
Número de empleado asignado por el empleador.
Name
socialSecurityNumber
Type
string
required
Description
Número de seguridad social del empleado.
Name
laborRelationStartDate
Type
date
required
Description
Fecha de inicio de la relación laboral.
Name
satContractTypeId
Type
string
required
expandible
Description
Tipo de contrato entre el empleado y el empleador. Catálogo del SAT c_TipoContrato.
Type
enum:
Values
"01""02""03"
Name
satTaxRegimeTypeId
Type
string
required
expandible
Description
Tipo de régimen fiscal del empleado. Catálogo del SAT c_TipoRegimen.
Type
enum:
Values
"02""03""04"
Name
satWorkdayTypeId
Type
string
required
expandible
Description
Jornada de trabajo del empleado. Catálogo del SAT c_TipoJornada.
Type
enum:
Values
"01""02""03"
Name
satJobRiskId
Type
string
required
expandible
Description
Riesgo de trabajo del puesto del empleado. Catálogo del SAT c_RiesgoPuesto.
Type
enum:
Values
"1""2""3"
Name
satPaymentPeriodicityId
Type
string
required
expandible
Description
Periodicidad de pago del empleado. Catálogo del SAT c_PeriodicidadPago.
Type
enum:
Values
"01""02""03"
Name
satPayrollStateId
Type
string
required
expandible
Description
Entidad federativa donde el empleado labora. Catálogo del SAT c_Estado.
Type
enum:
Values
"AGU""BCN""BCS"
Name
seniority
Type
string
required
Description
Antigüedad del empleado como duración ISO 8601, en semanas o en años, meses y días. Ejemplo: P437W para 437 semanas o P1Y5M0D para 1 año y 5 meses.
Name
baseSalaryForContributions
Type
number
required
Description
Salario base de cotización o aportaciones del empleado. Debe estar entre 0 y 999,999,999,999.999999.
Name
integratedDailySalary
Type
number
required
Description
Salario diario integrado del empleado. Debe estar entre 0 y 999,999,999,999.999999.
Name
satBankId
Type
string?
expandible
Description
Banco donde el empleado recibe el pago de nómina. Catálogo del SAT c_Banco.
Type
enum:
Values
002006009
Name
satUnionizedStatusId
Type
string?
expandible
Description
Estado sindical del empleado. Catálogo del SAT c_Sindicalizado.
Type
enum:
Values
"Sí""No"
Name
position
Type
string?
Description
Puesto que ocupa el empleado.
Name
department
Type
string?
Description
Departamento donde labora el empleado.
Name
bankAccount
Type
string?
Description
Cuenta bancaria donde el empleado recibe el pago de nómina.
Name
subcontractorRfc
Type
string?
Description
RFC del subcontratista, cuando el empleado es subcontratado.
Name
timePercentage
Type
number?
Description
Porcentaje de tiempo de trabajo, cuando el empleado es subcontratado.

Errores

Todos los casos llegan como falla de validación en el campo que se indica.

Estado	Cuándo ocurre	Mensaje
400	baseSalaryForContributions es menor que 0. Falla en BaseSalaryForContributions.	SalarioBaseCotApor debe ser mayor o igual a 0.
400	baseSalaryForContributions es mayor que 999,999,999,999.999999. Falla en BaseSalaryForContributions.	SalarioBaseCotApor no puede ser mayor a 999999999999.999999.
400	integratedDailySalary es menor que 0. Falla en IntegratedDailySalary.	SalarioDiarioIntegrado debe ser mayor o igual a 0.
400	integratedDailySalary es mayor que 999,999,999,999.999999. Falla en IntegratedDailySalary.	SalarioDiarioIntegrado no puede ser mayor a 999999999999.999999.

Request

PUT

/api/v4/people/<personId>/employee

curl --location --request PUT 'https://test.fiscalapi.com/api/v4/people/54fc14ae-c88f-4afc-996b-0574d63341e2/employee' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '{
  "employerPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
  "employeePersonId": "54fc14ae-c88f-4afc-996b-0574d63341e2",
  "employeeNumber": "12345ABC",
  "satContractTypeId": "02",
  "satTaxRegimeTypeId": "02",
  "satPaymentPeriodicityId": "02",
  "satPayrollStateId": "AGU",
  "socialSecurityNumber": "123456789012345",
  "laborRelationStartDate": "2022-01-15T00:00:00",
  "satWorkdayTypeId": "01",
  "satJobRiskId": "2",
  "satBankId": "012",
  "satUnionizedStatusId": "Sí",
  "department": "Sistemas",
  "position": "Programador Jr.",
  "seniority": "P7Y3M7D",
  "bankAccount": "12345678901234567890",
  "baseSalaryForContributions": 290.22,
  "integratedDailySalary": 46.47,
  "subcontractorRfc": null,
  "timePercentage": null
}'

Response

{
    "data": {
        "employerPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
        "employeePersonId": "54fc14ae-c88f-4afc-996b-0574d63341e2",
        "employeeNumber": "12345ABC",
        "socialSecurityNumber": "123456789012345",
        "laborRelationStartDate": "2022-01-15T00:00:00.000",
        "satContractType": {
            "id": "02",
            "description": "Contrato de trabajo para obra determinada",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satTaxRegimeType": {
            "id": "02",
            "description": "Sueldos (Incluye ingresos señalados en la fraccion I del articulo 94 de LISR)",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satWorkdayType": {
            "id": "01",
            "description": "Diurna",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satJobRisk": {
            "id": "2",
            "description": "Clase II",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satPaymentPeriodicity": {
            "id": "02",
            "description": "Semanal",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satBank": {
            "id": "012",
            "description": "BBVA BANCOMER",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satPayrollState": {
            "id": "AGU",
            "description": "Aguascalientes",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satUnionizedStatus": {
            "id": "Sí",
            "description": "SI",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "department": "Sistemas",
        "position": "Programador Jr.",
        "bankAccount": "12345678901234567890",
        "baseSalaryForContributions": 290.22,
        "integratedDailySalary": 46.47,
        "subcontractorRfc": null,
        "timePercentage": 0
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

DELETE/api/v4/people/<personId>/employee

Eliminar datos de empleado

Este endpoint elimina los datos de empleado de una persona por su id.

Request

DELETE

/api/v4/people/<personId>/employee

curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/people/bef56254-0892-4558-95c3-f9c8729e4b0e/employee' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>' \
--data ''

Response

{
    "data": true,
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}