Nóminas
Es importante tomar en cuenta que para generar una nómina primero debemos contar al menos con un grupo de empleados y un empleado de no ser asi no podremos generar nuestras nominas la estructura para generar estos componentes es la siguiente:
- Generar un grupo de empleados
- Generar empleados
- Generar nominas
Puedes encontrar como generar empleados y grupos de empleados en los siguientes links:
Como crear un grupo de empleados
Como crear un empleado
Listar nóminas
A continuación se explican los métodos con los cuales podremos visualizar las Nóminas de nuestra cuenta.
Importante
Es importante tomar en cuenta que al listar las nóminas no existe distinción entre versiones de CFDI por lo que mostrara todas las nóminas disponibles en nuestra cuenta
Para mostrar las nominas se utilizan los siguientes 3 métodos:
- Consultar todas las nóminas de nuestra cuenta
- Consultar un grupo de nómina en especifico
- Consultar la nomina de cada empleado en particular
Tip
A continuación se explican mas a detalle las caracteristicas de estos métodos y funcionalidades
Consultar todas las nóminas
En este método funciona para consultar todo el historial de nóminas de nuestra cuenta y se muestra ordenado por fecha de forma descendente, obtendremos como respuesta un arreglo con los grupos de nomina que contienen a cada empleado en particular.
Construcción de la URL
Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)
Endpoint: /payroll/list
Ejemplo: https://facturaonline.com.mx/api/payroll/list
Tip
Para probar el ejemplo de código, necesitas cambiar "Tu API key" por la clave de API de tu cuenta, y "Tu Secret key" por la clave secreta correspondiente.
Ejemplo para consultar todas las nóminas
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '{ HOST }/payroll/list',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key: Tu API key',
'F-Secret-Key: Tu Secret key'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'GET',
'url': '{ HOST }/payroll/list',
'headers': {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{ HOST }/payroll/list"
payload = ""
headers = {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
require "uri"
require "json"
require "net/http"
url = URI("{ HOST }/payroll/list")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
response = http.request(request)
puts response.read_body
Respuesta
Ejemplo de respuesta exitosa.
{
"status": "success",
"data": [
{
"uid": "62559959918c3",
"grupo": "619ead8d6427a",
"inicia": "2022-04-01",
"termina": "2022-04-11",
"descripcion": "Nomina 6 v4.0",
"concepto": "Nomina 6 v4.0",
"status": 100,
"total": "46510.00",
"creada": "2022-04-12 10:20:40",
"errores": 2,
"timbradas": 0,
"registros": [
{
"uid": "62559959941ab",
"uuid": "",
"dias_trabajados": 11,
"total_percepciones": "15500.00",
"total_deducciones": "0.00",
"total": "15500.00",
"status_timbre": "error",
"employee_uid": "61c4b569c0baf",
"creada": "2022-04-12 10:20:40",
"folio": null,
"serie": "17321",
"percepciones": [
{
"tipo": "001",
"clave": "123456",
"descripcion_per": "Empleado 1",
"gravado_per": "15500.00",
"exento_per": "0.00",
"extra_tipo": null,
"extra_dias": null,
"extra_horas": null
}
],
"deducciones": []
},
{
"uid": "625599599b672",
"uuid": "",
"dias_trabajados": 11,
"total_percepciones": "31000.00",
"total_deducciones": "0.00",
"total": "31010.00",
"status_timbre": "error",
"employee_uid": "61c4b697c9b3f",
"creada": "2022-04-12 10:20:40",
"folio": null,
"serie": "17321",
"percepciones": [
{
"tipo": "001",
"clave": "123456",
"descripcion_per": "Empleado 2",
"gravado_per": "31000.00",
"exento_per": "0.00",
"extra_tipo": null,
"extra_dias": null,
"extra_horas": null
}
],
"deducciones": []
}
],
"version_cfdi": "4.0"
},
{
"uid": "625598bd098d4",
"grupo": "619ead8d6427a",
"inicia": "2022-02-01",
"termina": "2022-02-15",
"descripcion": "Nomina 6 v4.0",
"concepto": "Nomina 6 v4.0",
"status": 100,
"total": "46510.00",
"creada": "2022-04-12 10:18:04",
"errores": 2,
"timbradas": 0,
"registros": [
{
"uid": "625598bd10c6f",
"uuid": "",
"dias_trabajados": 15,
"total_percepciones": "15500.00",
"total_deducciones": "0.00",
"total": "15500.00",
"status_timbre": "error",
"employee_uid": "61c4b569c0baf",
"creada": "2022-04-12 10:18:04",
"folio": null,
"serie": "17321",
"percepciones": [
{
"tipo": "001",
"clave": "123456",
"descripcion_per": "Empleado 1",
"gravado_per": "15500.00",
"exento_per": "0.00",
"extra_tipo": null,
"extra_dias": null,
"extra_horas": null
}
],
"deducciones": []
}
],
"version_cfdi": "3.3"
}
]
}
Ejemplo de respuesta erronea
{
"status": "error",
"message": "La cuenta que intenta autenticarse no existe",
"Data": "$2y$10$8a9S8o8WeiRhPh1YT6bnXun6uPs1ZdiZBUHjGwSqn3X44mbYSmY4.",
"Secret": "$2y$10$c5KNUW06w8r9OhH4MVPNz.BgpQfjHVZjPPYsVbX13WPQZomnYtxq"
}
Aviso
El mensaje de error puede variar dependiendo el nodo en el que haya información incorrecta. Te sugerimos leer cuidadosamente el mensaje del error ya que en el mismo se indica donde es necesario corregir la información.
Consultar un grupo de nómina en especifico
En este método podremos consultar un grupo de nómina junto a los empleados que forman parte de ella, la respuesta es un arreglo con la información general de la nómina y dentro los arreglos correspondientes a cada empleado con su información.
Parámetro | Tipo | Requerido | Detalles |
---|---|---|---|
UID | String | Requerido | Es el identificador unico correspondiente al grupo de nómina |
Importante
Es importante tomar en cuenta que el UID correspondiente a el grupo de nómina es distinto a el UID de la nómina del empleado ya que el grupo de nómina contiene cada uno de los UID correspondientes a las nominas individuales de cada empleado
Construcción de la URL
Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)
Endpoint: /payroll/6206f3702bcdd/view
Ejemplo: https://facturaonline.com.mx/api/payroll/6206f3702bcdd/view
Tip
Para probar el ejemplo de código, necesitas cambiar "Tu API key" por la clave de API de tu cuenta, y "Tu Secret key" por la clave secreta correspondiente.
Ejemplo para consultar un grupo de nómina
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '{ HOST }/payroll/6206f3702bcdd/view',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key: Tu API key',
'F-Secret-Key: Tu Secret key'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'GET',
'url': '{ HOST }/payroll/6206f3702bcdd/view',
'headers': {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{ HOST }/payroll/6206f3702bcdd/view"
payload = ""
headers = {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
require "uri"
require "json"
require "net/http"
url = URI("{ HOST }/payroll/6206f3702bcdd/view")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
response = http.request(request)
puts response.read_body
Respuesta
Ejemplo de respuesta exitosa.
{
"status": "success",
"data": {
"uid": "6206f3702bcdd",
"grupo": "619ead8d6427a",
"inicia": "2022-02-01",
"termina": "2022-02-15",
"descripcion": "Nomina 6 v4.0",
"concepto": "Nomina 6 v4.0",
"status": 100,
"total": "46510.00",
"creada": "2022-02-11 17:36:43",
"errores": 0,
"timbradas": 2,
"registros": [
{
"uid": "6206f370306ae",
"uuid": "e270f5f2-14a8-42ef-9022-e6d93ea31781",
"dias_trabajados": 15,
"total_percepciones": "15500.00",
"total_deducciones": "0.00",
"total": "15500.00",
"status_timbre": "cancelada",
"employee_uid": "61c4b569c0baf",
"creada": "2022-04-11 15:38:15",
"folio": 58,
"serie": "NOM",
"percepciones": [
{
"tipo": "001",
"clave": "123456",
"descripcion_per": "Empleado 1",
"gravado_per": "15500.00",
"exento_per": "0.00",
"extra_tipo": null,
"extra_dias": null,
"extra_horas": null
}
],
"deducciones": [],
"otrospagos": [
{
"tipo": "002",
"clave": "123456",
"descripcion_otros": "descripcion prueba",
"importe": "0.00"
}
]
},
{
"uid": "6206f370394f4",
"uuid": "9728d285-a060-47db-b261-eae9ab39dae8",
"dias_trabajados": 15,
"total_percepciones": "31000.00",
"total_deducciones": "0.00",
"total": "31010.00",
"status_timbre": "cancelada",
"employee_uid": "61c4b697c9b3f",
"creada": "2022-04-11 15:03:56",
"folio": 59,
"serie": "NOM",
"percepciones": [
{
"tipo": "001",
"clave": "123456",
"descripcion_per": "Empleado 2",
"gravado_per": "31000.00",
"exento_per": "0.00",
"extra_tipo": null,
"extra_dias": null,
"extra_horas": null
}
],
"deducciones": [],
"otrospagos": [
{
"tipo": "002",
"clave": "123456",
"descripcion_otros": "descripcion prueba",
"importe": "10.00"
}
]
}
],
"version_cfdi": "4.0"
}
}
Ejemplo de respuesta erronea
{
"status": "error",
"message": "La cuenta que intenta autenticarse no existe",
"Data": "$2y$10$8a9S8o8WeiRhPh1YT6bnXun6uPs1ZdiZBUHjGwSqn3X44mbYSmY4.",
"Secret": "$2y$10$c5KNUW06w8r9OhH4MVPNz.BgpQfjHVZjPPYsVbX13WPQZomnYtxq"
}
Aviso
El mensaje de error puede variar dependiendo el nodo en el que haya información incorrecta. Te sugerimos leer cuidadosamente el mensaje del error ya que en el mismo se indica donde es necesario corregir la información.
Consultar la nómina de un empleado en especifico
En este método podremos consultar la nómina de un empleado en particular correspondiente a un solo grupo de nomina, la respuesta regresa un arreglo que contiene la informacion general del empleado y los datos correspondiente a su nómina
Podemos consultar un grupo de nómina haciendo uso de los siguientes parametros:
Parámetro | Tipo | Requerido | Detalles |
---|---|---|---|
UID | String | Requerido | Es el identificador unico correspondiente a la nómina del empleado en particular |
Importante
Es importante tomar en cuenta que el UID correspondiente a el grupo de nómina es distinto a el UID de la nómina del empleado ya que el grupo de nómina contiene cada uno de los UID correspondientes a las nominas individuales de cada empleado
Construcción de la URL
Ejemplo para consultar la nómina de un empleado
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '{ HOST }/payroll/6206f370394f4/view/item',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key: Tu API key',
'F-Secret-Key: Tu Secret key'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'GET',
'url': '{ HOST }/payroll/6206f370394f4/view/item',
'headers': {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{ HOST }/payroll/6206f370394f4/view/item"
payload = ""
headers = {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
require "uri"
require "json"
require "net/http"
url = URI("{ HOST }/payroll/6206f370394f4/view/item")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
response = http.request(request)
puts response.read_body
Respuesta
Ejemplo de respuesta exitosa.
{
"status": "success",
"data": {
"uid": "6206f370394f4",
"uuid": "9728d285-a060-47db-b261-eae9ab39dae8",
"dias_trabajados": 15,
"total_percepciones": "31000.00",
"total_deducciones": "0.00",
"total": "31010.00",
"status_timbre": "cancelada",
"employee_uid": "61c4b697c9b3f",
"creada": "2022-04-11 15:03:56",
"folio": 59,
"serie": "NOM",
"version_cfdi": "4.0",
"percepciones": [
{
"tipo": "001",
"clave": "123456",
"descripcion": "Empleado 2",
"gravado": "31000.00",
"exento": "0.00",
"extra_tipo": null,
"extra_dias": null,
"extra_horas": null
}
],
"deducciones": [],
"otrospagos": [
{
"tipo": "002",
"clave": "123456",
"descripcion_otros": "asd",
"importe": "10.00"
}
]
}
}
Ejemplo de respuesta erronea
{
"status": "error",
"message": "La cuenta que intenta autenticarse no existe",
"Data": "$2y$10$8a9S8o8WeiRhPh1YT6bnXun6uPs1ZdiZBUHjGwSqn3X44mbYSmY4.",
"Secret": "$2y$10$c5KNUW06w8r9OhH4MVPNz.BgpQfjHVZjPPYsVbX13WPQZomnYtxq"
}
Aviso
El mensaje de error puede variar dependiendo el nodo en el que haya información incorrecta. Te sugerimos leer cuidadosamente el mensaje del error ya que en el mismo se indica donde es necesario corregir la información.
Crear nómina
A continuación se explica el método con el cual podremos crear una nómina
Aviso
Es importante tomar en cuenta que para poder crear una nómina debemos contar con al menos un grupo de empleados y un empleado activos de no ser asi no podremos generar nóminas, puedes consultar como generar grupos de empleados y empleados en los siguientes links
Como crear un grupo de empleados
Como crear un empleado
Podemos crear una nómina haciendo uso de los siguientes parametros:
Parámetro | Tipo | Requerido | Detalles |
---|---|---|---|
grupo | String | Requerido | UID del grupo de empleados que se utilizara para la nómina, al definir el grupo de empleados que se utilizara para la nómina unicamente los empleados que pertenecen a este grupo seran admitidos para timbrar |
fecha_pago | String | Requerido | Indica la fecha en la que se realiza el pago de la nómima En este campo se utiliza el siguiente formato para la fecha Ejemplo: "fecha_pago": "2022-12-02" |
num_dias | Numerico | Requerido | El numero de dias que cubre la nómina o dias trabajados |
incial | String | Requerido | Indica la fecha en la que inicia el periodo de nómina En este campo se utiliza el siguiente formato para la fecha Ejemplo: "fecha_pago": "2022-12-02 |
final | String | Requerido | Indica la fecha en la que termina el periodo de nómina En este campo se utiliza el siguiente formato para la fecha Ejemplo: "fecha_pago": "2022-12-02 |
tipo_nomina | String | Requerido | Indica si la nómina es de tipo "Ordinaria" o "Extraordinaria" Utiliza los valores: "O" para ordinaria "E" para extraordinaria (Si es de este tipo, el sistema en automático va a cambiar el valor del campo PeriodicidadPago a 99) |
descripcion | String | Requerido | Espacio para agregar una descripcion a la nómina |
serie | Numerico | Requerido | Indica id de la serie con la que deseas timbrar el documento. Ésta debe estar dada de alta en tu panel de Factura Online y coincidir con el tipo de CFDI que deseas timbrar. Para obtenerlo Inicia sesión y dirígete al Menú lateral - Configuraciones - Series y folios Ejemplo:
|
concepto | String | Requerido | Concepto que se muestra en la nómina de cada empleado |
identificador | String | Opcional | Indica un identificador personalizado para la nómina |
version_cfdi | String | Requerido | Se utiliza para definir en que version de CFDI se debe timbrar la nómina Admite los valores "3.3" y "4.0" |
registros | Arreglo | Requerido | Arreglo que contiene los datos de los empleados para la nómina |
data | Arreglo | Requerido | Hace referencia a la informacion del empleado y contiene los siguientes valores: "data": { |
id | String | Requerido | UID del empleado al cual se genera la nómina, este empleado debe existir en el grupo de empleados que se define al inicio |
dias | String | Requerido | Indica el numero de dias pagados a el empleado |
percepciones | Arreglo | Requerido | Arreglo que contiene las perceopciones del empleado |
deducciones | Arreglo | Opcional | Arreglo que contiene las deducciones del empleado |
tipo | String | Requerido | Inica el tipo de percepción o deducción que recibira el empleado en la nómina El tipo de deducción puedes consultarlo en este catalogo. |
clave | String | Requerido | Clave de control definida por el patron, es un campo libre para definir algun dato para su control |
descripcion | String | Requerido | Descripcion relacionada a la percepción o deducción del empleado |
exento | String | Requerido | Cantidad exenta en la percepción o deducción del empleado |
gravado | String | Requerido | Cantidad gravada en la percepción o deducción del empleado |
Incapacidad | Arreglo | Opcional | Arreglo que contiene los conceptos de incapacidades relacionadas a la nómina del empleado |
DiasIncapacidad | String | Opcional | Indica los dias de incapacidad que se integraran a la nómina |
TipoIncapacidad | String | Opcional | Indica el tipo de incapacidad que sufrio el empleado en el periodo Ésta puedes consultarla aqui. |
ImporteMonetario | Numerico | Opcional | Indica la cantidad que corresponde a la incapacidad descrita |
Construcción de la URL
Importante
El método que se utiliza para la creación de una nómina de tipo POST
Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)
Endpoint: /payroll/create
Ejemplo: https://facturaonline.com.mx/api/payroll/create
Tip
Para probar el ejemplo de código, necesitas cambiar "Tu API key" por la clave de API de tu cuenta, y "Tu Secret key" por la clave secreta correspondiente.
Ejemplo para crear una nueva nómina
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '{ HOST }/payroll/create',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"grupo": "6660e2c11e1cb",
"fecha_pago": "2024-09-02",
"num_dias": "1",
"inicial": "2024-09-02",
"final": "2024-09-02",
"tipo_nomina": "O",
"descripcion": "VIATICOS",
"serie": "NOM",
"concepto": "VIATICOS",
"identificador": "VIATICOS",
"version_cfdi": "4.0",
"registros": [
{
"data": {
"id": "6660e385cfb0b",
"nombre": "NOMBRE DEL EMPLEADO",
"puesto": "PUESTO DEL EMPLEADO",
"salario": null,
"dias": 1
},
"percepciones": [
{
"tipo": "050",
"clave": "050",
"descripcion": "VIATICOS",
"exento": "1435",
"gravado": "0.00"
}
],
"deducciones": [
{
"tipo": "081",
"clave": "081",
"importe": "1435",
"descripcion": "AJUSTE EN VIATICOS ENTREGADOS AL TRABAJADOR",
"Incapacidad": {
"DiasIncapacidad": "",
"TipoIncapacidad": "",
"ImporteMonetario": ""
}
}
]
}
]
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key: Tu API key',
'F-Secret-Key: Tu Secret key'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'POST',
'url': '{ HOST }/payroll/create',
'headers': {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
},
body: JSON.stringify({
"grupo": "6660e2c11e1cb",
"fecha_pago": "2024-09-02",
"num_dias": "1",
"inicial": "2024-09-02",
"final": "2024-09-02",
"tipo_nomina": "O",
"descripcion": "VIATICOS",
"serie": "NOM",
"concepto": "VIATICOS",
"identificador": "VIATICOS",
"version_cfdi": "4.0",
"registros": [
{
"data": {
"id": "6660e385cfb0b",
"nombre": "NOMBRE DEL EMPLEADO",
"puesto": "PUESTO DEL EMPLEADO",
"salario": null,
"dias": 1
},
"percepciones": [
{
"tipo": "050",
"clave": "050",
"descripcion": "VIATICOS",
"exento": "1435",
"gravado": "0.00"
}
],
"deducciones": [
{
"tipo": "081",
"clave": "081",
"importe": "1435",
"descripcion": "AJUSTE EN VIATICOS ENTREGADOS AL TRABAJADOR",
"Incapacidad": {
"DiasIncapacidad": "",
"TipoIncapacidad": "",
"ImporteMonetario": ""
}
}
]
}
]
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{ HOST }/payroll/create"
payload = json.dumps({
"grupo": "6660e2c11e1cb",
"fecha_pago": "2024-09-02",
"num_dias": "1",
"inicial": "2024-09-02",
"final": "2024-09-02",
"tipo_nomina": "O",
"descripcion": "VIATICOS",
"serie": "NOM",
"concepto": "VIATICOS",
"identificador": "VIATICOS",
"version_cfdi": "4.0",
"registros": [
{
"data": {
"id": "6660e385cfb0b",
"nombre": "NOMBRE DEL EMPLEADO",
"puesto": "PUESTO DEL EMPLEADO",
"salario": None,
"dias": 1
},
"percepciones": [
{
"tipo": "050",
"clave": "050",
"descripcion": "VIATICOS",
"exento": "1435",
"gravado": "0.00"
}
],
"deducciones": [
{
"tipo": "081",
"clave": "081",
"importe": "1435",
"descripcion": "AJUSTE EN VIATICOS ENTREGADOS AL TRABAJADOR",
"Incapacidad": {
"DiasIncapacidad": "",
"TipoIncapacidad": "",
"ImporteMonetario": ""
}
}
]
}
]
})
headers = {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
require "uri"
require "json"
require "net/http"
url = URI("{ HOST }/payroll/create")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
request.body = JSON.dump({
"grupo": "6660e2c11e1cb",
"fecha_pago": "2024-09-02",
"num_dias": "1",
"inicial": "2024-09-02",
"final": "2024-09-02",
"tipo_nomina": "O",
"descripcion": "VIATICOS",
"serie": "NOM",
"concepto": "VIATICOS",
"identificador": "VIATICOS",
"version_cfdi": "4.0",
"registros": [
{
"data": {
"id": "6660e385cfb0b",
"nombre": "NOMBRE DEL EMPLEADO",
"puesto": "PUESTO DEL EMPLEADO",
"salario": "__RUBY\#%0NULL__",
"dias": 1
},
"percepciones": [
{
"tipo": "050",
"clave": "050",
"descripcion": "VIATICOS",
"exento": "1435",
"gravado": "0.00"
}
],
"deducciones": [
{
"tipo": "081",
"clave": "081",
"importe": "1435",
"descripcion": "AJUSTE EN VIATICOS ENTREGADOS AL TRABAJADOR",
"Incapacidad": {
"DiasIncapacidad": "",
"TipoIncapacidad": "",
"ImporteMonetario": ""
}
}
]
}
]
})
response = http.request(request)
puts response.read_body
Respuesta
Ejemplo de respuesta exitosa.
{
"response": "success",
"message": "Nómina agregada a la fila de timbrado.",
"uid": "6257c33b8c944"
}
Ejemplo de respuesta erronea.
{
"status": "error",
"message": "La cuenta que intenta autenticarse no existe",
"Data": "$2y$10$8a9S8o8WeiRhPh1YT6bnXun6uPs1ZdiZBUHjGwSqn3X44mbYSmY4.",
"Secret": "$2y$10$c5KNUW06w8r9OhH4MVPNz.BgpQfjHVZjPPYsVbX13WPQZomnYtxq"
}
Aviso
El mensaje de error puede variar dependiendo el nodo en el que haya información incorrecta. Te sugerimos leer cuidadosamente el mensaje del error ya que en el mismo se indica donde es necesario corregir la información.
Cancelar una nómina
A continuación se explica el método con el cual podremos cancelar una nómina.
Importante
Es importante tomar en cuenta que cada nómina de cada empleado en particular corresponde a un CFDI por lo que al cancelar una nómina se esta cancelando solo el comprobante correspondiente a un solo empleado, por lo que si necesitamos cancelar todo el grupo de nómina deberemos cancelar cada uno de los comprobantes
Podemos cancelar una nómina utilizando los siguientes parametros
Parámetro | Tipo | Requerido | Detalles |
---|---|---|---|
UID | String | Requerido | Es el identificador unico asignado a la nómina que deseamos cancelar |
motivo | string | Requerido | Indica motivo por el cual es solicitada la cancelación del CFDI. |
folioSustituto | string | Requerido | Indica el UID o UUID del CFDI que reemplazara el CFDI cancelado. Ejemplo: |
Construcción de la URL
Importante
El método que se utiliza para cancelar una nómina es de tipo POST
Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)
Endpoint: /payroll/UID/cancel
Ejemplo: https://facturaonline.com.mx/api/payroll/UID/cancel
Tip
Para probar el ejemplo de código, necesitas cambiar "Tu API key" por la clave de API de tu cuenta, y "Tu Secret key" por la clave secreta correspondiente.
Ejemplo para cancelar una nómina
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '{ HOST }/payroll/6206eec5d2ac3/item/cancel',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"motivo": "02",
"folioSustituto": "6206eec5d7cd4"
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key: Tu API key',
'F-Secret-Key: Tu Secret key'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'POST',
'url': '{ HOST }/payroll/6206eec5d2ac3/item/cancel',
'headers': {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
},
body: JSON.stringify({
"motivo": "02",
"folioSustituto": "6206eec5d7cd4"
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{ HOST }/payroll/6206eec5d2ac3/item/cancel"
payload = json.dumps({
"motivo": "02",
"folioSustituto": "6206eec5d7cd4"
})
headers = {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
require "uri"
require "json"
require "net/http"
url = URI("{ HOST }/payroll/6206eec5d2ac3/item/cancel")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
request.body = JSON.dump({
"motivo": "02",
"folioSustituto": "6206eec5d7cd4"
})
response = http.request(request)
puts response.read_body
Respuesta
Ejemplo de respuesta exitosa.
{
"response": "success",
"uid": "61c4b569c0baf",
"message": "Nomina de empleado cancelada satisfactoriamente"
}
Ejemplo de respuesta erronea.
{
"status": "error",
"message": "La cuenta que intenta autenticarse no existe",
"Data": "$2y$10$8a9S8o8WeiRhPh1YT6bnXun6uPs1ZdiZBUHjGwSqn3X44mbYSmY4.",
"Secret": "$2y$10$c5KNUW06w8r9OhH4MVPNz.BgpQfjHVZjPPYsVbX13WPQZomnYtxq"
}
Aviso
El mensaje de error puede variar dependiendo el nodo en el que haya información incorrecta. Te sugerimos leer cuidadosamente el mensaje del error ya que en el mismo se indica donde es necesario corregir la información.
Descargar nómina
A continuación se explica como descargar una nómina
Cada nómina puede ser descargado a través de nuestra API en dos tipos de archivo distintos:
- XML
Para obtener uno u otro solo es necesario cambiar el endpoint al que estamos apuntando:
- /xml
Tambien para descargar una nómina es necesario el uso del siguiente parámetro el cual se utiliza en la construcción del enpoint para identificar la nómina que deseamos descargar:
Parámetro | Tipo | Requerido | Detalles |
---|---|---|---|
cfdi_uid | string | Requerido | Indica el UID o UUID de la nómina que deseas descargar. Ejemplo: 55c0fdc67593d |
Construcción de la URL
Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)
Endpoint PDF: /payroll/UID/item/pdf Endpoint XML: /payroll/UID/item/xml
Ejemplo: https://facturaonline.com.mx/api/payroll/55c0fdc67593d/item/pdf
Tip
Para probar el código de ejemplo es necesario que reemplaces el texto Tu API key por el API KEY de tu cuenta e Tu Secret key por el SECRET KEY correspondiente.
Además de reemplazar UID por el UID de la nómina que deseas descargar.
Ejemplo para descargar una nómina en formato XML
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '{ HOST }/payroll/6206f370394f4/item/xml',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key: Tu API key',
'F-Secret-Key: Tu Secret key'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'GET',
'url': '{ HOST }/payroll/6206f370394f4/item/xml',
'headers': {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{ HOST }/payroll/6206f370394f4/item/xml"
payload = ""
headers = {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
require "uri"
require "json"
require "net/http"
url = URI("{ HOST }/payroll/6206f370394f4/item/xml")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
response = http.request(request)
puts response.read_body
Enviar una nómina por email
A continuación se explica el método con el cual podremos enviar por email una nómina.
Importante
Es importante tomar en cuenta que cada nómina de cada empleado en particular corresponde a un CFDI por lo que al enviar una nómina se esta enviando solo el comprobante correspondiente a un solo empleado, por lo que si necesitamos enviar todo el grupo de nómina deberemos enviar cada uno de los comprobantes
Podemos enviar una nómina utilizando los siguientes parametros
Parámetro | Tipo | Requerido | Detalles |
---|---|---|---|
UID | String | Requerido | Es el identificador unico asignado a la nómina que deseamos enviar |
Construcción de la URL
Importante
El método que se utiliza para enviar una nómina es de tipo POST
Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)
Endpoint: /payroll/UID/item/email
Ejemplo: https://facturaonline.com.mx/api/payroll/UID/item/email
Tip
Para probar el ejemplo de código, necesitas cambiar "Tu API key" por la clave de API de tu cuenta, y "Tu Secret key" por la clave secreta correspondiente.
Ejemplo para enviar una nómina
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '{ HOST }/payroll/6206f370394f4/item/email',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key: Tu API key',
'F-Secret-Key: Tu Secret key'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'POST',
'url': '{ HOST }/payroll/6206f370394f4/item/email',
'headers': {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{ HOST }/payroll/6206f370394f4/item/email"
payload = ""
headers = {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
require "uri"
require "json"
require "net/http"
url = URI("{ HOST }/payroll/6206f370394f4/item/email")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
response = http.request(request)
puts response.read_body
Respuesta
Ejemplo de respuesta exitosa.
{
"response": "success",
"uid": "61c4b697c9b3f",
"message": "Hemos enviado tu Nomina con exito al e-mail: [email protected]"
}
Ejemplo de respuesta erronea.
{
"status": "error",
"message": "La cuenta que intenta autenticarse no existe",
"Data": "$2y$10$8a9S8o8WeiRhPh1YT6bnXun6uPs1ZdiZBUHjGwSqn3X44mbYSmY4.",
"Secret": "$2y$10$c5KNUW06w8r9OhH4MVPNz.BgpQfjHVZjPPYsVbX13WPQZomnYtxq"
}
Aviso
El mensaje de error puede variar dependiendo el nodo en el que haya información incorrecta. Te sugerimos leer cuidadosamente el mensaje del error ya que en el mismo se indica donde es necesario corregir la información.
Descargar acuse de una nómina
A continuación se explica el método con el cual podremos descargar el acuse de cancelación de una nómina.
Importante
Es importante tomar en cuenta que cada nómina de cada empleado en particular corresponde a un CFDI por lo que al descargar el acuse de una nómina se esta solicitando solo el comprobante correspondiente a un solo empleado, por lo que si necesitamos los acuses de todo el grupo de nómina deberemos solicitar cada uno de los comprobantes
Podemos descargar el acuse de una nómina utilizando los siguientes parametros
Parámetro | Tipo | Requerido | Detalles |
---|---|---|---|
UID | String | Requerido | Es el identificador unico asignado a la nómina que deseamos enviar |
Construcción de la URL
Importante
El método que se utiliza para descargar el acuse de una nómina es de tipo GET
Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)
Endpoint: /payroll/UID/item/acuse
Ejemplo: https://facturaonline.com.mx/api/payroll/UID/item/acuse
Tip
Para probar el ejemplo de código, necesitas cambiar "Tu API key" por la clave de API de tu cuenta, y "Tu Secret key" por la clave secreta correspondiente.
Ejemplo para descargar el acuse de una nómina
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '{ HOST }/payroll/6206f370394f4/item/acuse',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key: Tu API key',
'F-Secret-Key: Tu Secret key'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'GET',
'url': '{ HOST }/payroll/6206f370394f4/item/acuse',
'headers': {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{ HOST }/payroll/6206f370394f4/item/acuse"
payload = ""
headers = {
'Content-Type': 'application/json',
'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
'F-Api-Key': 'Tu API key',
'F-Secret-Key': 'Tu Secret key'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
require "uri"
require "json"
require "net/http"
url = URI("{ HOST }/payroll/6206f370394f4/item/acuse")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
response = http.request(request)
puts response.read_body
Respuesta
Ejemplo de respuesta exitosa.
<?xml version="1.0" encoding="utf-8"?>
<Acuse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Fecha="2022-04-11T15:06:00.8822769" RfcEmisor="XOJI740919U48">
<Folios xmlns="http://cancelacfd.sat.gob.mx">
<UUID>9728D285-A060-47DB-B261-EAE9AB39DAE8</UUID>
<EstatusUUID>201</EstatusUUID>
</Folios>
<Signature Id="SelloSAT" xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#hmac-sha512" />
<Reference URI="">
<Transforms>
<Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
<XPath>not(ancestor-or-self::*[local-name()='Signature'])</XPath>
</Transform>
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512" />
<DigestValue>3mh05i9bjnBDjK61RU2om6y8dNWo3TKzcWWCoiJV26h1klWiz2cdOKptxG4U90ffMM4Ajvz8b2IPtUWgaU/McQ==</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>qux5QPlwYbASZCVNW9vzyl1DITHGUgEroc9DMzcBwXiG15XL8+r8u8Q02iEJkxgbqEaykHqys2OQMBhOBCaj3w==</SignatureValue>
<KeyInfo>
<KeyName>BF66E582888CC845</KeyName>
<KeyValue>
<RSAKeyValue>
<Modulus>n5YsGT0w5Z70ONPbqszhExfJU+KY3Bscftc2jxUn4wxpSjEUhnCuTd88OK5QbDW3Mupoc61jr83lRhUCjchFAmCigpC10rEntTfEU+7qtX8ud/jJJDB1a9lTIB6bhBN//X8IQDjhmHrfKvfen3p7RxLrFoxzWgpwKriuGI5wUlU=</Modulus>
<Exponent>AQAB</Exponent>
</RSAKeyValue>
</KeyValue>
</KeyInfo>
</Signature>
</Acuse>
Ejemplo de respuesta erronea.
{
"status": "error",
"message": "La cuenta que intenta autenticarse no existe",
"Data": "$2y$10$8a9S8o8WeiRhPh1YT6bnXun6uPs1ZdiZBUHjGwSqn3X44mbYSmY4.",
"Secret": "$2y$10$c5KNUW06w8r9OhH4MVPNz.BgpQfjHVZjPPYsVbX13WPQZomnYtxq"
}
Aviso
El mensaje de error puede variar dependiendo el nodo en el que haya información incorrecta. Te sugerimos leer cuidadosamente el mensaje del error ya que en el mismo se indica donde es necesario corregir la información.