Idempotencia
Timbrar no se deshace. Si tu petición se cortó y no sabes si la factura salió, reintentar a ciegas puede emitir dos comprobantes al mismo cliente por lo mismo, y el segundo hay que cancelarlo con el SAT. La llave de idempotencia es para que reintentar sea seguro.
Idempotency-Key con un valor tuyo, único por factura. Si repites la llamada con la
misma llave te devolvemos la factura que ya existe, con el encabezado
Idempotency-Replayed: true.
Qué poner de llave
Algo que tu sistema pueda volver a calcular igual después de reiniciarse: el id de la orden, el del pedido, un UUID que guardaste antes de llamarnos. Un número aleatorio generado en el momento de la petición no sirve, porque el reintento generaría otro.
La llave es única por emisor. Dos contribuyentes de la misma cuenta pueden usar la misma sin pisarse.
Un rechazo sí se puede reintentar
Si la factura anterior con esa llave quedó en error y nunca llegó a tener timbre, la
llave se libera y el reintento crea una factura nueva. Es lo que se quiere: corregiste el dato que el PAC no aceptó y
vuelves a intentar con la misma llave de tu lado.
Una que sí timbró nunca se libera. Ahí el reintento devuelve la de siempre.
Dos llamadas al mismo tiempo
Sin llave de idempotencia, dos peticiones concurrentes pueden alcanzar el mismo folio. La segunda contesta
folio_conflict con un 409, y reintentar es lo correcto:
tomará el siguiente número. Con llave no pasa, porque las dos terminan hablando de la misma factura.