From c1617a2e068bcff4690327b75317e7e98516563e Mon Sep 17 00:00:00 2001 From: mendozagit Date: Wed, 14 Oct 2026 08:55:00 -0600 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20la=20gu=C3=ADa=20de=20webhooks=20pa?= =?UTF-8?q?sa=20a=20docs.fiscalapi.com/webhooks-info?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fapi-docs separa la guía (tutorial /webhooks-info) de la referencia de endpoints (/webhooks y /events). El README y listen.md enlazan a la guía: evento, firma y reintentos. --- README.md | 2 +- docs/listen.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5eb1854..2aef881 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ ambiente de pruebas ([detalles](docs/trigger.md)). | [Solución de problemas](docs/solucion-de-problemas.md) | Errores frecuentes con su causa y remedio. | `fiscalapi --help` y `fiscalapi --help` describen cada opción. La guía de webhooks de la API (forma del -evento, firma, reintentos) está en [docs.fiscalapi.com/webhooks](https://docs.fiscalapi.com/webhooks). +evento, firma, reintentos) está en [docs.fiscalapi.com/webhooks-info](https://docs.fiscalapi.com/webhooks-info). ## Desarrollo diff --git a/docs/listen.md b/docs/listen.md index fa3026f..baa5c46 100644 --- a/docs/listen.md +++ b/docs/listen.md @@ -142,7 +142,7 @@ timestamp, la firma verifica; si cambias un carácter del cuerpo, de la firma o | `webhook-signature` | `v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=` | La forma del evento y la verificación a mano en cada lenguaje están en la -[guía de webhooks de FiscalAPI](https://docs.fiscalapi.com/webhooks). +[guía de webhooks de FiscalAPI](https://docs.fiscalapi.com/webhooks-info). ## Conexión y sesiones From cf81f817b6f023b693a88d90db073d28b709ce30 Mon Sep 17 00:00:00 2001 From: mendozagit Date: Wed, 14 Oct 2026 09:12:48 -0600 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20salida=20real=20de=20--json,=20even?= =?UTF-8?q?ts=20retrieve,=20Actualizado=20y=20400=20de=20validaci=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Diferencias que encontró un E2E del CLI 0.1.0 contra el back: - --json imprime el data con GetRawText (ApiCommandContext.cs:34), es decir con el formato indentado de la API (WriteIndented en el back). Los ejemplos de una línea pasan a ese formato. - events retrieve muestra el evento como lo devuelve la API, no el cuerpo compacto que se entregó; se aclara que no sirve para verificar una firma. - webhooks create y retrieve siempre imprimen Actualizado (WebhookView.WriteDetail; al crear es igual a Creado). - Un 400 de validación pone el texto general en Detalle y una línea "- " por regla (ApiException.cs:73-76). - solucion-de-problemas: se separan el 401 sin header X-API-KEY y el 401 Invalid API KEY. --- docs/salida-y-codigos.md | 2 +- docs/solucion-de-problemas.md | 5 +++++ docs/trigger.md | 21 ++++++++++++++++-- docs/webhooks-y-eventos.md | 41 +++++++++++++++++++++++++---------- 4 files changed, 54 insertions(+), 15 deletions(-) diff --git a/docs/salida-y-codigos.md b/docs/salida-y-codigos.md index d16fce1..5ae67e6 100644 --- a/docs/salida-y-codigos.md +++ b/docs/salida-y-codigos.md @@ -25,7 +25,7 @@ Con `--json`, **stdout trae solo JSON** y todo lo demás va a stderr: | Comando | stdout con `--json` | |---|---| | `webhooks …`, `events list`, `events resend`, `trigger` | El `data` de la respuesta de la API, sin cambios. | -| `events retrieve` | El evento tal como se entregó (igual que sin `--json`). | +| `events retrieve` | El evento como lo devuelve la API (igual que sin `--json`). No es el cuerpo compacto que se entregó, así que no sirve para verificar una firma. | | `listen` | Un objeto JSON por entrega, uno por línea (JSON Lines). Ver [listen](listen.md#salida-con---json). | | `listen --print-secret` | `{"secret":"whsec_…"}` | | `login`, `logout` | Nada: sus mensajes van a stderr. | diff --git a/docs/solucion-de-problemas.md b/docs/solucion-de-problemas.md index 889135f..0f6793f 100644 --- a/docs/solucion-de-problemas.md +++ b/docs/solucion-de-problemas.md @@ -22,6 +22,11 @@ pruebas no sirven con `--live` y al revés). ### 401 `Missing required http X-API-KEY.` +**Causa:** la petición llegó sin el header `X-API-KEY`. +**Remedio:** el mismo de arriba. + +### 401 `Invalid API KEY` + **Causa:** la API key no es válida para ese ambiente (revocada, mal copiada o de otro ambiente). **Remedio:** el mismo de arriba. `fiscalapi login` valida las llaves antes de guardarlas: `Error: Las credenciales no son válidas para test.fiscalapi.com.` diff --git a/docs/trigger.md b/docs/trigger.md index d2c6801..7afb8c3 100644 --- a/docs/trigger.md +++ b/docs/trigger.md @@ -63,11 +63,14 @@ fiscalapi trigger download_request.completed \ --person-id 2e7d4c1b-9a8f-4e6d-b5c4-3a2b1c0d9e8f ``` -Con `--json`, imprime el `data` de la respuesta sin cambios: +Con `--json`, imprime el `data` de la respuesta sin cambios, con el formato indentado de la API: ```text $ fiscalapi trigger invoice.canceled --json -{"eventId":"3f9c1d2e-7b4a-4e8f-9a1b-2c3d4e5f6a7b","webhookId":"9b2e7c4a-1d3f-4e6b-8a5c-0f1e2d3c4b5a"} +{ + "eventId": "3f9c1d2e-7b4a-4e8f-9a1b-2c3d4e5f6a7b", + "webhookId": "9b2e7c4a-1d3f-4e6b-8a5c-0f1e2d3c4b5a" + } ``` ## Cómo se entrega @@ -93,6 +96,20 @@ Error: Sorry, it's not me, it's you. traceIdentifier (para soporte): 8F3A2C1D9B7E4F60A5C3D2E1F0B9A877 ``` +Un 400 de validación pone el texto general en `Detalle:` y una línea `- ` por cada regla que falló. Un tipo de +evento que no existe sale así: + +```text +$ fiscalapi trigger invoice.cancelled +Error: Sorry, it's not me, it's you. + Detalle: One or more validation failures have occurred. + - El tipo de evento 'invoice.cancelled' no existe. + Código HTTP: 400 + traceIdentifier (para soporte): … +``` + +Los demás 400 de la tabla traen su texto directo en `Detalle:`. + | Código | Texto | Qué hacer | |---|---|---| | 409 | `La escucha de CLI no está conectada; ejecuta fiscalapi listen.` | Abre `fiscalapi listen` o usa `--webhook`. | diff --git a/docs/webhooks-y-eventos.md b/docs/webhooks-y-eventos.md index 3e584c6..27e5447 100644 --- a/docs/webhooks-y-eventos.md +++ b/docs/webhooks-y-eventos.md @@ -51,10 +51,11 @@ Descripción Producción Eventos invoice.canceled, invoice.cancellation_requested Personas 2e7d4c1b-9a8f-4e6d-b5c4-3a2b1c0d9e8f, 7c3b2a1d-0e9f-4d8c-a7b6-5f4e3d2c1b0a Creado 2026-10-13T09:30:00.000 +Actualizado 2026-10-13T09:30:00.000 ``` Solo aparecen los campos con valor. Según el caso también verás `Motivo` y `Deshabilitado` (webhook deshabilitado), -`Fallando desde`, `Persona de la escucha` y `Sesión vence` (escucha de CLI) y `Actualizado`. +`Fallando desde`, `Persona de la escucha` y `Sesión vence` (escucha de CLI). ### Crear un webhook @@ -68,13 +69,14 @@ Solo aparecen los campos con valor. Según el caso también verás `Motivo` y `D ```text $ fiscalapi webhooks create --url https://example.com/webhooks --events '*' -ID 6f1c2a4e-0b7d-4c55-9a3e-1d2f3a4b5c6d -Tipo url -Estado enabled -URL https://example.com/webhooks -Eventos * -Personas todas -Creado 2026-10-13T09:30:00.000 +ID 6f1c2a4e-0b7d-4c55-9a3e-1d2f3a4b5c6d +Tipo url +Estado enabled +URL https://example.com/webhooks +Eventos * +Personas todas +Creado 2026-10-13T09:30:00.000 +Actualizado 2026-10-13T09:30:00.000 Secreto de firma: whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw Guarda este secreto de firma. Lo usarás para verificar que los eventos vienen de FiscalAPI. @@ -216,12 +218,27 @@ Error: --from debe ser una fecha ISO 8601 (p. ej. 2026-10-01 o 2026-10-01T08:00: ### Ver un evento -`events retrieve` imprime el evento exactamente como lo entrega la API, con o sin `--json`. Su `id` es el del header -`webhook-id` de sus entregas. +`events retrieve` imprime el evento como lo devuelve la API, con o sin `--json`. Su `id` es el del header +`webhook-id` de sus entregas. La API lo devuelve indentado y el cuerpo que recibe tu endpoint va compacto, así que esta +salida no sirve para verificar una firma: verifica siempre con el cuerpo crudo que recibió tu endpoint. ```text $ fiscalapi events retrieve 0d6f5c1e-8a2b-4c3d-9e8f-7a6b5c4d3e2f -{"id":"0d6f5c1e-8a2b-4c3d-9e8f-7a6b5c4d3e2f","type":"invoice.canceled","createdAt":"2026-10-12T15:47:46Z","personId":"2e7d4c1b-9a8f-4e6d-b5c4-3a2b1c0d9e8f","data":{"relatedObject":{"id":"c4d3e2f1-a0b9-4c8d-9e7f-6a5b4c3d2e1f","type":"invoice","url":"/api/v4/invoices/c4d3e2f1-a0b9-4c8d-9e7f-6a5b4c3d2e1f"},"status":"X","previousStatus":"C"}} +{ + "id": "0d6f5c1e-8a2b-4c3d-9e8f-7a6b5c4d3e2f", + "type": "invoice.canceled", + "createdAt": "2026-10-12T15:47:46Z", + "personId": "2e7d4c1b-9a8f-4e6d-b5c4-3a2b1c0d9e8f", + "data": { + "relatedObject": { + "id": "c4d3e2f1-a0b9-4c8d-9e7f-6a5b4c3d2e1f", + "type": "invoice", + "url": "/api/v4/invoices/c4d3e2f1-a0b9-4c8d-9e7f-6a5b4c3d2e1f" + }, + "status": "X", + "previousStatus": "C" + } + } ``` ### Reenviar un evento @@ -243,7 +260,7 @@ descartar los ids que ya procesó. ## `--json` -Con `--json`, cada comando imprime en stdout el `data` de la respuesta de la API, sin cambios: +Con `--json`, cada comando imprime en stdout el `data` de la respuesta de la API, sin cambios y con su formato indentado: ```bash # Los ids de los webhooks habilitados