Panel Facturama

RFC	Válido hasta	Estado
Selecciona un emisor

Facturas

CFDI tipo I (Ingreso) · PUE o PPD

Emite comprobantes fiscales de ingreso. Usa PUE (Pago en Una Exhibición) cuando el pago es inmediato, y PPD (Pago en Parcialidades o Diferido) cuando el cliente pagará después — en ese caso deberás emitir un Complemento de Pago al recibir el dinero.

POST /facturama/cfdi

Campo	Tipo	Req	Descripción
rfcEmisor	string	OPT	RFC del emisor. Si se omite, se usa el emisor activo del panel.
serie	string	OPT*	Serie local del emisor (ej: "A"). Requerida si no envías `folio`.
folio	string	OPT*	Folio explícito. Si se omite, se calcula automáticamente a partir de la serie.
formaPago	string	OPT	Clave SAT (default "31" transferencia). Usar "99" para PPD.
metodoPago	string	OPT	"PUE" (default) o "PPD". Con PPD la factura queda pendiente de pago.
receptor	object	REQ	Datos del receptor: `rfc, razonSocial, regimenFiscal, codigoPostal, usoCfdi`
conceptos	array	REQ	Lista de conceptos. Ver tabla de ConceptoDto abajo.

ConceptoDto

Campo	Tipo	Req	Descripción
sku	string	REQ	Clave interna del producto o servicio.
descripcion	string	REQ	Descripción del producto o servicio.
cantidad	number	REQ	Cantidad de unidades.
precioUnitario	number	REQ	Precio sin IVA por unidad.
claveUnidad	string	REQ	Clave SAT de unidad (ej: "E48" Servicio, "H87" Pieza).
nombreUnidad	string	REQ	Nombre de la unidad (ej: "Servicio", "Pieza").
codigoSat	string	OPT	Clave de producto/servicio SAT. Default "01010101".
sinImpuestos	boolean	OPT	true para conceptos exentos de IVA. Default false (aplica IVA 16%).
ivaUnitario	number	OPT	Monto de IVA por unidad si es diferente al 16% estándar.

Redondeo: subtotal, IVA y total de cada concepto se redondean a 2 decimales de forma independiente por concepto (no sobre el total de la factura). Si tus cálculos locales usan más decimales, el monto que verás timbrado puede diferir por centavos respecto a tu cálculo sin redondear.

Formas de pago comunes: 01 Efectivo · 02 Cheque · 03 Transferencia · 04 Tarjeta de crédito · 28 Tarjeta de débito · 99 Por definir (PPD)

Ejemplo — Factura PUE (pago inmediato)

{
  "rfcEmisor":  "PLA110402TA4",
  "serie":      "A",
  "formaPago":  "03",
  "metodoPago": "PUE",
  "modo":       "sandbox",
  "receptor": {
    "rfc":           "APT040201KA5",
    "razonSocial":   "ACTITUD POSITIVA EN TONER",
    "regimenFiscal": "601",
    "codigoPostal":  "31203",
    "usoCfdi":       "G03"
  },
  "conceptos": [
    {
      "sku":            "PROD-001",
      "descripcion":    "Servicio de consultoria",
      "cantidad":       1,
      "precioUnitario": 1000.00,
      "claveUnidad":    "E48",
      "nombreUnidad":   "Servicio",
      "codigoSat":      "80131500"
    }
  ]
}

La respuesta incluye id (UUID del CFDI). Guárdalo para cancelar, descargar o relacionar notas de crédito. Subtotal: $1,000 · IVA 16%: $160 · Total: $1,160

Endpoints relacionados

Método	Ruta	Descripción
GET	/facturama/cfdi?rfcEmisor=XXX	Lista CFDIs. Filtros: rfc, folio, dateStart, dateEnd, status, buyerRfc
GET	/facturama/cfdi/:id?rfcEmisor=XXX	Detalle de un CFDI por UUID
GET	/facturama/cfdi/:id/pdf?rfcEmisor=XXX	Descarga PDF del CFDI
GET	/facturama/cfdi/:id/xml?rfcEmisor=XXX	Descarga XML del CFDI

Cancelaciones

Cancelar un CFDI ante el SAT · requiere motivo de cancelación

Existen dos endpoints equivalentes. El primero usa DELETE (compatible con REST clásico) y el segundo usa POST (útil cuando el cliente HTTP no soporta body en DELETE).

DELETE /facturama/cfdi/:id

POST /facturama/cfdi/:id/cancelar

Campo (body)	Tipo	Req	Descripción
motivo	string	REQ	Clave SAT del motivo (ver tabla abajo).
uuidReplacement	string	OPT	UUID del CFDI sustituto. Requerido solo si motivo es "01".

Motivos de cancelación SAT

