Factura con detracción
Factura sujeta a detracción. Envía el objeto detraccion (o `{}` para usar lo configurado en la empresa): la API completa cuenta, porcentaje, tipo y monto, y marca la operación como 1001.
POSThttps://api.facturalo.pe/api/v3/documentos/enviar
Parámetros del body
Campo
Descripción
webhookbooleanopcional
Si es true, la respuesta es inmediata (EN_PROCESO) y el resultado llega al webhook configurado. Default: false (síncrono).Ej:
falseestablecimientostring | nullopcional
UUID del establecimiento emisor. Si se omite, se usa el establecimiento principal de la empresa.
cotizacionstring | nullopcional
UUID de la cotización que se convierte en este comprobante. Se valida antes de enviar a SUNAT y queda vinculada. Opcional.
documentoobjectrequerido
Datos del comprobante electrónico.
sunatTransaccionstringrequerido
1001 = Operación sujeta a detracción. Obligatorio para este tipo.Ej:
1001tipoComprobantestringrequerido
01 = Factura electrónica.Ej:
01seriestringrequerido
Serie del comprobante. Facturas: F001–F999. Boletas: B001–B999. Exactamente 4 caracteres.Ej:
F001correlativostringrequerido
Correlativo numérico. Máximo 8 caracteres.Ej:
1fechaEmisionstringrequerido
Fecha de emisión en formato YYYY-MM-DD.Ej:
2026-06-13fechaVencimientostring | nullopcional
Fecha de vencimiento. Formato YYYY-MM-DD. Si no se envía, se toma la fechaEmision como fecha de vencimiento.
formaPagostringrequerido
"CONTADO" | "CREDITO". Si es CREDITO, se requiere el array cuotas.Ej:
CONTADOmonedastringrequerido
"PEN" (Soles) | "USD" (Dólares).Ej:
PENobservacionesstring | nullopcional
Texto libre que aparece en el comprobante.
placaVehiculostring | nullopcional
Placa del vehículo asociado a la operación.
ordenComprastring | nullopcional
Número de orden de compra del cliente.
otrosCamposarray | nullopcional
Campos libres solo locales (PDF, consulta y webhook). No se envían a SUNAT. Máximo 30 ítems. Cada ítem: { label, value }.Ej:
[{ "label": "Cajero", "value": "Guillermo" }]labelstringrequerido
Etiqueta visible en el PDF (ej. Cajero, Método de pago, Mesa).Ej:
Cajerovaluestringrequerido
Valor del campo.Ej:
GuillermodescuentoGlobalnumber | nullopcional
Descuento global aplicado al total del documento (con IGV incluido).
enviarCorreobooleanopcional
Si es true, envía el PDF y XML al correo del cliente tras la aceptación. Default: false.Ej:
truedetraccionobjectrequerido
Datos de la detracción (SPOT). Aplica a facturas de más de S/ 700. Lo que no envíes se completa con lo configurado en la empresa (PATCH /empresas/{uuid} → empresa.detraccion); con
{} se usa todo de ahí.tipostringopcional
Bien o servicio, catálogo 54 (ej. 037 Demás servicios gravados con el IGV). Default: el de la empresa.Ej:
037medioPagostringopcional
Catálogo 59. Default: 001 (depósito en cuenta).Ej:
001ctaBancostringopcional
Cuenta de detracciones del Banco de la Nación. Default: la de la empresa.Ej:
00-000-000000porcentajenumberopcional
Porcentaje de detracción. Default: el de la empresa.Ej:
12montonumberopcional
Monto en soles. Si no lo envías se calcula: total × porcentaje / 100. En facturas en dólares es obligatorio (en soles).Ej:
141.6clienteobjectrequerido
Datos del adquirente.
tipoDocumentostringrequerido
6 = RUC · 1 = DNI · 0 = Sin documento (clientes varios).Ej:
6numeroDocumentostringrequerido
Número sin puntos ni guiones. RUC: 11 dígitos. DNI: 8 dígitos.Ej:
20609753413denominacionstringrequerido
Razón social o nombre completo.Ej:
EMPRESA S.A.C.direccionstring | nullopcional
Requerida si tipoDocumento = 6 (RUC).
correostring | nullopcional
Correo del cliente para envío del PDF/XML.
celularstring | nullopcional
Número de celular. Exactamente 9 dígitos.
itemsarrayrequerido
Líneas del comprobante. Mínimo 1 ítem.
unidadMedidastringrequerido
Código SUNAT: NIU = unidad · ZZ = servicio · BX = caja · KGM = kilogramo · GLI = galón.Ej:
NIUcodigostring | nullopcional
Código interno del producto (max 30 caracteres).
productoIdstring | nullopcional
UUID de la variante (o del producto si tiene una sola) del catálogo. Lo que no envíes (descripción, unidad, IGV, precio, código SUNAT) sale del catálogo, y si controla stock descuenta del inventario. También puedes enviar el SKU en
codigo sin descripcion.seriesstring[] | nullopcional
Productos que controlan número de serie: una serie / IMEI por unidad. Se agrega a la descripción (
S/N: …) y la serie queda vendida. Ver Series.Ej: ["5CD1234ABD"]descripcionstringrequerido
Descripción del producto o servicio (max 250 caracteres).Ej:
SERVICIO DE CONSULTORÍAcantidadnumberrequerido
Cantidad de unidades. Mínimo 0.Ej:
2precioUnitarionumberrequerido
Precio por unidad con IGV incluido. La API calcula el IGV automáticamente.Ej:
590tipoIgvstringrequerido
10 = Gravado oneroso (tasa normal 18%).Ej:
10descuentonumber | nullopcional
Descuento por ítem (con IGV incluido).
impuestoBolsaboolean | nullopcional
Si es true, aplica ICBPER (impuesto a bolsas plásticas) a este ítem.
Detracción desde la configuración de la empresa
Configura una vez la cuenta del Banco de la Nación, el porcentaje y el tipo en la consola (Empresa → Detracciones) o con PATCH /empresas/{uuid}. Desde ahí basta con"detraccion": {} en cada factura. Si sunatTransaccion es 0101, la API la cambia a 1001 (operación sujeta a detracción). Con forma de pago CREDITO, las cuotas deben sumar el total menos la detracción.Language
Credentials
Header
Authorization
Ejemplos con el SDK oficial en Node, PHP y Python
Idempotencia
Header
Idempotency-Key
Misma clave + mismo cuerpo = misma respuesta (24 h). Ver /idempotencia.
API Request
$ npm install @facturalo-pe/node
import { FacturaloClient } from "@facturalo-pe/node";
const facturalo = new FacturaloClient({ token: process.env.FACTURALO_TOKEN! });
const envio = await facturalo.documentos.enviar({
sunatTransaccion: "1001",
tipoComprobante: "01",
serie: "F001",
correlativo: "1",
fechaEmision: "2026-06-13",
formaPago: "CONTADO",
otrosCampos: [
{
label: "Cajero",
value: "Guillermo"
},
{
label: "Método de pago",
value: "Yape"
},
{
label: "Mesa",
value: "12"
}
],
moneda: "PEN",
cliente: {
tipoDocumento: "6",
numeroDocumento: "20000000001",
denominacion: "EMPRESA S.A.C.",
direccion: "AV. LIMA 123 - LIMA - LIMA - LIMA",
correo: "cliente@empresa.com"
},
detraccion: {
tipo: "037",
medioPago: "001",
ctaBanco: "00-000-000000",
porcentaje: 12,
monto: 141.6
},
items: [
{
unidadMedida: "ZZ",
codigo: "S001",
descripcion: "Servicio de consultoría empresarial",
cantidad: 1,
precioUnitario: 1180,
tipoIgv: "10"
}
]
}, {
idempotencyKey: "orden-1042"
});
console.log(envio.estado, envio.sunat?.mensaje, envio.enlaces.pdf);SDK oficial @facturalo-pe/node · guía en /sdks
Response
Elige un ejemplo de respuesta:
application/json
200Aceptada
{
"success": true,
"message": "La Factura numero F001-00000001 ha sido aceptada",
"data": {
"estado": "ACEPTADA",
"entorno": "demo",
"documento": {
"id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84",
"estado": "ACEPTADA",
"serie": "F001",
"correlativo": "00000001",
"tipo": "FACTURA"
},
"sunat": {
"estado": "ACEPTADA",
"codigo": "0",
"mensaje": "La Factura numero F001-00000001 ha sido aceptada",
"notas": []
},
"enlaces": {
"pdf": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.pdf",
"pdfTicket": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.ticket.pdf",
"xml": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.xml",
"cdr": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.cdr"
},
"hash": "xvQpVbLssRc8FlD8/0LuSYeIPo8=",
"cadenaQr": "20601476551 | 01 | F001 | 00000001 | 180.00 | 1180.00 | 13/06/2026 | 6 | 20000000001 | xvQpVbLssRc8FlD8/0LuSYeIPo8= |"
}
}