Idempotencia y reintentos
Idempotency-Key es opcional en las mutaciones. Recomendamos utilizarla, especialmente al crear borradores y timbrar.
Una clave representa una solicitud lógica. Guárdala en tu sistema antes de enviar la solicitud y reutilízala ante un reintento de la misma ruta, método y contenido.
POST /api/v1/invoice-draftsX-API-Key: fc_test_...Content-Type: application/jsonIdempotency-Key: pedido-1001-crear-borradorPara timbrar ese borrador, utiliza otra clave, por ejemplo pedido-1001-timbrar. No generes una clave nueva por cada intento de transporte.
Qué sucede al repetir una solicitud
Sección titulada «Qué sucede al repetir una solicitud»| Situación | Resultado |
|---|---|
| Misma clave y solicitud terminada | Se reproduce la respuesta registrada |
| Misma clave con otro contenido | 409 idempotency_conflict; se conserva la respuesta original |
| Solicitud todavía en curso | 409 idempotency_in_progress |
| Solicitud sin clave | Se trata como una operación independiente |
La clave admite hasta 255 caracteres y no caduca automáticamente. Su ámbito incluye la API key, el método y la ruta. Al rotar la API key, no asumas que se comparte el historial de idempotencia.
Un timeout durante el timbrado
Sección titulada «Un timeout durante el timbrado»El proveedor puede haber emitido el CFDI aunque tu sistema no haya recibido la respuesta. Consulta el documento original por su ID.
FactuCat protege el timbrado del mismo borrador contra solicitudes simultáneas. Una respuesta ambigua mantiene la operación bloqueada hasta conocer el resultado. El paso del tiempo por sí solo no libera esa protección.
Las confirmaciones guardadas se recuperan por conciliación sin repetir el timbrado. Si el resultado sigue siendo desconocido, comparte con soporte el ID del documento y el request ID. No envíes la llave ni el XML completo en un log de soporte.
Cuándo usar una clave nueva
Sección titulada «Cuándo usar una clave nueva»Utiliza una clave nueva para una operación nueva o cuando corrijas el contenido después de un error de validación. Una respuesta de error también puede quedar registrada bajo la clave original.
El SDK genera una clave automáticamente por mutación y la conserva en su reintento de transporte. Una llamada nueva genera otra clave. Para continuar la misma operación después de reiniciar tu aplicación, proporciona una clave que tú hayas persistido mediante idempotencyKey.