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.
Si el PAC no contestó
Un pac_unavailable no es un rechazo: el PAC no contestó a tiempo, y pudo haber
timbrado. Esa llave no se libera. Reintenta con la misma llave: primero le preguntamos al PAC si timbró ese
comprobante.
Si lo timbró, te devolvemos la factura timbrada con Idempotency-Replayed: true. Si no,
la timbramos con el mismo folio. Si el PAC sigue sin contestar, te devolvemos otra vez
pac_unavailable y puedes reintentar más tarde.
Lo que se timbra es lo que mandó la primera llamada, con su receptor y sus conceptos. Lo que traiga el cuerpo del reintento no se lee: el PAC pudo haber timbrado la primera, y timbrar otros datos sería un segundo comprobante. Para facturar con datos distintos, usa otra llave.
Si una factura de antes de este cambio quedó sin respuesta del PAC, no tenemos con qué preguntarle. Te contestamos
stamping_unconfirmed: búscala en el SAT por su folio y, si no aparece, vuelve a
timbrarla con otra llave.
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.
Si repites la llamada con la misma llave mientras la primera sigue esperando al PAC, te contestamos
201 con status: "stamping" y sin
uuid. Todavía no es la respuesta: vuelve a preguntar en unos segundos con la misma
llave.