@openfactura/cli 0.1.0 → 0.2.0

package/README.md

@@ -21,7 +21,7 @@ npx @openfactura/cli --help
 
 ## Inicio de sesión
 
-Cree una clave de API en el panel web (Ajustes → Claves de API). Las claves `of_test_…` trabajan contra
+Cree una clave de API en el panel web (Desarrolladores → Nueva clave). Las claves `of_test_…` trabajan contra
 el ambiente de pruebas del MH y las `of_live_…` contra producción.
 
 ```bash
@@ -220,7 +220,45 @@ openfactura dte invalidar <codigo> --tipo 1 --reemplazo <codigo-del-dte-que-lo-c
 ```
 
 `--tipo`: `1` error en la información (requiere `--reemplazo`), `2` rescindir la operación, `3` otro
-(requiere `--motivo` y `--reemplazo`). La invalidación es irreversible.
+(requiere `--motivo` y `--reemplazo`). La invalidación es irreversible. El mismo comando invalida un
+evento de retorno u operaciones especiales si recibe su código. Un DTE con un retorno vigente no se
+invalida hasta invalidar antes el retorno.
+
+#### Retorno (evento 18)
+
+Devolución de bienes, reembolso o envases sobre una Factura (01), Factura de Exportación (11) o Sujeto
+Excluido (14) procesados, sin invalidar el documento. Plazo: 3 meses desde la fecha del documento.
+
+```bash
+echo '{ "items": [{ "descripcion": "Silla", "cantidad": 1, "precioUni": 22.6 }] }' \
+  | openfactura dte retorno 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4 -
+```
+
+`precioUni` va como en el documento original: en Factura con IVA, en 11 y 14 sin IVA. Como `dte emitir`,
+lleva `Idempotency-Key` y pide confirmación con una clave `of_live_…`.
+
+### Eventos
+
+```bash
+openfactura eventos operaciones-especiales simplificadas.json   # evento 17
+openfactura eventos list --tipo retorno
+openfactura eventos get <codigo>
+openfactura eventos json <codigo> -o retorno.json
+openfactura eventos pdf <codigo> -o retorno.pdf
+```
+
+El archivo de operaciones especiales informa facturas simplificadas (`"tipoDocumento": "02"`, por rangos)
+o comprobantes de control interno (`"97"`):
+
+```json
+{
+  "tipoDocumento": "02",
+  "fecha": "2026-10-31",
+  "items": [
+    { "descripcion": "Facturas simplificadas", "docDel": "1", "docAl": "25", "precioUni": 10 }
+  ]
+}
+```
 
 ### Contingencia
 
@@ -228,9 +266,30 @@ openfactura dte invalidar <codigo> --tipo 1 --reemplazo <codigo-del-dte-que-lo-c
 openfactura contingencia transmitir
 ```
 
+### Webhooks
+
+Su sistema recibe un `POST` firmado cuando un documento cambia de estado. La clave necesita el permiso
+`webhooks:manage`.
+
+```bash
+openfactura webhooks add https://erp.su-empresa.sv/hooks/openfactura \
+  --eventos dte.procesado,dte.rechazado --descripcion "ERP"   # sin --eventos: todos
+openfactura webhooks list
+openfactura webhooks test <id>          # envía webhook.prueba; salida 1 si no se entrega
+openfactura webhooks deliveries <id>    # últimas 50 entregas, con intentos y errores
+openfactura webhooks rotate <id>        # secreto nuevo; el anterior deja de firmar
+openfactura webhooks remove <id>
+```
+
+`add` y `rotate` muestran el secreto de firma (`whsec_…`) una sola vez. Eventos: `dte.procesado`,
+`dte.rechazado`, `dte.contingencia`, `dte.invalidado`, `retorno.procesado`,
+`operaciones_especiales.procesado`. Cómo verificar la cabecera `OpenFactura-Signature`: sección
+«Webhooks» de `docs/api.md` en el repositorio del servidor.
+
 ### Confirmación en producción
 
-Con una clave `of_live_…`, `dte emitir`, `dte invalidar` y `contingencia transmitir` piden confirmación
+Con una clave `of_live_…`, `dte emitir`, `dte retorno`, `eventos operaciones-especiales`,
+`dte invalidar` y `contingencia transmitir` piden confirmación
 porque tienen efecto fiscal. Use `--yes` para omitirla. Si no hay una terminal interactiva (un script,
 una tubería, `dte emitir -`), la CLI no pregunta: exige `--yes` y termina con salida `2` si falta.
 
@@ -274,10 +333,13 @@ clientes que no pueden enviar un encabezado HTTP fijo al servidor MCP remoto (`/
 herramientas que el remoto y las ejecuta llamando a la API REST con su clave:
 
 `emisor_obtener`, `catalogo_buscar`, `clientes_buscar`, `cliente_crear`, `productos_buscar`,
