Consultar y enviar

Antes de listar

• Los listados no tienen paginación ni orden: regresan todo lo que cumple en una sola respuesta. Usa periodos cortos (un mes o menos) si tu cuenta timbra mucho.
• Incluyen los CFDI cancelados. estado_cfdi es "1" vigente y "0" cancelado.
• Además de lo que emites, traen los CFDI recibidos que descargaste del SAT. Manda Documentorigin: issued para solo emitidos o received para solo recibidos.
• Mezclan CFDI timbrados en modo de pruebas y en producción si tu cuenta usó los dos.
• Los valores llegan como texto: montos con seis decimales ("1160.000000"), claves y banderas como "1".
• fecha es la fecha del CFDI, no la del timbrado, en hora del centro de México y formato AAAA-MM-DD hh:mm:ss.

Por mes

curl -sS "$FD_API/invoice/list" \
  -H "X-Api-Key: $FD_API_KEY" \
  -H "Type: I" -H "Month: 10" -H "Year: 2026" \
  -H "Documentorigin: issued"

{
  "message": "Successful Request.",
  "code": 200,
  "documents": [
    {
      "uuid": "6F0C2E1A-9B3D-4C7E-8A51-2D4F6B8C0E13",
      "folio": "1001",
      "serie": "A",
      "fecha": "2026-10-15 10:14:02",
      "tipodecomprobante": "I",
      "estado_cfdi": "1",
      "moneda": "MXN",
      "metodopago": "PUE",
      "formapago": "03",
      "monto_subtotal": "1000.000000",
      "monto_iva": "160.000000",
      "monto_total": "1160.000000",
      "emisor_rfc": "EKU9003173C9",
      "receptor_rfc": "XIA190128J61",
      "receptor_nombre": "XENON INDUSTRIAL ARTICLES",
      "estatus_cobranza": "0",
      "saldo_insoluto": "1160.000000"
    }
  ]
}

listextended recibe lo mismo y regresa todos los encabezados del CFDI: versión, certificado, decimales, domicilio del receptor, via_generacion (1 web, 2 API, 3 emitido descargado del SAT, 4 recibido), estatus_envio_email (0 sin enviar, 1 enviado, 2 leído), REP pendiente, campos extra1 a extra30 y más.

estatus_cobranza es 0 sin cobros, 1 con cobro parcial y 2 cobrado; saldo_insoluto es lo que falta por cobrar.

Por rango de fechas

Regresa las mismas columnas que list.

Solo los CFDI que recibiste de tus proveedores y descargaste del SAT, con los encabezados Type (vacío para todos los tipos), Startdate y Enddate en AAAA-MM-DD. Aquí emisor_* es tu proveedor y receptor_* eres tú.

Con filtros

El encabezado Filters lleva un objeto JSON en una sola línea. Cada llave es una columna de listextended y, si quieres, un operador separado por un espacio: =, !=, <, <=, >, >= o LIKE. Sin operador es igualdad. Todas las condiciones se cumplen a la vez (AND).

curl -sS "$FD_API/invoice/listwithfilters" \
  -H "X-Api-Key: $FD_API_KEY" \
  -H 'Filters: {"receptor_rfc": "XIA190128J61", "fecha >=": "2026-10-01", "fecha <": "2026-11-01", "estado_cfdi": "1"}'

• LIKE no agrega comodines: manda tú el % ({"receptor_nombre LIKE": "%XENON%"}). El _ también es comodín.
• null sin operador busca vacíos; con !=, los que tienen valor.
• {} no filtra: regresa todos los documentos de tu cuenta. Evítalo en cuentas grandes.
• Una columna o un operador fuera de la lista responden HTTP 400 con el nombre del que no se reconoce.

Pagos de tus facturas

Un renglón por cada pago registrado, con su complemento de pago (pago_uuid, null si el pago no tiene REP) y los datos de la factura que paga. Todos los encabezados son opcionales; sin ninguno regresa todos los pagos de la cuenta. La lista viene en la llave list, no en documents.

CFDI relacionados

Con el encabezado Uuid, regresa dos listas. padres son los CFDI que mencionan al que consultas: una nota de crédito, un sustituto o un complemento de pago que lo paga (tipo_relacion P). hijos son los que el consultado menciona en sus CfdiRelacionados. Esta respuesta no trae message ni code.

{
  "padres": [
    {
      "uuid": "3C9B7A12-4E5D-4F60-B8A1-9D2C6E0F7B34",
      "serie": "NC",
      "folio": "45",
      "tipodecomprobante": "E",
      "tipodecomprobante_desc": "Egreso",
      "estado_cfdi": "1",
      "monto_total": "116.000000",
      "tipo_relacion": "01",
      "tipo_relacion_desc": "01 Nota de crédito de los documentos relacionados"
    }
  ],
  "hijos": []
}

Las relaciones se arman después del timbrado; justo después de timbrar, una relación nueva puede tardar en aparecer.

Enviar por correo

curl -sS -X POST "$FD_API/invoice/send" \
  -H "X-Api-Key: $FD_API_KEY" \
  -H "UUID: 6F0C2E1A-9B3D-4C7E-8A51-2D4F6B8C0E13" \
  -H "RECIPIENT: cliente@facturadigital.com.mx" \
  -H "MESSAGE: Gracias por tu compra."

Responde { "message": "Email queued", "code": 200 }: el correo queda en la fila de envío y sale en menos de un minuto. Si ya hay un envío pendiente del mismo UUID al mismo correo, no se duplica. No usa folio, pero tu cuenta necesita saldo mayor a cero.