Timbrar

Timbrar un comprobante

Tres caminos: mandas el comprobante en JSON y nosotros armamos el XML; mandas el XML que ya armaste y nosotros lo sellamos; o lo sellas tú y nosotros sólo lo timbramos.

Método	Mandas	Cuándo
`TimbrarCfdiObj`JSON	JSON	Lo recomendado. Con `comprobante` (CFDI 4.0) o `retenciones` (Retenciones 2.0). Referencia
`selladoTimbCFDI`XML	XML	Tu sistema ya arma el XML: lo mandas sin sello en `xmlBase64`. Referencia
`TimbradoCFDI`XML sellado	XML sellado	Tu sistema sella con tu CSD y no quieres guardarlo aquí. CFDI 4.0 o Retenciones 2.0. Referencia

Cómo se arma desde el JSON

Los nombres son los del Anexo 20 del SAT: Emisor, Receptor, Conceptos, Impuestos. El orden no importa: el XML sale en el orden del esquema.
Las llaves no distinguen mayúsculas: FechaPago y fechaPago son lo mismo. La nómina de los ejemplos va en camelCase.
Los valores se copian tal cual, sin recalcular ni redondear: el importe es el que decides tú. Mándalos como texto ("116.00") para que nada pase por un número de punto flotante.
Una llave que el servicio no conoce detiene el comprobante con 301 y la ruta exacta (Comprobante.Conceptos[0]: Descuneto…). Callarla sería timbrar sin un dato que sí mandaste.
Version, Sello, NoCertificado y Certificado los pone el servicio.
Acentos, eñes y & van tal cual. El carácter | no se acepta (salvo en CadPago): es el separador de la cadena original y haría que dos facturas distintas parecieran la misma.

Dónde va cada complemento

Llave	Complemento	Ejemplo
`Pagos`Pagos 2.0	Pagos 2.0	Complemento de pago
`nomina`Nómina 1.2	Nómina 1.2	Recibo de nómina
`CartaPorte`Carta Porte 3.1 (autotransporte, marítimo, aéreo y ferroviario)	Carta Porte 3.1 (autotransporte, marítimo, aéreo y ferroviario)	Traslado
`ComercioExterior`Comercio Exterior 2.0	Comercio Exterior 2.0	Exportación
`ImpuestosLocales`Impuestos locales	Impuestos locales	Honorarios con retenciones
`INE`INE 1.1	INE 1.1	Proveedor de un partido
`instEducativas`IEDU (en cada concepto)	IEDU (en cada concepto)	Colegiaturas
`Donatarias`Donatarias 1.1	Donatarias 1.1	`noAutorizacion`, `fechaAutorizacion` y `leyenda`, como en el servicio anterior.
`LeyendasFiscales`Leyendas fiscales 1.0	Leyendas fiscales 1.0	Una lista `Leyenda` con `disposicionFiscal`, `norma` y `textoLeyenda`.
`Complemento`Los de Retenciones 2.0	Los de Retenciones 2.0	Dividendos y los demás

Lo que regresa

Campo	Tipo	Para qué
`Codigo`texto	texto	«100» timbrado, «506» ya estaba timbrado; cualquier otro, el rechazo.
`Mensaje`texto	texto	Qué pasó, en español. En un rechazo, la regla del SAT que no se cumplió.
`UUID`texto	texto	El folio fiscal. Sólo con 100 o 506.
`XMLBase64`base64	base64	El CFDI timbrado, completo. Sólo con 100 o 506.
`PDFBase64`base64	base64	El PDF, si lo pediste con obtenerPDF; si no, null.
`IdSeguimiento`texto	texto	La huella del comprobante: con ella preguntas después por su desenlace (seguimientoCFDI).

Código	HTTP	Qué significa
100	200	Timbrado.
506	200	Ya estaba timbrado: el mismo UUID y el mismo XML. Trátalo como éxito.
301	200	El comprobante no se pudo armar; el mensaje dice qué campo.
CFDI40xxx…	200	Una regla del SAT no se cumple (la matriz de validaciones); el mensaje dice cuál.
500	200	No hay CSD cargado para el RFC del emisor, o no abre.
500	503	No se sabe si se timbró, o no se pudo enviar. Reintenta con el mismo comprobante.
102	401	Usuario o contraseña inválidos.
105	200	No tienes timbres disponibles (sólo en producción). Compra en tu portal y manda el mismo comprobante: no se gastó nada.

Cuánto esperar

Una factura tarda alrededor de un segundo. Configura tu cliente para esperar hasta 70 segundos: si el PAC no contesta, el servicio se rinde antes, busca el timbre por la huella y te responde. Puedes mandar muchas a la vez; la misma factura dos veces a la vez se timbra una sola.

Qué hacer con cada respuesta para que una factura nunca se timbre dos veces: reintentos.