-`producto_crear`, `dte_validar`, `dte_emitir`, `dte_listar`, `dte_obtener`, `dte_invalidar`.
+`producto_crear`, `dte_validar`, `dte_emitir`, `dte_listar`, `dte_obtener`, `dte_invalidar`,
+`dte_retorno`, `operaciones_especiales_informar`, `eventos_listar`, `evento_obtener`,
+`webhooks_listar`, `webhook_crear`, `webhook_eliminar`, `webhook_probar`.
 
 Cada herramienta exige el mismo permiso que su ruta REST, así que la clave decide qué puede hacer el
-asistente. Empiece con una clave `of_test_…`; `dte_emitir` y `dte_invalidar` tienen efecto fiscal con una
+asistente. Empiece con una clave `of_test_…`; `dte_emitir`, `dte_retorno`, `operaciones_especiales_informar` y
+`dte_invalidar` tienen efecto fiscal con una
 clave `of_live_…`, y aquí no hay confirmación de la CLI: la da usted en su cliente MCP al aprobar la
 llamada.
 

package/dist/index.js

@@ -6,7 +6,7 @@ import { parseArgs } from "util";
 // package.json
 var package_default = {
   name: "@openfactura/cli",
-  version: "0.1.0",
+  version: "0.2.0",
   description: "Cliente de l\xEDnea de comandos y servidor MCP (stdio) de Open Factura: facturaci\xF3n electr\xF3nica de El Salvador (DTE).",
   license: "MIT",
   repository: {
@@ -257,6 +257,56 @@ var invalidacion = z.object({
   solicitante: persona.optional(),
   responsable: persona.optional()
 });
+var fecha = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use el formato AAAA-MM-DD");
+var retorno = z.object({
+  items: z.array(
+    z.object({
+      descripcion: texto(1e3),
+      cantidad: z.number().positive(),
+      precioUni: z.number().nonnegative(),
+      tipoItem: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]).optional(),
+      codigo: opcional(25),
+      uniMedida: z.number().int().min(1).max(99).optional(),
+      descuento: z.number().nonnegative().optional(),
+      tipoVenta: z.enum(["gravada", "exenta", "noSujeta"]).optional(),
+      seguro: z.number().nonnegative().optional(),
+      flete: z.number().nonnegative().optional()
+    })
+  ).min(1).max(2e3).describe(
+    "Bienes que se retornan. precioUni: en Factura (01) CON IVA, como en la factura; en Exportaci\xF3n (11) y Sujeto Excluido (14) SIN IVA."
+  )
+});
+var operacionesEspeciales = z.object({
+  tipoDocumento: z.enum(["02", "97"]).describe("02 factura de venta simplificada (por rangos), 97 comprobante de control interno"),
+  fecha: fecha.optional().describe("Fecha del evento; define el periodo informado"),
+  items: z.array(
+    z.object({
+      descripcion: texto(1500),
+      precioUni: z.number().nonnegative().describe("SIN IVA"),
+      cantidad: z.number().int().positive().optional(),
+      numDocumento: opcional(36),
+      docDel: z.string().trim().min(1).max(36).optional(),
+      docAl: z.string().trim().min(1).max(36).optional(),
+      fechaEmision: fecha.optional(),
+      tipoVenta: z.enum(["gravada", "exenta", "noSujeta"]).optional(),
+      codigoGeneracionRef: z.string().length(36).optional()
+    })
+  ).min(1).max(2e3)
+});
+var EVENTOS_WEBHOOK = [
+  "dte.procesado",
+  "dte.rechazado",
+  "dte.contingencia",
+  "dte.invalidado",
+  "retorno.procesado",
+  "operaciones_especiales.procesado"
+];
+var webhook = z.object({
+  url: z.string().max(2e3).describe("URL https:// p\xFAblica que recibir\xE1 los POST firmados"),
+  descripcion: opcional(200),
+  eventos: z.array(z.enum(EVENTOS_WEBHOOK)).min(1).describe("Eventos a los que se suscribe"),
+  activo: z.boolean().optional()
+});
 
 // src/http.ts
 var TIEMPO_LIMITE_MS = 6e4;
