Listar empleados

GET

/employees

FACTUCAT_API_URL="${FACTUCAT_API_URL:-https://sandbox.factucat.com/api/v1}"

curl --fail-with-body --request GET \
  --url "$FACTUCAT_API_URL/employees" \
  --header "X-API-Key: $FACTUCAT_API_KEY"

• Sandbox
• Producción

Solo lectura. Requiere payroll:read y acceso a nómina de Plan Miau. Despacho en modo de solo lectura conserva acceso. OAuth usa el espacio seleccionado al autorizar; las API keys usan su cuenta propietaria. CURP, NSS y cuenta bancaria se enmascaran salvo en los documentos fiscales XML y PDF.

Authorizations

• apiKeyAuth
• payrollOAuth

Parameters

Query Parameters

status

string

Allowed values: active inactive

q

string

>= 1 characters <= 120 characters

cursor

string

/^(0|[1-9]\d*)$/

limit

integer

>= 1 <= 100

Responses

200

Operación exitosa

Media typeapplication/json

object

data

required

Array<object>

object

id

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

userId

required

string

>= 1 characters

employeeNumber

required

string

fullName

required

string

rfc

required

string

curp

required

string

postalCode

required

string

fiscalRegime

required

string

email

string format: email

/^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/

status

required

string

Allowed values: active inactive

department

string

position

string

hireDate

string

contractType

required

string

payrollRegimeType

required

string

paymentPeriodicity

required

string

netSalaryPeriod

number

> 0

grossSalaryPeriod

number

> 0

integratedDailySalary

number

> 0

federalEntityCode

required

string

socialSecurityNumber

required

string | null

bankCode

string

bankAccount

required

string | null

retainImss

required

boolean

terminatedAt

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/

createdAt

required

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/

updatedAt

required

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/

meta

required

object

requestId

required

string

>= 1 characters

idempotencyKey

string

>= 1 characters

pagination

object

limit

required

integer

> 0 <= 9007199254740991

offset

required

integer

<= 9007199254740991

hasMore

required

boolean

nextCursor

string | null

400

Datos inválidos

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

401

API key ausente, inválida o de otro ambiente

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

403

Plan inactivo o permisos insuficientes

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

404

Recurso no encontrado

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

405

Método no permitido

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

409

Conflicto o solicitud en curso. error.reason es opcional; duplicate_rfc indica que ya existe un cliente con ese RFC en la cuenta; stamp_in_progress indica que el documento se está timbrando: consúltalo antes de reintentar.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

429

Límite de solicitudes alcanzado

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

Headers

Retry-After

integer

Segundos antes de reintentar.

500

Error interno

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string

503

PAC temporalmente no disponible

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: bad_request conflict csd_required forbidden internal_error pac_unavailable invalid_api_key invalid_json method_not_allowed missing_api_key missing_idempotency_key missing_scope not_found plan_required rate_limit_exceeded validation_error invalid_input INVALID_ISSUE_DATE idempotency_conflict idempotency_in_progress

message

required

string

>= 1 characters

requestId

required

string

>= 1 characters

retryable

required

boolean

reason

string