Clave	Descripción	¿Requiere UUID sustituto?
01	Comprobante emitido con errores con relación	Sí — uuidReplacement
02	Comprobante emitido con errores sin relación	No
03	No se llevó a cabo la operación	No
04	Operación nominativa en factura global	No

Ejemplo — Cancelar por error sin relación

POST /facturama/cfdi/550e8400-e29b-41d4-a716-446655440000/cancelar?rfcEmisor=PLA110402TA4

{
  "motivo": "02"
}

Ejemplo — Cancelar y sustituir por otro CFDI

POST /facturama/cfdi/550e8400-e29b-41d4-a716-446655440000/cancelar?rfcEmisor=PLA110402TA4

{
  "motivo":          "01",
  "uuidReplacement": "660f9500-f30c-52e5-b827-557766551111"
}

El SAT puede requerir la aceptación del receptor antes de confirmar la cancelación. Facturama gestiona este proceso internamente. El acuse confirma que la solicitud fue recibida, no que ya está cancelada.

Acuse de cancelación

GET /facturama/cfdi/:id/acuse-cancelacion?rfcEmisor=XXX&formato=pdf

Parámetro formato: pdf (default) o xml. Devuelve el archivo como descarga binaria.

PPD — Complementos de pago

CFDI tipo P · flujo de dos pasos · requiere factura previa con metodoPago PPD

Cuando el cliente paga después de emitida la factura se debe registrar el pago con un CFDI tipo "P" (Complemento de Pago). El flujo siempre es de dos pasos: primero la factura PPD, luego el complemento.

Paso 1

Factura PPD

POST /cfdi
metodoPago: "PPD"
formaPago: "99"

Paso 2

Complemento de pago

POST /facturas/:uuid/pagos
con el UUID de la factura PPD

Paso 1 — Crear la factura PPD

POST /facturama/cfdi

{
  "rfcEmisor":  "PLA110402TA4",
  "serie":      "A",
  "formaPago":  "99",
  "metodoPago": "PPD",
  "modo":       "sandbox",
  "receptor": {
    "rfc":           "APT040201KA5",
    "razonSocial":   "ACTITUD POSITIVA EN TONER",
    "regimenFiscal": "601",
    "codigoPostal":  "31203",
    "usoCfdi":       "G03"
  },
  "conceptos": [
    {
      "sku":            "SERV-002",
      "descripcion":    "Desarrollo de software a medida",
      "cantidad":       1,
      "precioUnitario": 5000.00,
      "claveUnidad":    "E48",
      "nombreUnidad":   "Servicio",
      "codigoSat":      "81112100"
    }
  ]
}

Subtotal: $1,000 · IVA 16%: $160 · Total: $1,160. La respuesta contiene el id (UUID). Úsalo en el Paso 2.

Paso 2 — Registrar el pago

POST /facturama/facturas/:facturaUuid/pagos

Campo	Tipo	Req	Descripción
montoPagado	number	REQ	Cuánto se paga en esta exhibición (con IVA incluido).
fechaPago	string	REQ	Fecha y hora del pago ISO 8601 (ej: "2026-05-25T10:00:00").
formaPago	string	REQ	Clave SAT de la forma de pago real (ej: "03" transferencia, "01" efectivo).
rfcEmisor	string	OPT	RFC del emisor. Si se omite, usa el emisor activo.
serie	string	OPT	Serie local para el folio del complemento. Si se omite usa la primera serie del emisor.
moneda	string	OPT	Moneda del pago. Default "MXN".
totalFactura	number	OPT	Total de la factura original. Solo necesario si el sistema no lo puede obtener automáticamente (primera vez con factura antigua).
regimenFiscalReceptor	string	OPT	Régimen fiscal del receptor. Solo hace falta si la factura original es anterior a esta corrección y Facturama tampoco lo devuelve al consultarla (ver aviso abajo).
codigoPostalReceptor	string	OPT	Código postal del domicilio fiscal del receptor. Mismo caso que `regimenFiscalReceptor`.
modo	string	OPT	"sandbox" o "produccion". Por defecto usa el modo del emisor.

El sistema calcula automáticamente parcialidad, saldo anterior e insoluto a partir del historial de pagos en la base de datos. Solo necesitas enviar montoPagado.

Error "el domicilio fiscal del receptor no corresponde al RFC": el régimen fiscal y código postal del receptor se toman de la factura PPD original (guardados al timbrarla). Si la factura es anterior a esta corrección, el sistema no los tiene guardados y devuelve un error pidiendo regimenFiscalReceptor y codigoPostalReceptor en el body — solo hace falta enviarlos esa primera vez, con los mismos datos que usaste al crear la factura.

Ejemplo — Pago total (una sola exhibición)

POST /facturama/facturas/{uuid-de-la-factura-ppd}/pagos

