POST /v1/facturas

Crear una factura

Crea y timbra un CFDI 4.0 en una sola llamada. La respuesta llega cuando el PAC devuelve el UUID; si tarda más de 15 s regresamos 202 y te avisamos por webhook.

Manda siempre Idempotency-Key. Si repites la llamada con la misma clave te devolvemos la factura original en vez de timbrar dos veces.

Parámetros

receptor_rfc string · requerido: RFC de quien recibe la factura: 12 caracteres si es persona moral, 13 si es persona física. Debe coincidir con su constancia de situación fiscal.
receptor_cp string · requerido: Código postal del domicilio fiscal del receptor, 5 dígitos. El SAT lo valida junto con el RFC.
uso_cfdi string · requerido: Clave del catálogo de uso del CFDI, por ejemplo G03 para gastos en general.
metodo_pago string · requerido: PUE cuando el pago ya se hizo en una sola exhibición; PPD cuando queda a crédito y se liquidará después con un complemento de pago.
forma_pago string · requerido: Clave del catálogo de formas de pago del SAT, por ejemplo 03 para transferencia electrónica de fondos.
conceptos[] array · requerido: Lista de conceptos. Cada uno lleva descripcion, cantidad y valor_unitario. Si omites las claves del SAT las inferimos del producto guardado.
serie / folio string / entero · opcionales: Si no los mandas usamos tu serie activa y el siguiente folio disponible. Asignarlos a mano es la causa más común de FOLIO_DUPLICADO.

Respuesta

Devolvemos 201 con el UUID en cuanto el PAC responde. Si el PAC tarda más de 15 s devolvemos 202 con la factura en estado timbrando y te avisamos por webhook al terminar.

id string: Identificador de la factura dentro de oden.tax.
estado string: timbrando, timbrada, cancelacion_en_proceso, cancelada o error.
uuid string: Folio fiscal del SAT, 36 caracteres. Llega en null mientras el estado sea timbrando.
serie string: Serie con la que se timbró.
folio entero: Folio consecutivo dentro de la serie.
fecha_timbrado string: Momento del timbrado en ISO 8601 con zona horaria.
total string: Total con impuestos, dos decimales.
moneda string: Clave ISO 4217. MXN salvo que pidas otra.
xml_url string: Descarga del XML timbrado.
pdf_url string: Descarga de la representación impresa.

Errores comunes

CFDI40102: El receptor no está inscrito con ese RFC y código postal.
CSD_EXPIRADO: Tu certificado venció. Súbelo de nuevo en Configuración → CSD.
FOLIO_DUPLICADO: Ese folio ya existe en la serie. Deja que lo asignemos nosotros.
LIMITE_PLAN: Llegaste al tope del plan Básico; el Pro incluye API y 500 al mes.