Timbrar CFDI de nómina
curl --request POST \
--url https://api.ipsofactura.com/cfdi/timbrar-nomina \
--header 'Content-Type: application/json' \
--header 'x-api: <api-key>' \
--data '
{
"folio": "2026-001",
"idempotency_key": "nomina-emp-42-2026-09",
"nomina": {
"deducciones": [
{
"clave": "IMSSEmp",
"concepto": "Cuota IMSS empleado",
"importe": 1000,
"tipo_deduccion": "001"
},
{
"clave": "ISR",
"concepto": "ISR",
"importe": 800,
"tipo_deduccion": "002"
}
],
"empleado": {
"curp": "VECJ880326HDFXXX01",
"num_empleado": "EMP-042",
"num_seguridad_social": "12345678901",
"periodicidad_pago": "04",
"tipo_contrato": "01",
"tipo_jornada": "01",
"tipo_regimen": "02"
},
"empleador": {
"registro_patronal": "A1234567890"
},
"fecha_final_pago": "2026-09-15",
"fecha_inicial_pago": "2026-09-01",
"fecha_pago": "2026-09-15",
"num_dias_pagados": 15,
"percepciones": [
{
"clave": "001",
"concepto": "Sueldo",
"importe_exento": 2000,
"importe_gravado": 10000,
"tipo_percepcion": "001"
}
],
"tipo_nomina": "O",
"total_deducciones": 1800,
"total_otros_pagos": 0,
"total_percepciones": 12000
},
"receptor": {
"domicilio_fiscal": "06600",
"nombre": "JUAN VECTOR",
"rfc": "VECJ880326XXX"
},
"rfc_emisor": "AAA010101AAA",
"serie": "NOM"
}
'import requests
url = "https://api.ipsofactura.com/cfdi/timbrar-nomina"
payload = {
"folio": "2026-001",
"idempotency_key": "nomina-emp-42-2026-09",
"nomina": {
"deducciones": [
{
"clave": "IMSSEmp",
"concepto": "Cuota IMSS empleado",
"importe": 1000,
"tipo_deduccion": "001"
},
{
"clave": "ISR",
"concepto": "ISR",
"importe": 800,
"tipo_deduccion": "002"
}
],
"empleado": {
"curp": "VECJ880326HDFXXX01",
"num_empleado": "EMP-042",
"num_seguridad_social": "12345678901",
"periodicidad_pago": "04",
"tipo_contrato": "01",
"tipo_jornada": "01",
"tipo_regimen": "02"
},
"empleador": { "registro_patronal": "A1234567890" },
"fecha_final_pago": "2026-09-15",
"fecha_inicial_pago": "2026-09-01",
"fecha_pago": "2026-09-15",
"num_dias_pagados": 15,
"percepciones": [
{
"clave": "001",
"concepto": "Sueldo",
"importe_exento": 2000,
"importe_gravado": 10000,
"tipo_percepcion": "001"
}
],
"tipo_nomina": "O",
"total_deducciones": 1800,
"total_otros_pagos": 0,
"total_percepciones": 12000
},
"receptor": {
"domicilio_fiscal": "06600",
"nombre": "JUAN VECTOR",
"rfc": "VECJ880326XXX"
},
"rfc_emisor": "AAA010101AAA",
"serie": "NOM"
}
headers = {
"x-api": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
folio: '2026-001',
idempotency_key: 'nomina-emp-42-2026-09',
nomina: {
deducciones: [
{
clave: 'IMSSEmp',
concepto: 'Cuota IMSS empleado',
importe: 1000,
tipo_deduccion: '001'
},
{clave: 'ISR', concepto: 'ISR', importe: 800, tipo_deduccion: '002'}
],
empleado: {
curp: 'VECJ880326HDFXXX01',
num_empleado: 'EMP-042',
num_seguridad_social: '12345678901',
periodicidad_pago: '04',
tipo_contrato: '01',
tipo_jornada: '01',
tipo_regimen: '02'
},
empleador: {registro_patronal: 'A1234567890'},
fecha_final_pago: '2026-09-15',
fecha_inicial_pago: '2026-09-01',
fecha_pago: '2026-09-15',
num_dias_pagados: 15,
percepciones: [
{
clave: '001',
concepto: 'Sueldo',
importe_exento: 2000,
importe_gravado: 10000,
tipo_percepcion: '001'
}
],
tipo_nomina: 'O',
total_deducciones: 1800,
total_otros_pagos: 0,
total_percepciones: 12000
},
receptor: {domicilio_fiscal: '06600', nombre: 'JUAN VECTOR', rfc: 'VECJ880326XXX'},
rfc_emisor: 'AAA010101AAA',
serie: 'NOM'
})
};
fetch('https://api.ipsofactura.com/cfdi/timbrar-nomina', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ipsofactura.com/cfdi/timbrar-nomina",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'folio' => '2026-001',
'idempotency_key' => 'nomina-emp-42-2026-09',
'nomina' => [
'deducciones' => [
[
'clave' => 'IMSSEmp',
'concepto' => 'Cuota IMSS empleado',
'importe' => 1000,
'tipo_deduccion' => '001'
],
[
'clave' => 'ISR',
'concepto' => 'ISR',
'importe' => 800,
'tipo_deduccion' => '002'
]
],
'empleado' => [
'curp' => 'VECJ880326HDFXXX01',
'num_empleado' => 'EMP-042',
'num_seguridad_social' => '12345678901',
'periodicidad_pago' => '04',
'tipo_contrato' => '01',
'tipo_jornada' => '01',
'tipo_regimen' => '02'
],
'empleador' => [
'registro_patronal' => 'A1234567890'
],
'fecha_final_pago' => '2026-09-15',
'fecha_inicial_pago' => '2026-09-01',
'fecha_pago' => '2026-09-15',
'num_dias_pagados' => 15,
'percepciones' => [
[
'clave' => '001',
'concepto' => 'Sueldo',
'importe_exento' => 2000,
'importe_gravado' => 10000,
'tipo_percepcion' => '001'
]
],
'tipo_nomina' => 'O',
'total_deducciones' => 1800,
'total_otros_pagos' => 0,
'total_percepciones' => 12000
],
'receptor' => [
'domicilio_fiscal' => '06600',
'nombre' => 'JUAN VECTOR',
'rfc' => 'VECJ880326XXX'
],
'rfc_emisor' => 'AAA010101AAA',
'serie' => 'NOM'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ipsofactura.com/cfdi/timbrar-nomina"
payload := strings.NewReader("{\n \"folio\": \"2026-001\",\n \"idempotency_key\": \"nomina-emp-42-2026-09\",\n \"nomina\": {\n \"deducciones\": [\n {\n \"clave\": \"IMSSEmp\",\n \"concepto\": \"Cuota IMSS empleado\",\n \"importe\": 1000,\n \"tipo_deduccion\": \"001\"\n },\n {\n \"clave\": \"ISR\",\n \"concepto\": \"ISR\",\n \"importe\": 800,\n \"tipo_deduccion\": \"002\"\n }\n ],\n \"empleado\": {\n \"curp\": \"VECJ880326HDFXXX01\",\n \"num_empleado\": \"EMP-042\",\n \"num_seguridad_social\": \"12345678901\",\n \"periodicidad_pago\": \"04\",\n \"tipo_contrato\": \"01\",\n \"tipo_jornada\": \"01\",\n \"tipo_regimen\": \"02\"\n },\n \"empleador\": {\n \"registro_patronal\": \"A1234567890\"\n },\n \"fecha_final_pago\": \"2026-09-15\",\n \"fecha_inicial_pago\": \"2026-09-01\",\n \"fecha_pago\": \"2026-09-15\",\n \"num_dias_pagados\": 15,\n \"percepciones\": [\n {\n \"clave\": \"001\",\n \"concepto\": \"Sueldo\",\n \"importe_exento\": 2000,\n \"importe_gravado\": 10000,\n \"tipo_percepcion\": \"001\"\n }\n ],\n \"tipo_nomina\": \"O\",\n \"total_deducciones\": 1800,\n \"total_otros_pagos\": 0,\n \"total_percepciones\": 12000\n },\n \"receptor\": {\n \"domicilio_fiscal\": \"06600\",\n \"nombre\": \"JUAN VECTOR\",\n \"rfc\": \"VECJ880326XXX\"\n },\n \"rfc_emisor\": \"AAA010101AAA\",\n \"serie\": \"NOM\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.ipsofactura.com/cfdi/timbrar-nomina")
.header("x-api", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"folio\": \"2026-001\",\n \"idempotency_key\": \"nomina-emp-42-2026-09\",\n \"nomina\": {\n \"deducciones\": [\n {\n \"clave\": \"IMSSEmp\",\n \"concepto\": \"Cuota IMSS empleado\",\n \"importe\": 1000,\n \"tipo_deduccion\": \"001\"\n },\n {\n \"clave\": \"ISR\",\n \"concepto\": \"ISR\",\n \"importe\": 800,\n \"tipo_deduccion\": \"002\"\n }\n ],\n \"empleado\": {\n \"curp\": \"VECJ880326HDFXXX01\",\n \"num_empleado\": \"EMP-042\",\n \"num_seguridad_social\": \"12345678901\",\n \"periodicidad_pago\": \"04\",\n \"tipo_contrato\": \"01\",\n \"tipo_jornada\": \"01\",\n \"tipo_regimen\": \"02\"\n },\n \"empleador\": {\n \"registro_patronal\": \"A1234567890\"\n },\n \"fecha_final_pago\": \"2026-09-15\",\n \"fecha_inicial_pago\": \"2026-09-01\",\n \"fecha_pago\": \"2026-09-15\",\n \"num_dias_pagados\": 15,\n \"percepciones\": [\n {\n \"clave\": \"001\",\n \"concepto\": \"Sueldo\",\n \"importe_exento\": 2000,\n \"importe_gravado\": 10000,\n \"tipo_percepcion\": \"001\"\n }\n ],\n \"tipo_nomina\": \"O\",\n \"total_deducciones\": 1800,\n \"total_otros_pagos\": 0,\n \"total_percepciones\": 12000\n },\n \"receptor\": {\n \"domicilio_fiscal\": \"06600\",\n \"nombre\": \"JUAN VECTOR\",\n \"rfc\": \"VECJ880326XXX\"\n },\n \"rfc_emisor\": \"AAA010101AAA\",\n \"serie\": \"NOM\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ipsofactura.com/cfdi/timbrar-nomina")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"folio\": \"2026-001\",\n \"idempotency_key\": \"nomina-emp-42-2026-09\",\n \"nomina\": {\n \"deducciones\": [\n {\n \"clave\": \"IMSSEmp\",\n \"concepto\": \"Cuota IMSS empleado\",\n \"importe\": 1000,\n \"tipo_deduccion\": \"001\"\n },\n {\n \"clave\": \"ISR\",\n \"concepto\": \"ISR\",\n \"importe\": 800,\n \"tipo_deduccion\": \"002\"\n }\n ],\n \"empleado\": {\n \"curp\": \"VECJ880326HDFXXX01\",\n \"num_empleado\": \"EMP-042\",\n \"num_seguridad_social\": \"12345678901\",\n \"periodicidad_pago\": \"04\",\n \"tipo_contrato\": \"01\",\n \"tipo_jornada\": \"01\",\n \"tipo_regimen\": \"02\"\n },\n \"empleador\": {\n \"registro_patronal\": \"A1234567890\"\n },\n \"fecha_final_pago\": \"2026-09-15\",\n \"fecha_inicial_pago\": \"2026-09-01\",\n \"fecha_pago\": \"2026-09-15\",\n \"num_dias_pagados\": 15,\n \"percepciones\": [\n {\n \"clave\": \"001\",\n \"concepto\": \"Sueldo\",\n \"importe_exento\": 2000,\n \"importe_gravado\": 10000,\n \"tipo_percepcion\": \"001\"\n }\n ],\n \"tipo_nomina\": \"O\",\n \"total_deducciones\": 1800,\n \"total_otros_pagos\": 0,\n \"total_percepciones\": 12000\n },\n \"receptor\": {\n \"domicilio_fiscal\": \"06600\",\n \"nombre\": \"JUAN VECTOR\",\n \"rfc\": \"VECJ880326XXX\"\n },\n \"rfc_emisor\": \"AAA010101AAA\",\n \"serie\": \"NOM\"\n}"
response = http.request(request)
puts response.read_body{
"cadena_original_sat": "||1.1|...||",
"folio": "2026-001",
"id": "9a4f07ff-3abc-435f-b7a6-88c2bc65b4c1",
"numero_certificado_sat": "00001000000500000000",
"sello_cfdi": "...",
"sello_sat": "...",
"serie": "NOM",
"stamped_at": "2026-09-15T10:00:00",
"uuid": "6128396f-c09b-4ec6-8699-43da5a244971"
}CFDI
Timbrar CFDI de nómina
Genera, sella y timbra un CFDI 4.0 tipo N con complemento Nómina 1.2. Ipsofactura calcula el total como total_percepciones - total_deducciones + total_otros_pagos y valida los totales del detalle, periodo, CURP, NSS y días pagados. Es seguro reintentar con el mismo idempotency_key o con la misma serie y folio.
POST
/
cfdi
/
timbrar-nomina
Timbrar CFDI de nómina
curl --request POST \
--url https://api.ipsofactura.com/cfdi/timbrar-nomina \
--header 'Content-Type: application/json' \
--header 'x-api: <api-key>' \
--data '
{
"folio": "2026-001",
"idempotency_key": "nomina-emp-42-2026-09",
"nomina": {
"deducciones": [
{
"clave": "IMSSEmp",
"concepto": "Cuota IMSS empleado",
"importe": 1000,
"tipo_deduccion": "001"
},
{
"clave": "ISR",
"concepto": "ISR",
"importe": 800,
"tipo_deduccion": "002"
}
],
"empleado": {
"curp": "VECJ880326HDFXXX01",
"num_empleado": "EMP-042",
"num_seguridad_social": "12345678901",
"periodicidad_pago": "04",
"tipo_contrato": "01",
"tipo_jornada": "01",
"tipo_regimen": "02"
},
"empleador": {
"registro_patronal": "A1234567890"
},
"fecha_final_pago": "2026-09-15",
"fecha_inicial_pago": "2026-09-01",
"fecha_pago": "2026-09-15",
"num_dias_pagados": 15,
"percepciones": [
{
"clave": "001",
"concepto": "Sueldo",
"importe_exento": 2000,
"importe_gravado": 10000,
"tipo_percepcion": "001"
}
],
"tipo_nomina": "O",
"total_deducciones": 1800,
"total_otros_pagos": 0,
"total_percepciones": 12000
},
"receptor": {
"domicilio_fiscal": "06600",
"nombre": "JUAN VECTOR",
"rfc": "VECJ880326XXX"
},
"rfc_emisor": "AAA010101AAA",
"serie": "NOM"
}
'import requests
url = "https://api.ipsofactura.com/cfdi/timbrar-nomina"
payload = {
"folio": "2026-001",
"idempotency_key": "nomina-emp-42-2026-09",
"nomina": {
"deducciones": [
{
"clave": "IMSSEmp",
"concepto": "Cuota IMSS empleado",
"importe": 1000,
"tipo_deduccion": "001"
},
{
"clave": "ISR",
"concepto": "ISR",
"importe": 800,
"tipo_deduccion": "002"
}
],
"empleado": {
"curp": "VECJ880326HDFXXX01",
"num_empleado": "EMP-042",
"num_seguridad_social": "12345678901",
"periodicidad_pago": "04",
"tipo_contrato": "01",
"tipo_jornada": "01",
"tipo_regimen": "02"
},
"empleador": { "registro_patronal": "A1234567890" },
"fecha_final_pago": "2026-09-15",
"fecha_inicial_pago": "2026-09-01",
"fecha_pago": "2026-09-15",
"num_dias_pagados": 15,
"percepciones": [
{
"clave": "001",
"concepto": "Sueldo",
"importe_exento": 2000,
"importe_gravado": 10000,
"tipo_percepcion": "001"
}
],
"tipo_nomina": "O",
"total_deducciones": 1800,
"total_otros_pagos": 0,
"total_percepciones": 12000
},
"receptor": {
"domicilio_fiscal": "06600",
"nombre": "JUAN VECTOR",
"rfc": "VECJ880326XXX"
},
"rfc_emisor": "AAA010101AAA",
"serie": "NOM"
}
headers = {
"x-api": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
folio: '2026-001',
idempotency_key: 'nomina-emp-42-2026-09',
nomina: {
deducciones: [
{
clave: 'IMSSEmp',
concepto: 'Cuota IMSS empleado',
importe: 1000,
tipo_deduccion: '001'
},
{clave: 'ISR', concepto: 'ISR', importe: 800, tipo_deduccion: '002'}
],
empleado: {
curp: 'VECJ880326HDFXXX01',
num_empleado: 'EMP-042',
num_seguridad_social: '12345678901',
periodicidad_pago: '04',
tipo_contrato: '01',
tipo_jornada: '01',
tipo_regimen: '02'
},
empleador: {registro_patronal: 'A1234567890'},
fecha_final_pago: '2026-09-15',
fecha_inicial_pago: '2026-09-01',
fecha_pago: '2026-09-15',
num_dias_pagados: 15,
percepciones: [
{
clave: '001',
concepto: 'Sueldo',
importe_exento: 2000,
importe_gravado: 10000,
tipo_percepcion: '001'
}
],
tipo_nomina: 'O',
total_deducciones: 1800,
total_otros_pagos: 0,
total_percepciones: 12000
},
receptor: {domicilio_fiscal: '06600', nombre: 'JUAN VECTOR', rfc: 'VECJ880326XXX'},
rfc_emisor: 'AAA010101AAA',
serie: 'NOM'
})
};
fetch('https://api.ipsofactura.com/cfdi/timbrar-nomina', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ipsofactura.com/cfdi/timbrar-nomina",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'folio' => '2026-001',
'idempotency_key' => 'nomina-emp-42-2026-09',
'nomina' => [
'deducciones' => [
[
'clave' => 'IMSSEmp',
'concepto' => 'Cuota IMSS empleado',
'importe' => 1000,
'tipo_deduccion' => '001'
],
[
'clave' => 'ISR',
'concepto' => 'ISR',
'importe' => 800,
'tipo_deduccion' => '002'
]
],
'empleado' => [
'curp' => 'VECJ880326HDFXXX01',
'num_empleado' => 'EMP-042',
'num_seguridad_social' => '12345678901',
'periodicidad_pago' => '04',
'tipo_contrato' => '01',
'tipo_jornada' => '01',
'tipo_regimen' => '02'
],
'empleador' => [
'registro_patronal' => 'A1234567890'
],
'fecha_final_pago' => '2026-09-15',
'fecha_inicial_pago' => '2026-09-01',
'fecha_pago' => '2026-09-15',
'num_dias_pagados' => 15,
'percepciones' => [
[
'clave' => '001',
'concepto' => 'Sueldo',
'importe_exento' => 2000,
'importe_gravado' => 10000,
'tipo_percepcion' => '001'
]
],
'tipo_nomina' => 'O',
'total_deducciones' => 1800,
'total_otros_pagos' => 0,
'total_percepciones' => 12000
],
'receptor' => [
'domicilio_fiscal' => '06600',
'nombre' => 'JUAN VECTOR',
'rfc' => 'VECJ880326XXX'
],
'rfc_emisor' => 'AAA010101AAA',
'serie' => 'NOM'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ipsofactura.com/cfdi/timbrar-nomina"
payload := strings.NewReader("{\n \"folio\": \"2026-001\",\n \"idempotency_key\": \"nomina-emp-42-2026-09\",\n \"nomina\": {\n \"deducciones\": [\n {\n \"clave\": \"IMSSEmp\",\n \"concepto\": \"Cuota IMSS empleado\",\n \"importe\": 1000,\n \"tipo_deduccion\": \"001\"\n },\n {\n \"clave\": \"ISR\",\n \"concepto\": \"ISR\",\n \"importe\": 800,\n \"tipo_deduccion\": \"002\"\n }\n ],\n \"empleado\": {\n \"curp\": \"VECJ880326HDFXXX01\",\n \"num_empleado\": \"EMP-042\",\n \"num_seguridad_social\": \"12345678901\",\n \"periodicidad_pago\": \"04\",\n \"tipo_contrato\": \"01\",\n \"tipo_jornada\": \"01\",\n \"tipo_regimen\": \"02\"\n },\n \"empleador\": {\n \"registro_patronal\": \"A1234567890\"\n },\n \"fecha_final_pago\": \"2026-09-15\",\n \"fecha_inicial_pago\": \"2026-09-01\",\n \"fecha_pago\": \"2026-09-15\",\n \"num_dias_pagados\": 15,\n \"percepciones\": [\n {\n \"clave\": \"001\",\n \"concepto\": \"Sueldo\",\n \"importe_exento\": 2000,\n \"importe_gravado\": 10000,\n \"tipo_percepcion\": \"001\"\n }\n ],\n \"tipo_nomina\": \"O\",\n \"total_deducciones\": 1800,\n \"total_otros_pagos\": 0,\n \"total_percepciones\": 12000\n },\n \"receptor\": {\n \"domicilio_fiscal\": \"06600\",\n \"nombre\": \"JUAN VECTOR\",\n \"rfc\": \"VECJ880326XXX\"\n },\n \"rfc_emisor\": \"AAA010101AAA\",\n \"serie\": \"NOM\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.ipsofactura.com/cfdi/timbrar-nomina")
.header("x-api", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"folio\": \"2026-001\",\n \"idempotency_key\": \"nomina-emp-42-2026-09\",\n \"nomina\": {\n \"deducciones\": [\n {\n \"clave\": \"IMSSEmp\",\n \"concepto\": \"Cuota IMSS empleado\",\n \"importe\": 1000,\n \"tipo_deduccion\": \"001\"\n },\n {\n \"clave\": \"ISR\",\n \"concepto\": \"ISR\",\n \"importe\": 800,\n \"tipo_deduccion\": \"002\"\n }\n ],\n \"empleado\": {\n \"curp\": \"VECJ880326HDFXXX01\",\n \"num_empleado\": \"EMP-042\",\n \"num_seguridad_social\": \"12345678901\",\n \"periodicidad_pago\": \"04\",\n \"tipo_contrato\": \"01\",\n \"tipo_jornada\": \"01\",\n \"tipo_regimen\": \"02\"\n },\n \"empleador\": {\n \"registro_patronal\": \"A1234567890\"\n },\n \"fecha_final_pago\": \"2026-09-15\",\n \"fecha_inicial_pago\": \"2026-09-01\",\n \"fecha_pago\": \"2026-09-15\",\n \"num_dias_pagados\": 15,\n \"percepciones\": [\n {\n \"clave\": \"001\",\n \"concepto\": \"Sueldo\",\n \"importe_exento\": 2000,\n \"importe_gravado\": 10000,\n \"tipo_percepcion\": \"001\"\n }\n ],\n \"tipo_nomina\": \"O\",\n \"total_deducciones\": 1800,\n \"total_otros_pagos\": 0,\n \"total_percepciones\": 12000\n },\n \"receptor\": {\n \"domicilio_fiscal\": \"06600\",\n \"nombre\": \"JUAN VECTOR\",\n \"rfc\": \"VECJ880326XXX\"\n },\n \"rfc_emisor\": \"AAA010101AAA\",\n \"serie\": \"NOM\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ipsofactura.com/cfdi/timbrar-nomina")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"folio\": \"2026-001\",\n \"idempotency_key\": \"nomina-emp-42-2026-09\",\n \"nomina\": {\n \"deducciones\": [\n {\n \"clave\": \"IMSSEmp\",\n \"concepto\": \"Cuota IMSS empleado\",\n \"importe\": 1000,\n \"tipo_deduccion\": \"001\"\n },\n {\n \"clave\": \"ISR\",\n \"concepto\": \"ISR\",\n \"importe\": 800,\n \"tipo_deduccion\": \"002\"\n }\n ],\n \"empleado\": {\n \"curp\": \"VECJ880326HDFXXX01\",\n \"num_empleado\": \"EMP-042\",\n \"num_seguridad_social\": \"12345678901\",\n \"periodicidad_pago\": \"04\",\n \"tipo_contrato\": \"01\",\n \"tipo_jornada\": \"01\",\n \"tipo_regimen\": \"02\"\n },\n \"empleador\": {\n \"registro_patronal\": \"A1234567890\"\n },\n \"fecha_final_pago\": \"2026-09-15\",\n \"fecha_inicial_pago\": \"2026-09-01\",\n \"fecha_pago\": \"2026-09-15\",\n \"num_dias_pagados\": 15,\n \"percepciones\": [\n {\n \"clave\": \"001\",\n \"concepto\": \"Sueldo\",\n \"importe_exento\": 2000,\n \"importe_gravado\": 10000,\n \"tipo_percepcion\": \"001\"\n }\n ],\n \"tipo_nomina\": \"O\",\n \"total_deducciones\": 1800,\n \"total_otros_pagos\": 0,\n \"total_percepciones\": 12000\n },\n \"receptor\": {\n \"domicilio_fiscal\": \"06600\",\n \"nombre\": \"JUAN VECTOR\",\n \"rfc\": \"VECJ880326XXX\"\n },\n \"rfc_emisor\": \"AAA010101AAA\",\n \"serie\": \"NOM\"\n}"
response = http.request(request)
puts response.read_body{
"cadena_original_sat": "||1.1|...||",
"folio": "2026-001",
"id": "9a4f07ff-3abc-435f-b7a6-88c2bc65b4c1",
"numero_certificado_sat": "00001000000500000000",
"sello_cfdi": "...",
"sello_sat": "...",
"serie": "NOM",
"stamped_at": "2026-09-15T10:00:00",
"uuid": "6128396f-c09b-4ec6-8699-43da5a244971"
}Authorizations
API key emitida por Ipsofactura, enviada en el header x-api.
Headers
Alternativa a idempotency_key en el cuerpo: reenviar la misma llave devuelve la respuesta del primer intento (Idempotency-Replayed: true) en lugar de timbrar otra vez, y la misma llave con un cuerpo distinto es 422 IDEMPOTENCY_KEY_REUSED. Máximo 100 caracteres ASCII imprimibles, sin espacios. Si además envías el campo en el cuerpo, los dos valores deben coincidir; si no, la respuesta es 400 VALIDATION_ERROR.
Maximum string length:
100Example:
"nomina-emp-42-2026-09"
Body
application/json
Solicitud para generar y timbrar un CFDI 4.0 de nómina con complemento Nómina 1.2.
Datos del complemento Nómina 1.2.
Show child attributes
Show child attributes
Datos fiscales del empleado receptor.
Show child attributes
Show child attributes
RFC de la empresa emisora registrada en la cuenta.
Minimum string length:
1Pattern:
[A-Z&Ñ]{3,4}[0-9]{2}(0[1-9]|1[0-2])(0[1-9]|[12][0-9]|3[01])[A-Z0-9]{2}[0-9A]Example:
"AAA010101AAA"
Fecha de emisión ISO 8601. Default: fecha actual.
Pattern:
\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})?Example:
"2026-09-15T10:00:00"
Folio del comprobante. Si se omite, Ipsofactura asigna el siguiente consecutivo.
Maximum string length:
40Pattern:
[^|]*Example:
"2026-001"
Clave estable opcional. Reenviar la misma clave y payload devuelve el primer resultado.
Maximum string length:
100Pattern:
^[\x21-\x7E]+$Example:
"nomina-emp-42-2026-09"
Código postal de expedición. Default: código postal del emisor.
Example:
"06600"
Serie del comprobante, máximo 25 caracteres.
Maximum string length:
25Pattern:
[^|]*Example:
"NOM"
Response
CFDI de nómina timbrado
Show child attributes
Show child attributes
La clave de idempotencia con la que se timbró este CFDI, si se envió una.