{
  "rfcEmisor":  "PLA110402TA4",
  "fechaPago":  "2026-05-25T10:00:00",
  "formaPago":  "03",
  "montoPagado": 5800.00,
  "modo":        "sandbox"
}

Ejemplo — Pago en parcialidades (primera de tres)

POST /facturama/facturas/{uuid-de-la-factura-ppd}/pagos

{
  "rfcEmisor":  "PLA110402TA4",
  "fechaPago":  "2026-05-25T10:00:00",
  "formaPago":  "03",
  "montoPagado": 2000.00,
  "modo":        "sandbox"
}

-- Segunda parcialidad (mismo endpoint, mismo body cambiando el monto) --

{
  "rfcEmisor":  "PLA110402TA4",
  "fechaPago":  "2026-06-10T10:00:00",
  "formaPago":  "03",
  "montoPagado": 2000.00,
  "modo":        "sandbox"
}

-- Tercera parcialidad --

{
  "rfcEmisor":  "PLA110402TA4",
  "fechaPago":  "2026-07-01T10:00:00",
  "formaPago":  "03",
  "montoPagado": 1800.00,
  "modo":        "sandbox"
}

El sistema detecta automáticamente cuál es la parcialidad, el saldo anterior y el insoluto. Cada llamada solo necesita montoPagado y fechaPago.

Pago múltiple — varias facturas PPD en un solo CFDI

POST /facturama/pagos/multiple

Cuando un mismo pago liquida/abona varias facturas PPD del mismo receptor (por ejemplo una transferencia que cubre tres facturas), este endpoint timbra un solo CFDI tipo "P" con un DoctoRelacionado por factura, en vez de un complemento de pago por cada una. A diferencia de /facturas/:uuid/pagos, aquí saldoAnterior, saldoInsoluto y parcialidad son obligatorios por factura (no se auto-calculan).

Campo	Tipo	Req	Descripción
fechaPago	string	REQ	Fecha y hora del pago ISO 8601.
formaPago	string	REQ	Clave SAT de la forma de pago real.
facturas	array	REQ	Facturas a liquidar/abonar. Cada elemento: `uuid, saldoAnterior, montoPagado, saldoInsoluto, parcialidad` (y opcionalmente `serie, folio`).
rfcEmisor	string	OPT	RFC del emisor. Si se omite, usa el emisor activo.
serie	string	OPT	Serie local para el folio del complemento.
moneda	string	OPT	Moneda del pago. Default "MXN".
regimenFiscalReceptor	string	OPT	Igual que en el pago simple: solo hace falta para facturas anteriores a la corrección del domicilio fiscal del receptor.
codigoPostalReceptor	string	OPT	Igual que en el pago simple.
modo	string	OPT	"sandbox" o "produccion". Por defecto usa el modo del emisor.

Todas las facturas de un mismo pago múltiple deben tener el mismo receptor (RFC) — el CFDI de pago solo admite un receptor. Si mezclas facturas de RFCs distintos, el endpoint responde con error antes de intentar timbrar.

Ejemplo — una transferencia que liquida dos facturas

POST /facturama/pagos/multiple

{
  "rfcEmisor":  "PLA110402TA4",
  "fechaPago":  "2026-05-25T10:00:00",
  "formaPago":  "03",
  "modo":        "sandbox",
  "facturas": [
    {
      "uuid":          "AAAAAAAA-1111-1111-1111-111111111111",
      "saldoAnterior": 3000.00,
      "montoPagado":   3000.00,
      "saldoInsoluto": 0,
      "parcialidad":   1
    },
    {
      "uuid":          "BBBBBBBB-2222-2222-2222-222222222222",
      "saldoAnterior": 2800.00,
      "montoPagado":   2800.00,
      "saldoInsoluto": 0,
      "parcialidad":   1
    }
  ]
}

Endpoints de pagos

Método	Ruta	Descripción
GET	/facturama/facturas/:uuid/pagos	Lista complementos de pago de una factura
POST	/facturama/pagos/multiple	Timbra un solo CFDI de pago relacionando varias facturas PPD del mismo receptor
GET	/facturama/pagos/:id/pdf?rfcEmisor=XXX	Descarga el PDF del CFDI de pago
GET	/facturama/pagos/:id/xml?rfcEmisor=XXX	Descarga el XML del CFDI de pago
POST	/facturama/pagos/:id/cancelar?rfcEmisor=XXX	Cancela el complemento de pago (motivo "02" automático)

Notas de crédito

CFDI tipo E (Egreso) · devoluciones, descuentos y bonificaciones

Una nota de crédito reduce el valor de una factura previamente emitida. Se emite como CFDI tipo "E" (Egreso) referenciando el UUID de la factura original. El sistema recupera automáticamente los datos del receptor desde esa factura.

POST /facturama/facturas/:facturaUuid/nota-credito

El :facturaUuid de la URL es el UUID del CFDI de ingreso original. No se envía en el body.