@@ -522,7 +572,7 @@ function crearServidorMcp(api, version) {
     "dte_invalidar",
     {
       title: "Invalidar un DTE",
-      description: "Transmite el evento de invalidaci\xF3n de un DTE procesado. Es irreversible y tiene efecto fiscal: confirme con el usuario. tipoAnulacion: 1 error en la informaci\xF3n (requiere codigoGeneracionReemplazo), 2 rescindir la operaci\xF3n, 3 otro (requiere motivo y reemplazo).",
+      description: "Transmite el evento de invalidaci\xF3n de un DTE procesado, o de un evento de retorno u operaciones especiales (use su c\xF3digo de generaci\xF3n). Un DTE con retorno vigente exige invalidar antes el retorno. Es irreversible y tiene efecto fiscal: confirme con el usuario. tipoAnulacion: 1 error en la informaci\xF3n (requiere codigoGeneracionReemplazo), 2 rescindir la operaci\xF3n, 3 otro (requiere motivo y reemplazo).",
       inputSchema: z2.object({ codigoGeneracion: z2.string(), ...invalidacion.shape }),
       annotations: {
         readOnlyHint: false,
@@ -535,6 +585,122 @@ function crearServidorMcp(api, version) {
       () => api.pedir("POST", `/dte/${ruta(codigoGeneracion)}/invalidar`, { cuerpo: entrada })
     )
   );
+  servidor.registerTool(
+    "dte_retorno",
+    {
+      title: "Registrar un retorno (evento 18)",
+      description: "Transmite un Evento de Retorno sobre una Factura (01), Factura de Exportaci\xF3n (11) o Sujeto Excluido (14) procesados: devoluci\xF3n de bienes, reembolso o envases, sin invalidar el documento. Plazo: 3 meses desde la fecha del DTE. La suma de retornos no puede superar el DTE. Tiene efecto fiscal: confirme con el usuario. Para un Cr\xE9dito Fiscal use una Nota de Cr\xE9dito (05).",
+      inputSchema: z2.object({
+        codigoGeneracion: z2.string().describe("C\xF3digo de generaci\xF3n del DTE original"),
+        ...retorno.shape,
+        idempotencyKey: z2.string().min(8).max(200).describe(
+          "Identificador \xFAnico de este intento. Repetirlo devuelve el mismo resultado sin transmitir dos veces."
+        )
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    ({ codigoGeneracion, idempotencyKey, ...entrada }) => responder(
+      () => api.pedir("POST", `/dte/${ruta(codigoGeneracion)}/retorno`, {
+        cuerpo: entrada,
+        headers: { "Idempotency-Key": idempotencyKey }
+      })
+    )
+  );
+  servidor.registerTool(
+    "operaciones_especiales_informar",
+    {
+      title: "Informar operaciones especiales (evento 17)",
+      description: "Transmite un Evento de Operaciones Especiales: informa al MH las facturas simplificadas (02, siempre por rangos docDel\u2013docAl) o los comprobantes de control interno (97, uno a uno con numDocumento o por rangos, sin mezclar) de un periodo. precioUni SIN IVA. Los documentos anulados van en un evento aparte con codigoGeneracionRef. Tiene efecto fiscal: confirme con el usuario.",
+      inputSchema: z2.object({
+        ...operacionesEspeciales.shape,
+        idempotencyKey: z2.string().min(8).max(200).describe(
+          "Identificador \xFAnico de este intento. Repetirlo devuelve el mismo resultado sin transmitir dos veces."
+        )
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    ({ idempotencyKey, ...entrada }) => responder(
+      () => api.pedir("POST", "/eventos/operaciones-especiales", {
+        cuerpo: entrada,
+        headers: { "Idempotency-Key": idempotencyKey }
+      })
+    )
+  );
+  servidor.registerTool(
+    "eventos_listar",
+    {
+      title: "Listar eventos",
+      description: "Eventos de retorno y de operaciones especiales del ambiente activo (los 50 m\xE1s recientes).",
+      inputSchema: z2.object({ tipo: z2.enum(["retorno", "operaciones_especiales"]).optional() }),
+      annotations: lectura
+    },
+    ({ tipo }) => responder(() => api.pedir("GET", "/eventos", { query: { tipo } }))
+  );
+  servidor.registerTool(
+    "evento_obtener",
+    {
+      title: "Ver un evento",
+      description: "Detalle de un evento por c\xF3digo de generaci\xF3n: estado, sello, JSON oficial y respuesta del MH.",
+      inputSchema: z2.object({ codigoGeneracion: z2.string() }),
+      annotations: lectura
+    },
+    ({ codigoGeneracion }) => responder(() => api.pedir("GET", `/eventos/${ruta(codigoGeneracion)}`))
+  );
+  servidor.registerTool(
+    "webhooks_listar",
+    {
+      title: "Listar webhooks",
+      description: "Webhooks de la organizaci\xF3n: URL, eventos suscritos y si est\xE1n activos. Nunca devuelve el secreto de firma.",
+      inputSchema: z2.object({}),
+      annotations: lectura
+    },
+    () => responder(() => api.pedir("GET", "/webhooks"))
+  );
+  servidor.registerTool(
+    "webhook_crear",
+    {
+      title: "Crear webhook",
+      description: `Registra una URL https:// que recibir\xE1 un POST firmado cuando cambie el estado de un documento. Eventos: ${EVENTOS_WEBHOOK.join(", ")}. Devuelve el secreto de firma (whsec_\u2026) UNA sola vez: entr\xE9gueselo al usuario para que verifique la firma OpenFactura-Signature.`,
+      inputSchema: webhook,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    },
+    (datos) => responder(() => api.pedir("POST", "/webhooks", { cuerpo: datos }))
+  );
+  servidor.registerTool(
+    "webhook_eliminar",
+    {
+      title: "Eliminar webhook",
+      description: "Elimina un webhook y su historial de entregas. Deja de recibir notificaciones de inmediato. Confirme con el usuario.",
+      inputSchema: z2.object({ id: z2.string() }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ id }) => responder(() => api.pedir("DELETE", `/webhooks/${ruta(id)}`))
+  );
+  servidor.registerTool(
+    "webhook_probar",
+    {
+      title: "Probar webhook",
+      description: "Env\xEDa ya un evento webhook.prueba firmado a la URL del webhook y devuelve si respondi\xF3 2xx, su estado HTTP o el error.",
+      inputSchema: z2.object({ id: z2.string() }),
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true }
+    },
+    ({ id }) => responder(() => api.pedir("POST", `/webhooks/${ruta(id)}/probar`))
+  );
   return servidor;
 }
 function servirMcp(api, version) {
@@ -579,7 +745,7 @@ var siNo = (valor) => valor ? "s\xED" : "no";
 // src/comandos.ts
 var nombreTipo = (codigo) => `${codigo} ${TIPOS_DTE[String(codigo)] ?? ""}`.trim();
 var nombreAmbiente = (codigo) => `${codigo} ${NOMBRE_AMBIENTE[String(codigo)] ?? ""}`.trim();
-var fecha = (ms) => typeof ms === "number" ? new Date(ms).toISOString().replace("T", " ").slice(0, 19) : ms;
+var fecha2 = (ms) => typeof ms === "number" ? new Date(ms).toISOString().replace("T", " ").slice(0, 19) : ms;
 var segmento = (texto2) => encodeURIComponent(texto2);
 function mostrar(ctx, datos, legible) {
   ctx.ent.stdout(ctx.json ? JSON.stringify(datos, null, 2) : legible());
@@ -959,36 +1125,45 @@ async function dteValidar(ctx) {
   });
   return problemas.length ? SALIDA.error : SALIDA.ok;
 }
-async function dteEmitir(ctx) {
-  const origen = ctx.args[0];
-  const cuerpo = await leerEmision(ctx, origen);
+async function enviarUnaVez(ctx, ruta2, cuerpo, qu\u00E9, reintento, stdin = false) {
   const api = ctx.api();
   const clave = ctx.op("idempotency-key") ?? randomUUID();
   if (clave.length < 1 || clave.length > 200)
     throw new ErrorUso("--idempotency-key debe tener entre 1 y 200 caracteres.");
-  await confirmar(ctx, `emitir un DTE (${nombreTipo(cuerpo.tipoDte)})`, origen === "-");
+  await confirmar(ctx, qu\u00E9, stdin);
   ctx.ent.stderr(`Idempotency-Key: ${clave}`);
-  let respuesta;
   try {
-    respuesta = await api.pedir("POST", "/dte", {
+    const respuesta = await api.pedir("POST", ruta2, {
       cuerpo,
       headers: { "Idempotency-Key": clave }
     });
+    if (respuesta.headers.get("Idempotent-Replayed") === "true") {
+      ctx.ent.stderr(
+        "Respuesta repetida: esta Idempotency-Key ya se hab\xEDa usado; no se transmiti\xF3 de nuevo."
+      );
+    }
+    return respuesta.datos;
   } catch (error) {
     if (error instanceof ErrorCli && (error.code === "sin_conexion" || error.code === "tiempo_agotado")) {
       ctx.ent.stderr(
-        `No se sabe si el DTE se emiti\xF3. Reintente con la misma clave para no emitir dos veces:
-  openfactura dte emitir ${origen} --idempotency-key ${clave}`
+        `No se sabe si se transmiti\xF3. Reintente con la misma clave para no duplicarlo:
+  openfactura ${reintento} --idempotency-key ${clave}`
       );
     }
     throw error;
   }
-  const doc = respuesta.datos;
-  if (respuesta.headers.get("Idempotent-Replayed") === "true") {
-    ctx.ent.stderr(
-      "Respuesta repetida: esta Idempotency-Key ya se hab\xEDa usado; no se emiti\xF3 de nuevo."
-    );
-  }
+}
+async function dteEmitir(ctx) {
+  const origen = ctx.args[0];
+  const cuerpo = await leerEmision(ctx, origen);
+  const doc = await enviarUnaVez(
+    ctx,
+    "/dte",
+    cuerpo,
+    `emitir un DTE (${nombreTipo(cuerpo.tipoDte)})`,
+    `dte emitir ${origen}`,
+    origen === "-"
+  );
   if (doc.estado === "contingencia") {
     ctx.ent.stderr(
       "El MH no respondi\xF3: el DTE qued\xF3 firmado en contingencia. Transm\xEDtalo con `openfactura contingencia transmitir`."
@@ -1073,7 +1248,7 @@ async function dteGet(ctx) {
           eventos.map((e) => [
             e.tipo,
             e.estado,
-            fecha(e.creado),
+            fecha2(e.creado),
             e.codigoGeneracion,
             e.selloRecibido
           ])
@@ -1129,6 +1304,117 @@ async function dteInvalidar(ctx) {
 ${fichaDocumento(datos)}`);
   return void 0;
 }
+var TIPOS_EVENTO = ["retorno", "operaciones_especiales"];
+function fichaEvento(e) {
+  return fichas([
+    [
+      "Evento",
+      e.tipoEvento === "18" ? "18 Retorno" : e.tipoEvento === "17" ? "17 Operaciones especiales" : e.tipo
+    ],
+    ["Estado", e.estado],
+    ["C\xF3digo de generaci\xF3n", e.codigoGeneracion],
+    ["Ambiente", nombreAmbiente(e.ambiente)],
+    ["Sello recibido", e.selloRecibido]
+  ]);
+}
+async function leerObjeto(ctx, origen, forma) {
+  const cuerpo = await leerJson(ctx, origen);
+  if (!cuerpo || typeof cuerpo !== "object" || Array.isArray(cuerpo) || !("items" in cuerpo)) {
+    throw new ErrorUso(`El archivo debe ser un objeto ${forma}`);
+  }
+  return cuerpo;
+}
+async function dteRetorno(ctx) {
+  const [codigo, origen] = ctx.args;
+  const cuerpo = await leerObjeto(
+    ctx,
+    origen,
+    '{ "items": [{ "descripcion", "cantidad", "precioUni" }] }'
+  );
+  const evento = await enviarUnaVez(
+    ctx,
+    `/dte/${segmento(codigo)}/retorno`,
+    cuerpo,
+    `registrar un retorno sobre el DTE ${codigo}`,
+    `dte retorno ${codigo} ${origen}`,
+    origen === "-"
+  );
+  mostrar(ctx, evento, () => `Retorno registrado.
+${fichaEvento(evento)}`);
+  return void 0;
+}
+async function eventosOperacionesEspeciales(ctx) {
+  const origen = ctx.args[0];
+  const cuerpo = await leerObjeto(
+    ctx,
+    origen,
+    '{ "tipoDocumento": "02" | "97", "fecha"?, "items": [{ "descripcion", "precioUni", "docDel", "docAl" }] }'
+  );
+  const evento = await enviarUnaVez(
+    ctx,
+    "/eventos/operaciones-especiales",
+    cuerpo,
+    "informar operaciones especiales",
+    `eventos operaciones-especiales ${origen}`,
+    origen === "-"
+  );
+  mostrar(ctx, evento, () => `Operaciones especiales informadas.
+${fichaEvento(evento)}`);
+  return void 0;
+}
+async function eventosList(ctx) {
+  const tipo = ctx.op("tipo");
+  if (tipo !== void 0 && !TIPOS_EVENTO.includes(tipo)) {
+    throw new ErrorUso(`--tipo debe ser uno de: ${TIPOS_EVENTO.join(", ")}`);
+  }
+  const { datos } = await ctx.api().pedir("GET", "/eventos", { query: { tipo } });
+  mostrar(
+    ctx,
+    datos,
+    () => datos.length ? tabla(
+      ["creado", "evento", "estado", "c\xF3digo de generaci\xF3n"],
+      datos.map((e) => [
+        new Date(e.creado).toISOString().slice(0, 10),
+        e.tipoEvento,
+        e.estado,
+        e.codigoGeneracion
+      ])
+    ) : "No hay eventos."
+  );
+  return void 0;
+}
+async function eventosGet(ctx) {
+  const { datos } = await ctx.api().pedir("GET", `/eventos/${segmento(ctx.args[0])}`);
+  mostrar(ctx, datos, () => fichaEvento(datos));
+  return void 0;
+}
+async function eventosJson(ctx) {
+  const codigo = ctx.args[0];
+  const { datos } = await ctx.api().pedir("GET", `/eventos/${segmento(codigo)}/json`);
+  const texto2 = JSON.stringify(datos, null, 2);
+  const salida = ctx.op("output");
+  if (salida === void 0) {
+    ctx.ent.stdout(texto2);
+    return void 0;
+  }
+  const destino = resolve(ctx.ent.cwd, salida);
+  await writeFile(destino, `${texto2}
+`);
+  mostrar(ctx, { archivo: destino }, () => `JSON guardado en ${destino}`);
+  return void 0;
+}
+async function eventosPdf(ctx) {
+  const codigo = ctx.args[0];
+  const bytes = await ctx.api().descargar(`/eventos/${segmento(codigo)}/pdf`);
+  const destino = resolve(ctx.ent.cwd, ctx.op("output") ?? `${basename(codigo)}.pdf`);
+  await writeFile(destino, bytes);
+  mostrar(
+    ctx,
+    { archivo: destino, bytes: bytes.length },
+    () => `PDF guardado en ${destino} (${bytes.length} bytes)`
+  );
+  return void 0;
+}
 async function contingenciaTransmitir(ctx) {
   const api = ctx.api();
   await confirmar(ctx, "transmitir los DTE en contingencia");
@@ -1150,6 +1436,113 @@ async function contingenciaTransmitir(ctx) {
   });
   return void 0;
 }
+function fichaWebhook(w) {
+  return fichas([
+    ["Id", w.id],
+    ["URL", w.url],
+    ["Descripci\xF3n", w.descripcion],
+    ["Eventos", Array.isArray(w.eventos) ? w.eventos.join(", ") : null],
+    ["Activo", siNo(w.activo)]
+  ]);
+}
+function mostrarSecreto(ctx, w, titulo) {
+  mostrar(
+    ctx,
+    w,
+    () => [
+      titulo,
+      fichaWebhook(w),
+      "",
+      `Secreto de firma: ${w.secreto}`,
+      "Gu\xE1rdelo ahora: no se vuelve a mostrar. Verifique con \xE9l la cabecera OpenFactura-Signature."
+    ].join("\n")
+  );
+}
+async function webhooksList(ctx) {
+  const { datos } = await ctx.api().pedir("GET", "/webhooks");
+  mostrar(
+    ctx,
+    datos,
+    () => datos.length ? tabla(
+      ["id", "url", "eventos", "activo", "descripci\xF3n"],
+      datos.map((w) => [
+        w.id,
+        w.url,
+        w.eventos.join(", "),
+        siNo(w.activo),
+        w.descripcion
+      ])
+    ) : "No hay webhooks."
+  );
+  return void 0;
+}
+async function webhooksAdd(ctx) {
+  const texto2 = ctx.op("eventos");
+  const eventos = texto2 ? texto2.split(",").map((e) => e.trim()).filter(Boolean) : [...EVENTOS_WEBHOOK];
+  const desconocido = eventos.find((e) => !EVENTOS_WEBHOOK.includes(e));
+  if (desconocido || !eventos.length) {
+    throw new ErrorUso(`--eventos acepta, separados por coma: ${EVENTOS_WEBHOOK.join(", ")}`);
+  }
+  const cuerpo = { url: ctx.args[0], eventos };
+  if (ctx.op("descripcion") !== void 0) cuerpo.descripcion = ctx.op("descripcion");
+  const { datos } = await ctx.api().pedir("POST", "/webhooks", { cuerpo });
+  mostrarSecreto(ctx, datos, "Webhook creado.");
+  return void 0;
+}
+async function webhooksRemove(ctx) {
+  const id = ctx.args[0];
+  const { datos } = await ctx.api().pedir("DELETE", `/webhooks/${segmento(id)}`);
+  mostrar(ctx, datos, () => `Webhook ${id} eliminado.`);
+  return void 0;
+}
+async function webhooksTest(ctx) {
+  const id = ctx.args[0];
+  const { datos } = await ctx.api().pedir("POST", `/webhooks/${segmento(id)}/probar`);
+  mostrar(
+    ctx,
+    datos,
+    () => datos.entregado ? `Entregado: el destino respondi\xF3 HTTP ${datos.status}.` : `No se entreg\xF3: ${datos.error ?? "error desconocido"}.`
+  );
+  return datos.entregado ? SALIDA.ok : SALIDA.error;
+}
+async function webhooksDeliveries(ctx) {
+  const id = ctx.args[0];
+  const { datos } = await ctx.api().pedir("GET", `/webhooks/${segmento(id)}/entregas`);
+  mostrar(
+    ctx,
+    datos,
+    () => datos.length ? tabla(
+      [
+        "creado (UTC)",
+        "evento",
+        "estado",
+        "intentos",
+        "http",
+        "error",
+        "pr\xF3ximo intento",
+        "id"
+      ],
+      datos.map((e) => [
+        fecha2(e.creado),
+        e.evento,
+        e.estado,
+        e.intentos,
+        e.ultimoStatus,
+        e.ultimoError,
+        fecha2(e.proximoIntento),
+        e.id
+      ]),
+      [3]
+    ) : "Este webhook todav\xEDa no tiene entregas."
+  );
+  return void 0;
+}
+async function webhooksRotate(ctx) {
+  const id = ctx.args[0];
+  const { datos } = await ctx.api().pedir("POST", `/webhooks/${segmento(id)}/rotar-secreto`);
+  mostrarSecreto(ctx, datos, "Secreto rotado: el anterior ya no firma.");
+  return void 0;
+}
 async function mcp(ctx) {
   const api = ctx.api();
   ctx.ent.stderr(
@@ -1162,7 +1555,9 @@ var GRUPOS = {
   clientes: "Clientes guardados",
   productos: "Productos y servicios guardados",
   dte: "Documentos tributarios electr\xF3nicos",
-  contingencia: "Documentos emitidos en contingencia"
+  eventos: "Eventos de retorno (18) y de operaciones especiales (17)",
+  contingencia: "Documentos emitidos en contingencia",
+  webhooks: "Notificaciones firmadas a su sistema cuando cambia un documento"
 };
 var COMANDOS = [
   {
@@ -1288,11 +1683,59 @@ var COMANDOS = [
   {
     nombre: "dte invalidar",
     uso: "dte invalidar <codigoGeneracion> --tipo <1|2|3> [--motivo <texto>] [--reemplazo <codigo>] [--yes]",
-    resumen: "Invalida un DTE procesado (irreversible)",
+    resumen: "Invalida un DTE procesado, o un evento de retorno u operaciones especiales (irreversible)",
     opciones: ["tipo", "motivo", "reemplazo", "yes"],
     args: [1, 1],
     accion: dteInvalidar
   },
+  {
+    nombre: "dte retorno",
+    uso: "dte retorno <codigoGeneracion> <archivo.json | -> [--idempotency-key <k>] [--yes]",
+    resumen: "Registra un retorno (evento 18) sobre una Factura, Exportaci\xF3n o Sujeto Excluido",
+    opciones: ["idempotency-key", "yes"],
+    args: [2, 2],
+    accion: dteRetorno
+  },
+  {
+    nombre: "eventos operaciones-especiales",
+    uso: "eventos operaciones-especiales <archivo.json | -> [--idempotency-key <k>] [--yes]",
+    resumen: "Informa facturas simplificadas o comprobantes de control interno (evento 17)",
+    opciones: ["idempotency-key", "yes"],
+    args: [1, 1],
+    accion: eventosOperacionesEspeciales
+  },
+  {
+    nombre: "eventos list",
+    uso: "eventos list [--tipo retorno|operaciones_especiales]",
+    resumen: "Lista los eventos de retorno y operaciones especiales",
+    opciones: ["tipo"],
+    args: [0, 0],
+    accion: eventosList
+  },
+  {
+    nombre: "eventos get",
+    uso: "eventos get <codigoGeneracion>",
+    resumen: "Muestra un evento",
+    opciones: [],
+    args: [1, 1],
+    accion: eventosGet
+  },
+  {
+    nombre: "eventos json",
+    uso: "eventos json <codigoGeneracion> [-o <archivo.json>]",
+    resumen: "Descarga el archivo JSON oficial del evento",
+    opciones: ["output"],
+    args: [1, 1],
+    accion: eventosJson
+  },
+  {
+    nombre: "eventos pdf",
+    uso: "eventos pdf <codigoGeneracion> [-o <archivo.pdf>]",
+    resumen: "Descarga la representaci\xF3n gr\xE1fica del evento",
+    opciones: ["output"],
+    args: [1, 1],
+    accion: eventosPdf
+  },
   {
     nombre: "contingencia transmitir",
     uso: "contingencia transmitir [--yes]",
@@ -1301,6 +1744,54 @@ var COMANDOS = [
     args: [0, 0],
     accion: contingenciaTransmitir
   },
+  {
+    nombre: "webhooks list",
+    uso: "webhooks list",
+    resumen: "Lista los webhooks (sin su secreto)",
+    opciones: [],
+    args: [0, 0],
+    accion: webhooksList
+  },
+  {
+    nombre: "webhooks add",
+    uso: "webhooks add <https://url> [--eventos <e1,e2>] [--descripcion <texto>]",
+    resumen: "Crea un webhook y muestra su secreto de firma una sola vez",
+    opciones: ["eventos", "descripcion"],
+    args: [1, 1],
+    accion: webhooksAdd
+  },
+  {
+    nombre: "webhooks remove",
+    uso: "webhooks remove <id>",
+    resumen: "Elimina un webhook y su historial de entregas",
+    opciones: [],
+    args: [1, 1],
+    accion: webhooksRemove
+  },
+  {
+    nombre: "webhooks test",
+    uso: "webhooks test <id>",
+    resumen: "Env\xEDa un evento webhook.prueba (salida 1 si no se entrega)",
+    opciones: [],
+    args: [1, 1],
+    accion: webhooksTest
+  },
+  {
+    nombre: "webhooks deliveries",
+    uso: "webhooks deliveries <id>",
+    resumen: "\xDAltimas 50 entregas de un webhook",
+    opciones: [],
+    args: [1, 1],
+    accion: webhooksDeliveries
+  },
+  {
+    nombre: "webhooks rotate",
+    uso: "webhooks rotate <id>",
+    resumen: "Genera un secreto de firma nuevo y lo muestra una vez",
+    opciones: [],
+    args: [1, 1],
+    accion: webhooksRotate
+  },
   {
     nombre: "mcp",
     uso: "mcp",
@@ -1337,7 +1828,7 @@ var OPCIONES = {
   },
   tipo: {
     type: "string",
-    ayuda: "Tipo de DTE (01, 03\u2026) o, al invalidar, tipo de anulaci\xF3n (1, 2, 3)"
+    ayuda: "Tipo de DTE (01, 03\u2026); al invalidar, tipo de anulaci\xF3n (1, 2, 3); en eventos, retorno | operaciones_especiales"
   },
   estado: {
     type: "string",
@@ -1365,7 +1856,11 @@ var OPCIONES = {
   telefono: { type: "string", ayuda: "Tel\xE9fono" },
   correo: { type: "string", ayuda: "Correo electr\xF3nico" },
   codigo: { type: "string", ayuda: "C\xF3digo del producto" },
-  descripcion: { type: "string", ayuda: "Descripci\xF3n del producto" },
+  descripcion: { type: "string", ayuda: "Descripci\xF3n (del producto o del webhook)" },
+  eventos: {
+    type: "string",
+    ayuda: "Eventos del webhook separados por coma (por defecto todos): dte.procesado, dte.rechazado, dte.contingencia, dte.invalidado, retorno.procesado, operaciones_especiales.procesado"
+  },
   precio: { type: "string", ayuda: "Precio unitario SIN IVA" },
   "tipo-item": {
     type: "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfactura/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Cliente de línea de comandos y servidor MCP (stdio) de Open Factura: facturación electrónica de El Salvador (DTE).",
   "license": "MIT",
   "repository": {