Defaults al timbrar
POST /cfdi/timbrar completa estos campos cuando no los envías:
Precedencia de los datos del emisor
El RFC del emisor siempre sale derfc_emisor (raíz del request) y debe corresponder a
una empresa registrada en tu cuenta.
El objeto emisor (nombre y régimen fiscal) es opcional. La regla es: lo que mandes en el
request gana; lo que omitas se completa con lo registrado en la empresa:
- Sin objeto
emisor→ se usan elnombre_fiscalyregimen_fiscalregistrados. - Con
emisor.regimen_fiscal→ ese régimen se usa para este CFDI, aunque difiera del registrado.
Obligatorios de facto
Estos campos aparecen como opcionales en el esquema histórico, pero omitirlos produce un400 o un rechazo del SAT — trátalos como obligatorios:
Receptor extranjero
Un receptor sin RFC mexicano se timbra con el RFC genéricoXEXX010101000, uso_cfdi S01
y dos campos opcionales que llevan sus datos fiscales reales al CFDI:
Receptor extranjero
400 VALIDATION_ERROR, sin consumir
timbre):
num_reg_id_tribrequiereresidencia_fiscal: un identificador fiscal extranjero no significa nada sin el país que lo emitió.residencia_fiscalsólo aplica a un receptor extranjero, es decir con RFCXEXX010101000. Enviarla con un RFC nacional es un error, no un campo que descartemos en silencio.residencia_fiscaldebe ser una clave dec_Pais.
POST /cfdi/timbrar-xml (se leen del XML que envías, no se
descartan) y un complemento de pago los hereda de la factura que liquida, porque el SAT
exige que el receptor del CFDI tipo P sea el de la factura relacionada.
Al recuperar el CFDI, GET /cfdi/{id} los devuelve como receptor_residencia_fiscal y
receptor_num_reg_id_trib.
Exportación: pedimento por concepto
Para una operación de exportación, además deexportacion (02 definitiva, 03 temporal,
04 definitiva con clave distinta a A1), cada concepto importado puede declarar su
pedimento, que se timbra en cfdi:InformacionAduanera@NumeroPedimento.
pedimento son 21 caracteres exactos en el formato del SAT AA␣␣AA␣␣PPPP␣␣NNNNNNN, con
dos espacios entre grupos: 2 dígitos del año de validación, 2 de la aduana, 4 de la
patente y 7 del consecutivo. Un espacio sencillo es el error más común y responde
400 VALIDATION_ERROR.
Concepto con pedimento
Retenciones a nivel comprobante
En el nodo globalimpuestos.retenciones[] el SAT sólo admite dos atributos: el impuesto y
el importe. Si envías además base, tipo_factor o tasa_o_cuota, se aceptan —no
rompemos integraciones existentes— pero el CFDI se timbra únicamente con impuesto e
importe. Esos valores sí se conservan: se usan después para prorratear la retención de
cada documento relacionado al emitir un complemento de pago. En las retenciones a nivel
concepto los cinco campos sí se timbran, porque ahí el SAT los declara.
Tipos de comprobante soportados
tipo_comprobante acepta I (ingreso), E (egreso) y P (pago, vía
POST /cfdi/complemento-pago). Los tipos T (traslado) y N (nómina)
requieren complementos que hoy no generamos, y la API los rechaza con
400 INVALID_TIPO_COMPROBANTE.
Para las ventas al público en general, consulta la guía de
factura global.
La referencia completa de cada campo está en
POST /cfdi/timbrar, generado directamente del código de
la API.¿Ya tienes el CFDI armado en XML?
Si tu sistema (ERP, facturador propio) arma el CFDI 4.0 en XML directamente, no necesitas convertirlo a este payload JSON: envíalo sin sellar aPOST /cfdi/timbrar-xml y Ipsofactura
lo sella y timbra igual. Ver Timbrado por XML.
Recuperar un CFDI después de timbrarlo
Para volver a encontrar un CFDI ya timbrado —por tuserie/folio, por su folio fiscal, o
por el id que te devolvimos— usa GET /cfdi/{id} o los filtros de GET /cfdi (serie,
folio, rfc_emisor, folio_fiscal). Es la base del patrón de recuperación tras un
timeout: ver Recuperación tras timeout.