Campo	Tipo	Req	Descripción
conceptos	array	REQ	Conceptos a devolver o descontar (misma estructura que en facturas).
rfcEmisor	string	OPT	RFC del emisor. Si se omite, usa el emisor activo.
serie	string	OPT	Serie para el folio local. Si se omite, usa la primera serie del emisor.
formaPago	string	OPT	Forma en que se devuelve el dinero. Default "31" (Por definir).
modo	string	OPT	`"sandbox"` o `"produccion"`. Si se omite, usa el modo del emisor.

El sistema asigna automáticamente el folio desde la serie configurada del emisor. El receptor se toma directamente de la factura original referenciada por :facturaUuid. Solo necesitas enviar los conceptos a devolver.

El sistema establece automáticamente cfdiType: "E" y usoCfdi: "G02" (Devoluciones, descuentos o bonificaciones) en el receptor de la nota de crédito.

Ejemplo — Devolución TOTAL (devolver todos los conceptos de la factura original)

POST /facturama/facturas/{uuid-de-la-factura-original}/nota-credito

{
  "rfcEmisor": "PLA110402TA4",
  "serie":     "A",
  "formaPago": "03",
  "modo":      "sandbox",
  "conceptos": [
    {
      "sku":            "LAP-001",
      "descripcion":    "Laptop HP ProBook 450 G10",
      "cantidad":       2,
      "precioUnitario": 15000.00,
      "claveUnidad":    "H87",
      "nombreUnidad":   "Pieza",
      "codigoSat":      "43211503"
    },
    {
      "sku":            "MOU-001",
      "descripcion":    "Mouse Logitech MX Master 3",
      "cantidad":       2,
      "precioUnitario": 500.00,
      "claveUnidad":    "H87",
      "nombreUnidad":   "Pieza",
      "codigoSat":      "43211708"
    }
  ]
}

Subtotal: $31,000 · IVA: $4,960 · Total nota: $35,960 (cubre la factura completa). El receptor se toma automáticamente de la factura: RFC APT040201KA5 / ACTITUD POSITIVA EN TONER.

Ejemplo — Devolución PARCIAL (devolver solo un artículo de la factura)

POST /facturama/facturas/{uuid-de-la-factura-original}/nota-credito

{
  "rfcEmisor": "PLA110402TA4",
  "serie":     "A",
  "formaPago": "03",
  "modo":      "sandbox",
  "conceptos": [
    {
      "sku":            "LAP-001",
      "descripcion":    "Devolucion - Laptop HP ProBook 450 G10",
      "cantidad":       1,
      "precioUnitario": 15000.00,
      "claveUnidad":    "H87",
      "nombreUnidad":   "Pieza",
      "codigoSat":      "43211503"
    }
  ]
}

Subtotal: $15,000 · IVA: $2,400 · Total nota: $17,400 (devolución parcial de una laptop). La factura original queda con saldo pendiente de $18,560.

Endpoints de notas de crédito

Método	Ruta	Descripción
GET	/facturama/notas-credito/:id	Detalle del CFDI de nota de crédito
GET	/facturama/notas-credito/:id/pdf?rfcEmisor=XXX	Descarga el PDF de la nota de crédito
GET	/facturama/notas-credito/:id/xml?rfcEmisor=XXX	Descarga el XML de la nota de crédito

Multi-emisor

Cómo especificar qué empresa emite el CFDI

Todos los endpoints que interactúan con Facturama aceptan el parámetro opcional rfcEmisor (query param en GET/DELETE o campo en el body en POST). Si se omite, se usa el emisor activo del panel.

Escenario	Cómo especificarlo
Usar el emisor activo del panel	No enviar `rfcEmisor`
Emisor específico en POST/PUT	`"rfcEmisor": "PLA110402TA4"` en el body
Emisor específico en GET/DELETE	`?rfcEmisor=PLA110402TA4` en la URL

Las facturas de emisores secundarios (API Multiemisor) no aparecen en el portal web de Facturama. Solo son visibles consultando la API con las credenciales correctas o usando este webservice.

Sandbox / Producción

Control por emisor · se cambia desde el panel de Emisores

Cada emisor puede configurarse en modo sandbox (pruebas) o produccion (real). El modo se guarda en emisores.json y se cambia desde la pestaña Información de cada emisor. Los CFDIs en sandbox no tienen validez fiscal.

Modo	URL base	Uso
sandbox	apisandbox.facturama.mx	Pruebas y desarrollo. No genera CFDIs reales.
produccion	api.facturama.mx	CFDIs reales con validez fiscal ante el SAT.

Emisores SANDBOX

Facturas Emitidas

Series propias

Sellos Digitales (CSD)

Información del Emisor

Historial Local (SQLite)

CFDIs Cancelados

Complementos de Pago (PPD)

Notas de Crédito

Catálogos SAT