Recuperación
Qué hacer cuando pierdes una clave o un secreto, cuando tu receptor se cae y cuando algo queda a medias.
Esta página es un índice para los días malos. Busca tu situación y sigue el enlace.
| Lo que pasó | Qué hacer |
|---|---|
| Se te filtró una API key, o toca renovarla | Rotarla desde el panel y revocar la anterior. |
| Perdiste todas tus API keys | Pedir una sustituta. |
| Perdiste o filtraste el secreto de un destino de webhook | Rotar el secreto. |
| Tu receptor se va a caer o va a cambiar de dirección | Desactivarlo o cambiarle la URL. |
| Tu receptor no guardó unos avisos | Consultar y reproducir eventos. |
| No sabes si una factura llegó a crearse | Reintentar sin duplicar. |
Un archivo quedó en failed | Reintentar el archivo. |
Una entrega quedó en failed o action_required | Recuperar la entrega. |
| Un documento se quedó bloqueado antes de llegar a la DIAN | Reanudarlo. |
Perdiste la credencial inicial
Un secreto perdido no se recupera: se sustituye.
Casi siempre basta con entrar al panel, crear una clave nueva en API keys y revocar la perdida. Todas las claves de tu cuenta pueden lo mismo, así que ninguna es irreemplazable.
Escríbenos solo si perdiste también el acceso al panel. Un operador de Cufy verificará tu identidad fuera de este canal y emitirá una credencial sustituta:
- Se revoca la inicial vigente y se entrega otra, con los mismos permisos, una sola vez.
- Las demás claves de tu cuenta no se tocan.
- Los documentos ya emitidos siguen su curso.
Rotar el secreto de un destino
El secreto con el que firmamos tus webhooks se entrega una vez, al registrar el destino. Si lo pierdes o sospechas que se filtró, rótalo.
Consulta el destino con GET /v1/webhook-endpoints/{id} y guarda su ETag.
Llama POST /v1/webhook-endpoints/{id}/secret-rotations con If-Match, Idempotency-Key y un cuerpo así:
{ "overlap_seconds": 3600, "reason": "Rotación programada del secreto" }overlap_seconds va de 0 a 86400: es cuánto tiempo seguirá valiendo el secreto anterior. La respuesta trae secret, key_id y previous_key_expires_at, y los trae una sola vez.
Instala el secreto nuevo en tu receptor sin quitar el anterior hasta que pase previous_key_expires_at. Tu receptor debe guardar los dos y elegir por el encabezado X-Cufy-Key-Id de cada aviso (ver Verificar y recibir).
Vuelve a consultar el destino para obtener su ETag nuevo antes de tocarlo otra vez.
Los envíos siguientes usan la clave nueva; un intento ya preparado puede llegar todavía con la anterior. Si perdiste el secreto por completo y prefieres cortar de inmediato, usa overlap_seconds: 0 y asume que perderás los avisos en vuelo.
Desactivar un receptor
Si tu receptor va a estar caído (un despliegue, un mantenimiento) o va a cambiar de dirección:
- Consulta el destino y guarda su
ETag. - Llama
PATCH /v1/webhook-endpoints/{id}con todos los campos de entrada —url,event_typesyactive— másIf-MatcheIdempotency-Key. Es un reemplazo, no un parche parcial: lo que no envías, se pierde.
{
"url": "https://tu-proyecto.example/webhooks/cufy",
"event_types": ["document.validated", "document.rejected"],
"active": false
}Desactivar detiene los envíos nuevos; uno ya preparado puede estar en camino. Los eventos se siguen registrando mientras tanto, así que puedes reproducirlos cuando vuelvas.
Para mudarte de dirección, cambia url con esa misma llamada. Los envíos antiguos no se redirigen al destino nuevo: quedan fallidos y se recuperan con un replay.
Consultar y reproducir eventos
Lista los eventos con GET /v1/webhook-events y compáralos con lo que guardaste. El identificador de un evento es event_id.
Mira qué pasó con el que falta: GET /v1/webhook-events/{id}/attempts muestra cada intento y el código HTTP que respondiste.
Reprodúcelo con POST /v1/webhook-events/{id}/replays, indicando a qué destino: { "endpoint_id": "…", "reason": "Recuperar el aviso tras restablecer el receptor" }. Lleva su Idempotency-Key.
Se puede hasta 30 días después del evento, solo si no hay envíos pendientes de ese destino, y con un minuto de espera entre replays del mismo evento.
Un replay entrega el mismo event_id, así que tu receptor tiene que deduplicar. Detalle en Reintentos y replay.
Ante cualquier duda, consulta el documento: el aviso solo dice que algo cambió, y la verdad está en GET /v1/documents/{id}.
Reintentos y replay
Qué hace Cufy cuando tu receptor no contesta, cómo ver los intentos y cómo pedir que te reenvíen un aviso.
Consultar empresa propia GET
**Estado:** implementada. **Ambientes:** simulation, qualification. **Permisos:** `company:read`. **Alcance:** Perfil y estado actuales; updated_at refleja cambios de perfil, versión o estado. Consultar empresa propia