fiscalisto 0.1.10 → 0.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,6 +5,6 @@
5
5
  * Written by hand; keep it short (an agent reads all of it) and true to the docs it links.
6
6
  */
7
7
  export declare const AGENT_SKILL_DESCRIPTION = "Agregar facturaci\u00F3n electr\u00F3nica mexicana (CFDI 4.0) a una app con la API y los SDKs de Fiscalisto: timbrar facturas, pagos (PPD), notas de cr\u00E9dito, n\u00F3mina y retenciones, cancelar, webhooks. Use it whenever the user wants to issue Mexican invoices (CFDI, SAT, timbrado, factura electr\u00F3nica) or integrate Fiscalisto.";
8
- export declare const AGENT_GUIDE = "# Facturar con Fiscalisto (CFDI 4.0)\n\nFiscalisto es una API REST que timbra comprobantes fiscales mexicanos (CFDI 4.0): revisa las reglas\ndel SAT antes de gastar un timbre, sella con el certificado del emisor y timbra con el PAC. Los\nnombres de la API est\u00E1n en ingl\u00E9s (`customer`, `items`, `unit_price`); la documentaci\u00F3n, los\nmensajes de error y los textos, en espa\u00F1ol (`Accept-Language: en` los da en ingl\u00E9s).\n\n- Base: `https://api.fiscalisto.com/v1`, JSON, `Authorization: Bearer <llave>`.\n- Llaves: `fk_test_\u2026` timbra en el ambiente de pruebas del SAT, gratis; `fk_live_\u2026` timbra CFDI\n reales y usa un timbre cada uno. Se crean en **Desarrolladores \u203A Llaves**.\n- Documentaci\u00F3n para agentes: https://fiscalisto.com/docs/api/llms.txt (\u00EDndice; cada p\u00E1gina tambi\u00E9n en `.md`), la\n referencia OpenAPI 3.1 en https://api.fiscalisto.com/v1/openapi.json y el servidor MCP\n https://fiscalisto.com/docs/api/mcp (sin llave) con search_docs, describe_operation, describe_object, explain_error y\n call_api.\n\n## Antes de escribir c\u00F3digo\n\n1. **La llave.** P\u00EDdasela a la persona y gu\u00E1rdela en `FISCALISTO_API_KEY` (en `.env`, nunca en el\n repositorio). Si no tiene: `npx fiscalisto login` abre el navegador y guarda su llave de\n pruebas; `npx fiscalisto init` instala el SDK y deja la llave en `.env`. Nunca invente una.\n2. **Sin llave todav\u00EDa:** `npx fiscalisto mock` levanta la API en http://127.0.0.1:12111, sin\n internet (`new Fiscalisto(\"fk_test_mock\", { baseUrl: \"http://127.0.0.1:12111\" })`). Contesta\n como la API pero no revisa reglas del SAT: pruebe despu\u00E9s con una `fk_test_`.\n3. **El SDK de su lenguaje** (los seis tienen cada ruta, tipos e Idempotency-Key autom\u00E1tica):\n\n| Lenguaje | Instalar | Cliente |\n| --- | --- | --- |\n| TypeScript / JavaScript | `npm install fiscalisto` | `new Fiscalisto()` |\n| Python | `pip install fiscalisto` | `Fiscalisto()` |\n| PHP | `composer require fiscalisto/fiscalisto` | `new Fiscalisto\\Fiscalisto()` |\n| Go | `go get fiscalisto.com/go` | `fiscalisto.NewClient(\"\")` |\n| Java | Maven `com.fiscalisto:fiscalisto` | `new FiscalistoClient()` |\n| C# / .NET | `dotnet add package Fiscalisto` | `new FiscalistoClient()` |\n\nSin argumento, cada cliente lee `FISCALISTO_API_KEY`. El c\u00F3digo de cada operaci\u00F3n en cada lenguaje:\n`describe_operation` del MCP (con `language`) o la p\u00E1gina `.md` de la referencia.\n\n## Timbrar una factura\n\n```ts\nimport { Fiscalisto } from \"fiscalisto\";\n\nconst fiscalisto = new Fiscalisto(); // FISCALISTO_API_KEY\n\nconst invoice = await fiscalisto.invoices.create(\n {\n customer: { tax_id: \"ICV060329BY0\", legal_name: \"INMOBILIARIA CVA\", tax_system: \"601\", zip: \"33826\" },\n payment_form: \"03\", // transferencia\n items: [{ description: \"Mensualidad\", product_key: \"86121700\", quantity: 2, unit_price: 2500 }],\n },\n { idempotencyKey: `pedido-${order.id}` },\n);\n// Guarde invoice.id (inv_\u2026) y invoice.uuid (el folio fiscal) con su pedido.\n```\n\n- **Idempotency-Key = el id de su pedido.** Si la respuesta se pierde, repetir con la misma nunca\n timbra dos veces. No use una al azar en cada intento.\n- **El cliente (Receptor) va exactamente como en su constancia de situaci\u00F3n fiscal:** RFC\n (`tax_id`), nombre sin r\u00E9gimen de capital (sin \u00ABS.A. de C.V.\u00BB), r\u00E9gimen (`tax_system`, c_RegimenFiscal)\n y c\u00F3digo postal (`zip`). Si su app no tiene esos datos, p\u00EDdalos con una liga\n (`POST /v1/customer_data_requests`) o rev\u00EDselos con `POST /v1/tax_ids/validate`; guarde clientes\n frecuentes con `/v1/customers` y mande su `cus_\u2026`.\n- Lo que omite toma el valor usual: PUE, MXN, uso G03 (S01 con r\u00E9gimen 616), objeto de impuesto 02,\n IVA 16 %, cantidad 1, unidad E48. `unit_price` es sin IVA, en pesos.\n- **Claves del SAT:** no las invente. B\u00FAsquelas en los cat\u00E1logos (`/v1/sat_catalogs/{name}`, por ejemplo\n `product_keys`) o guarde productos (`/v1/products`, `prd_\u2026`) con su clave.\n- **La respuesta** trae `status: \"valid\"` con UUID, PDF y XML. Si el PAC tarda llega\n `processing`: no repita con otra llave de idempotencia; espere el webhook `invoice.stamped`\n (o `invoice.failed`).\n- **PDF y XML:** `invoices.pdf(id)`, `invoices.xml(id)`; `invoices.send(id)` lo manda por correo.\n- **A cr\u00E9dito (PPD):** `payment_method: \"PPD\"`, `payment_form: \"99\"`; cada cobro lleva su\n complemento de pago (`POST /v1/payments`) a m\u00E1s tardar el d\u00EDa 5 del mes siguiente.\n- Otros comprobantes: notas de cr\u00E9dito (`/v1/credit_notes`), anticipos (`/v1/advances`), n\u00F3mina\n (`/v1/payroll_receipts`), retenciones (`/v1/retentions`), lotes de hasta 1,000\n (`/v1/invoice_batches`), factura global y autofactura por ticket (`/v1/tickets`).\n\n## Errores\n\nCada error trae `error.type`, `error.code`, `error.message` (en espa\u00F1ol) y `error.param` (el\ncampo a corregir). Un rechazo del SAT llega como `invoice_rejected` con su regla en\n`error.sat_code` (CFDI40\u2026): muestre el mensaje a la persona y corrija el dato; no reintente igual.\nEl SDK solo reintenta lo que es seguro repetir. `explain_error` del MCP dice qu\u00E9 hacer con cada\nc\u00F3digo; la lista completa est\u00E1 en https://fiscalisto.com/docs/api/errores.md.\n\n## Webhooks\n\nLo que pasa despu\u00E9s (timbrado tard\u00EDo, cancelaci\u00F3n aceptada d\u00EDas despu\u00E9s, lotes) llega a su endpoint\ncomo evento firmado. Cr\u00E9elo en **Desarrolladores \u203A Webhooks** o con `POST /v1/webhook_endpoints`\ny guarde su secreto `whsec_\u2026` en `FISCALISTO_WEBHOOK_SECRET`.\n\n```ts\nimport { FiscalistoWebhookError, verifyWebhook } from \"fiscalisto\";\n\nexport async function POST(request: Request) {\n try {\n // El cuerpo tal como lleg\u00F3 (texto), sin interpretarlo antes.\n const event = await verifyWebhook(await request.text(), request.headers, process.env.FISCALISTO_WEBHOOK_SECRET!);\n if (event.type === \"invoice.stamped\") await marcarFacturado(event.data.object);\n return new Response(null, { status: 200 });\n } catch (error) {\n if (error instanceof FiscalistoWebhookError) return new Response(null, { status: 400 });\n throw error;\n }\n}\n```\n\nConteste 2xx r\u00E1pido y procese aparte; un evento puede llegar m\u00E1s de una vez: ignore el `evt_\u2026` que\nya proces\u00F3. En desarrollo, `npx fiscalisto listen --forward-to http://localhost:3000/webhooks` le\nreenv\u00EDa los eventos de pruebas y `npx fiscalisto trigger invoice.stamped` provoca uno.\n\n## Cancelar\n\n`invoices.cancel(id, { motive: \"02\" })`: 02 con errores y sin sustituir (el usual), 01 con errores y sustituida\n(`substitution: \"inv_\u2026\"`, o `invoices.substitute` timbra la nueva y cancela la anterior), 03 no\nse llev\u00F3 a cabo y 04 solo en una factura global (una venta se factur\u00F3 despu\u00E9s a nombre del\ncliente). Si el cliente debe aceptar llega\n`invoice.cancellation_pending` y despu\u00E9s `invoice.canceled` o `invoice.cancellation_rejected`.\n\n## Probar\n\n- Las llaves `fk_test_` aplican las mismas revisiones del SAT que producci\u00F3n; una cuenta nueva ya\n tiene un emisor de pruebas listo.\n- RFC de prueba que provocan cada rechazo del SAT (por ejemplo `NOM010101FK9` \u2192 `CFDI40145`):\n https://fiscalisto.com/docs/api/pruebas-y-produccion.md#provocar-cada-rechazo-del-sat.\n- `call_api` del MCP prueba un cuerpo real con la llave de pruebas antes de escribirlo en c\u00F3digo.\n- Pruebas autom\u00E1ticas: `POST /v1/test_data/reset` deja el modo de pruebas como nuevo.\n\n## Nunca\n\n- Poner la llave en el navegador o en una app m\u00F3vil: la API rechaza el navegador\n (`browser_not_supported`). Llame desde su servidor.\n- Usar una `fk_live_` para probar: timbra CFDI reales con valor fiscal.\n- Inventar folios, UUID, RFC, reg\u00EDmenes o claves del SAT: cons\u00FAltelos.\n\n## Pasar a producci\u00F3n\n\nEmisor real (`POST /v1/issuers`), su CSD (`/certificates`), la firma con e.firma del contrato\ncon el PAC (`/efirma`) o, m\u00E1s f\u00E1cil, una liga para que el due\u00F1o lo haga\n(`POST /v1/issuers/{id}/onboarding_links`); timbres en **Desarrolladores \u203A Timbres**; y la llave\n`fk_live_` en el servidor. Detalle: https://fiscalisto.com/docs/api/pruebas-y-produccion.md#pasar-a-produccion.\n";
8
+ export declare const AGENT_GUIDE = "# Facturar con Fiscalisto (CFDI 4.0)\n\nFiscalisto es una API REST que timbra comprobantes fiscales mexicanos (CFDI 4.0): revisa las reglas\ndel SAT antes de gastar un timbre, sella con el certificado del emisor y timbra con el PAC. Los\nnombres de la API est\u00E1n en ingl\u00E9s (`customer`, `items`, `unit_price`); la documentaci\u00F3n, los\nmensajes de error y los textos, en espa\u00F1ol (`Accept-Language: en` los da en ingl\u00E9s).\n\n- Base: `https://api.fiscalisto.com/v1`, JSON, `Authorization: Bearer <llave>`.\n- Llaves: `fk_test_\u2026` timbra en el ambiente de pruebas del SAT, gratis; `fk_live_\u2026` timbra CFDI\n reales y usa un timbre cada uno. Se crean en **Desarrolladores \u203A Llaves**.\n- Documentaci\u00F3n para agentes: https://fiscalisto.com/docs/api/llms.txt (\u00EDndice; cada p\u00E1gina tambi\u00E9n en `.md`), la\n referencia OpenAPI 3.1 en https://api.fiscalisto.com/v1/openapi.json y el servidor MCP\n https://fiscalisto.com/docs/api/mcp (sin llave) con search_docs, describe_operation, describe_object, explain_error y\n call_api.\n\n## Antes de escribir c\u00F3digo\n\n1. **La llave.** P\u00EDdasela a la persona y gu\u00E1rdela en `FISCALISTO_API_KEY` (en `.env`, nunca en el\n repositorio). Si no tiene: `npx fiscalisto login` abre el navegador y guarda su llave de\n pruebas; `npx fiscalisto init` instala el SDK y deja la llave en `.env`. Nunca invente una.\n2. **Sin llave todav\u00EDa:** `npx fiscalisto mock` levanta la API en http://127.0.0.1:12111, sin\n internet (`new Fiscalisto(\"fk_test_mock\", { baseUrl: \"http://127.0.0.1:12111\" })`). Contesta\n como la API pero no revisa reglas del SAT: pruebe despu\u00E9s con una `fk_test_`.\n3. **El SDK de su lenguaje** (los seis tienen cada ruta, tipos e Idempotency-Key autom\u00E1tica):\n\n| Lenguaje | Instalar | Cliente |\n| --- | --- | --- |\n| TypeScript / JavaScript | `npm install fiscalisto` | `new Fiscalisto()` |\n| Python | `pip install fiscalisto` | `Fiscalisto()` |\n| PHP | `composer require fiscalisto/fiscalisto` | `new Fiscalisto\\Fiscalisto()` |\n| Go | `go get fiscalisto.com/go` | `fiscalisto.NewClient(\"\")` |\n| Java | Maven `com.fiscalisto:fiscalisto` | `new FiscalistoClient()` |\n| C# / .NET | `dotnet add package Fiscalisto` | `new FiscalistoClient()` |\n\nSin argumento, cada cliente lee `FISCALISTO_API_KEY`. El c\u00F3digo de cada operaci\u00F3n en cada lenguaje:\n`describe_operation` del MCP (con `language`) o la p\u00E1gina `.md` de la referencia.\n\n## Timbrar una factura\n\n```ts\nimport { Fiscalisto } from \"fiscalisto\";\n\nconst fiscalisto = new Fiscalisto(); // FISCALISTO_API_KEY\n\nconst invoice = await fiscalisto.invoices.create(\n {\n customer: { tax_id: \"ICV060329BY0\", legal_name: \"INMOBILIARIA CVA\", tax_system: \"601\", zip: \"33826\" },\n payment_form: \"03\", // transferencia\n items: [{ description: \"Mensualidad\", product_key: \"86121700\", quantity: 2, unit_price: 2500 }],\n },\n { idempotencyKey: `pedido-${order.id}` },\n);\n// Guarde invoice.id (inv_\u2026) y invoice.uuid (el folio fiscal) con su pedido.\n```\n\n- **Idempotency-Key = el id de su pedido.** Si la respuesta se pierde, repetir con la misma nunca\n timbra dos veces. No use una al azar en cada intento.\n- **El cliente (Receptor) va exactamente como en su constancia de situaci\u00F3n fiscal:** RFC\n (`tax_id`), nombre sin r\u00E9gimen de capital (sin \u00ABS.A. de C.V.\u00BB), r\u00E9gimen (`tax_system`, c_RegimenFiscal)\n y c\u00F3digo postal (`zip`). Si su app no tiene esos datos, p\u00EDdalos con una liga\n (`POST /v1/customer_data_requests`) o rev\u00EDselos con `POST /v1/tax_ids/validate`; guarde clientes\n frecuentes con `/v1/customers` y mande su `cus_\u2026`.\n- Lo que omite toma el valor usual: PUE, MXN, uso G03 (S01 con r\u00E9gimen 616), objeto de impuesto 02,\n IVA 16 %, cantidad 1, unidad E48. `unit_price` es sin IVA, en pesos.\n- **Claves del SAT:** no las invente. B\u00FAsquelas en los cat\u00E1logos (`/v1/sat_catalogs/{name}`, por ejemplo\n `product_keys`) o guarde productos (`/v1/products`, `prd_\u2026`) con su clave.\n- **La respuesta** trae `status: \"valid\"` con UUID, PDF y XML. Si el PAC tarda llega\n `processing`: no repita con otra llave de idempotencia; espere el webhook `invoice.stamped`\n (o `invoice.failed`).\n- **PDF y XML:** `invoices.pdf(id)`, `invoices.xml(id)`; `invoices.send(id)` lo manda por correo.\n- **A cr\u00E9dito (PPD):** `payment_method: \"PPD\"`, `payment_form: \"99\"`; cada cobro lleva su\n complemento de pago (`POST /v1/payments`) a m\u00E1s tardar el d\u00EDa 5 del mes siguiente.\n- Otros comprobantes: notas de cr\u00E9dito (`/v1/credit_notes`), anticipos (`/v1/advances`), n\u00F3mina\n (`/v1/payroll_receipts`), retenciones (`/v1/retentions`), lotes de hasta 1,000\n (`/v1/invoice_batches`), factura global y autofactura por ticket (`/v1/tickets`).\n\n## Errores\n\nCada error trae `error.type`, `error.code`, `error.message` (en espa\u00F1ol) y `error.param` (el\ncampo a corregir). Un rechazo del SAT llega como `invoice_rejected` con su regla en\n`error.sat_code` (CFDI40\u2026): muestre el mensaje a la persona y corrija el dato; no reintente igual.\nEl SDK solo reintenta lo que es seguro repetir. `explain_error` del MCP dice qu\u00E9 hacer con cada\nc\u00F3digo; la lista completa est\u00E1 en https://fiscalisto.com/docs/api/errores.md.\n\n## Webhooks\n\nLo que pasa despu\u00E9s (timbrado tard\u00EDo, cancelaci\u00F3n aceptada d\u00EDas despu\u00E9s, lotes) llega a su endpoint\ncomo evento firmado. Cr\u00E9elo en **Desarrolladores \u203A Webhooks** o con `POST /v1/webhook_endpoints`\ny guarde su secreto `whsec_\u2026` en `FISCALISTO_WEBHOOK_SECRET`.\n\n```ts\nimport { FiscalistoWebhookError, verifyWebhook } from \"fiscalisto\";\n\nexport async function POST(request: Request) {\n try {\n // El cuerpo tal como lleg\u00F3 (texto), sin interpretarlo antes.\n const event = await verifyWebhook(await request.text(), request.headers, process.env.FISCALISTO_WEBHOOK_SECRET!);\n if (event.type === \"invoice.stamped\") await marcarFacturado(event.data.object);\n return new Response(null, { status: 200 });\n } catch (error) {\n if (error instanceof FiscalistoWebhookError) return new Response(null, { status: 400 });\n throw error;\n }\n}\n```\n\nConteste 2xx r\u00E1pido y procese aparte; un evento puede llegar m\u00E1s de una vez: ignore el `evt_\u2026` que\nya proces\u00F3. En desarrollo, `npx fiscalisto listen --forward-to http://localhost:3000/webhooks` le\nreenv\u00EDa los eventos de pruebas y `npx fiscalisto trigger invoice.stamped` provoca uno.\n\n## Cancelar\n\n`invoices.cancel(id, { motive: \"02\" })`: 02 con errores y sin sustituir (el usual), 01 con errores y sustituida\n(`substitution: \"inv_\u2026\"`, o `invoices.substitute` timbra la nueva y cancela la anterior), 03 no\nse llev\u00F3 a cabo y 04 solo en una factura global (una venta se factur\u00F3 despu\u00E9s a nombre del\ncliente). Si el cliente debe aceptar llega\n`invoice.cancellation_pending` y despu\u00E9s `invoice.canceled` o `invoice.cancellation_rejected`.\n\n## Probar\n\n- Las llaves `fk_test_` aplican las mismas revisiones del SAT que producci\u00F3n; una cuenta nueva ya\n tiene un emisor de pruebas listo.\n- En pruebas el cliente o empleado debe estar en la lista de RFC de prueba del PAC (si no,\n `CFDI40143`): use `ICV060329BY0` INMOBILIARIA CVA, r\u00E9gimen 601, CP 33826 (persona moral) o\n `MASO451221PM4` MARIA OLIVIA MARTINEZ SAGAZ, CP 80290 (persona f\u00EDsica y n\u00F3mina).\n- En pruebas los correos solo llegan a las personas de la cuenta API (a otro, `send_email` timbra\n igual y la respuesta trae `email_error`), y cada emisor timbra hasta 5 comprobantes cada 10\n segundos (`429` `stamp_rate_limit`: espere `Retry-After` y repita con la misma llave).\n- RFC de prueba que provocan cada rechazo del SAT (por ejemplo `NOM010101FK9` \u2192 `CFDI40145`):\n https://fiscalisto.com/docs/api/pruebas-y-produccion.md#provocar-cada-rechazo-del-sat.\n- `call_api` del MCP prueba un cuerpo real con la llave de pruebas antes de escribirlo en c\u00F3digo.\n- Pruebas autom\u00E1ticas: `POST /v1/test_data/reset` deja el modo de pruebas como nuevo.\n\n## Nunca\n\n- Poner la llave en el navegador o en una app m\u00F3vil: la API rechaza el navegador\n (`browser_not_supported`). Llame desde su servidor.\n- Usar una `fk_live_` para probar: timbra CFDI reales con valor fiscal.\n- Inventar folios, UUID, RFC, reg\u00EDmenes o claves del SAT: cons\u00FAltelos.\n\n## Pasar a producci\u00F3n\n\nEmisor real (`POST /v1/issuers`), su CSD (`/certificates`), la firma con e.firma del contrato\ncon el PAC (`/efirma`) o, m\u00E1s f\u00E1cil, una liga para que el due\u00F1o lo haga\n(`POST /v1/issuers/{id}/onboarding_links`); timbres en **Desarrolladores \u203A Timbres**; y la llave\n`fk_live_` en el servidor. Detalle: https://fiscalisto.com/docs/api/pruebas-y-produccion.md#pasar-a-produccion.\n";
9
9
  /** The guide as an Agent Skill (agentskills.io): SKILL.md with its name and description. */
10
10
  export declare const AGENT_SKILL: string;
@@ -128,6 +128,12 @@ cliente). Si el cliente debe aceptar llega
128
128
 
129
129
  - Las llaves \`fk_test_\` aplican las mismas revisiones del SAT que producción; una cuenta nueva ya
130
130
  tiene un emisor de pruebas listo.
131
+ - En pruebas el cliente o empleado debe estar en la lista de RFC de prueba del PAC (si no,
132
+ \`CFDI40143\`): use \`ICV060329BY0\` INMOBILIARIA CVA, régimen 601, CP 33826 (persona moral) o
133
+ \`MASO451221PM4\` MARIA OLIVIA MARTINEZ SAGAZ, CP 80290 (persona física y nómina).
134
+ - En pruebas los correos solo llegan a las personas de la cuenta API (a otro, \`send_email\` timbra
135
+ igual y la respuesta trae \`email_error\`), y cada emisor timbra hasta 5 comprobantes cada 10
136
+ segundos (\`429\` \`stamp_rate_limit\`: espere \`Retry-After\` y repita con la misma llave).
131
137
  - RFC de prueba que provocan cada rechazo del SAT (por ejemplo \`NOM010101FK9\` → \`CFDI40145\`):
132
138
  ${DOCS}/pruebas-y-produccion.md#provocar-cada-rechazo-del-sat.
133
139
  - \`call_api\` del MCP prueba un cuerpo real con la llave de pruebas antes de escribirlo en código.
package/dist/cli.js CHANGED
@@ -15,7 +15,7 @@ import { homedir, hostname } from "node:os";
15
15
  import { dirname, join, resolve } from "node:path";
16
16
  import { createInterface } from "node:readline/promises";
17
17
  import { parseArgs } from "node:util";
18
- import { AGENT_SKILL } from "./agent-guide.js";
18
+ import { AGENT_GUIDE, AGENT_SKILL } from "./agent-guide.js";
19
19
  import { FiscalistoError, VERSION } from "./core.js";
20
20
  import { Fiscalisto } from "./index.js";
21
21
  import { createMock } from "./mock.js";
@@ -959,6 +959,51 @@ async function satLists(args, g) {
959
959
  }
960
960
  });
961
961
  }
962
+ // ── payroll ────────────────────────────────────────────────────────────────
963
+ /**
964
+ * «fiscalisto payroll preview|create --data @recibo.json [--external]»: a recibo de nómina.
965
+ * Without --external Fiscalisto calculates it from the employee (emp_…) and the period; with it,
966
+ * the amounts your payroll system calculated are checked and stamped exactly as sent.
967
+ */
968
+ async function payroll(args, g) {
969
+ const [sub, ...rest] = args;
970
+ if (sub !== "preview" && sub !== "create")
971
+ throw new UsageError("Uso: fiscalisto payroll preview|create --data @recibo.json [--external] [--idempotency-key …]");
972
+ const { values } = parseArgs({
973
+ args: rest,
974
+ options: {
975
+ data: { type: "string", short: "d" },
976
+ external: { type: "boolean" },
977
+ "idempotency-key": { type: "string" },
978
+ },
979
+ });
980
+ const body = await readData(values.data);
981
+ if (!body)
982
+ throw new UsageError(values.external
983
+ ? "Pase --data con el recibo que calculó su sistema (JSON, @archivo o -): employee, perceptions, deductions, other_payments y totals."
984
+ : 'Pase --data (JSON, @archivo o -): {"employee": "emp_…", "period": {…}}.');
985
+ const path = `/v1/payroll_receipts${values.external ? "/external" : ""}`;
986
+ const api = await client(g);
987
+ if (sub === "preview") {
988
+ const preview = await api.request({ method: "POST", path: `${path}/preview`, body });
989
+ return print(preview, () => {
990
+ const t = preview.payroll?.totals ?? preview.totals;
991
+ line(`${bold("Recibo de nómina")} ${dim("(sin timbrar)")} neto ${preview.total.toFixed(2)}`);
992
+ if (t)
993
+ line(` percepciones ${t.perceptions.toFixed(2)} · otros pagos ${t.other_payments.toFixed(2)} · deducciones ${t.deductions.toFixed(2)}`);
994
+ for (const w of preview.warnings ?? [])
995
+ line(` ${yellow("!")} ${typeof w === "string" ? w : `${w.param ? `${w.param}: ` : ""}${w.message}`}`);
996
+ });
997
+ }
998
+ await confirmLive(api, g, "Timbrar");
999
+ const invoice = await api.request({ method: "POST", path, body, idempotent: true }, { idempotencyKey: values["idempotency-key"] });
1000
+ return print(invoice, () => {
1001
+ showInvoice(invoice);
1002
+ for (const w of invoice.warnings ?? [])
1003
+ line(` ${yellow("!")} ${w}`);
1004
+ line(dim(` PDF: fiscalisto invoices pdf ${invoice.id}`));
1005
+ });
1006
+ }
962
1007
  // ── api ────────────────────────────────────────────────────────────────────
963
1008
  async function rawApi(args, g) {
964
1009
  const { values, positionals } = parseArgs({
@@ -975,7 +1020,7 @@ async function rawApi(args, g) {
975
1020
  const api = await client(g);
976
1021
  const body = await readData(values.data);
977
1022
  const stamps = method === "POST" &&
978
- /^\/v1\/(invoices|payments|credit_notes|advances|retentions|payroll_receipts|invoice_batches)(\/[^/]+\/substitute)?$/.test(path.split("?")[0] ?? "");
1023
+ /^\/v1\/(invoices|payments|credit_notes|advances|retentions|payroll_receipts(\/external)?|invoice_batches)(\/[^/]+\/substitute)?$/.test(path.split("?")[0] ?? "");
979
1024
  if (stamps)
980
1025
  await confirmLive(api, g, "Timbrar");
981
1026
  const [p, q] = path.split("?");
@@ -1212,12 +1257,10 @@ function openPlace(args) {
1212
1257
  openBrowser(url);
1213
1258
  print({ url }, () => line(url));
1214
1259
  }
1260
+ /** The integration guide (the docs MCP's get_started), from the package: no network needed. */
1215
1261
  async function docs() {
1216
- const url = `${APP_URL()}/docs/api/llms.txt`;
1217
- const r = await fetch(url);
1218
- if (!r.ok)
1219
- throw new Error(`No se pudo leer la documentación (${r.status}).`);
1220
- const text = await r.text();
1262
+ const url = `${APP_URL()}/docs/api/SKILL.md`;
1263
+ const text = `${AGENT_GUIDE}\nÍndice de toda la documentación: ${APP_URL()}/docs/api/llms.txt\n`;
1221
1264
  if (json)
1222
1265
  print({ url, text });
1223
1266
  else
@@ -1292,6 +1335,10 @@ ${bold("Facturas")}
1292
1335
  invoices cancel <inv_…> [--motive 02] [--substitution inv_…]
1293
1336
  sat-lists check RFC [RFC…] ¿Está en la lista 69-B del SAT?
1294
1337
 
1338
+ ${bold("Nómina")}
1339
+ payroll preview|create --data @recibo.json Fiscalisto calcula el recibo del empleado (emp_…)
1340
+ payroll preview|create --external --data @recibo.json Timbra tal cual los importes que calculó su sistema
1341
+
1295
1342
  ${bold("Webhooks")}
1296
1343
  listen [--forward-to URL] Reenvía los eventos a su computadora, firmados
1297
1344
  trigger <evento> Crea en pruebas lo que manda ese evento (invoice.stamped, invoice.failed…)
@@ -1304,7 +1351,7 @@ ${bold("Otros")}
1304
1351
  api [METHOD] /v1/… [--data] Cualquier ruta de la API con su llave
1305
1352
  mock [--port 12111] La API en su computadora, sin internet, para desarrollar y probar
1306
1353
  open [panel|facturas|llaves|webhooks|eventos|docs]
1307
- docs La guía completa para agentes (llms.txt)
1354
+ docs La guía de integración para agentes (la de get_started y SKILL.md)
1308
1355
 
1309
1356
  ${bold("Opciones")}
1310
1357
  --json Respuesta en JSON (para scripts y agentes)
@@ -1361,6 +1408,9 @@ export async function main(argv) {
1361
1408
  return await webhooks(args, globals);
1362
1409
  case "sat-lists":
1363
1410
  return await satLists(args, globals);
1411
+ case "payroll":
1412
+ case "nomina":
1413
+ return await payroll(args, globals);
1364
1414
  case "api":
1365
1415
  return await rawApi(args, globals);
1366
1416
  case "listen":
package/dist/core.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * llamar.
5
5
  */
6
6
  import type { ErrorCode } from "./error-codes.js";
7
- export declare const VERSION = "0.1.10";
7
+ export declare const VERSION = "0.1.12";
8
8
  /**
9
9
  * La versión de la API para la que se hizo este SDK: la manda en cada solicitud
10
10
  * (Fiscalisto-Version), así actualizar la API no cambia lo que recibe hasta que actualice el SDK.
package/dist/core.js CHANGED
@@ -3,7 +3,7 @@
3
3
  * errores y las listas que se recorren solas. Los recursos (generated.ts) solo dicen qué ruta
4
4
  * llamar.
5
5
  */
6
- export const VERSION = "0.1.10";
6
+ export const VERSION = "0.1.12";
7
7
  /**
8
8
  * La versión de la API para la que se hizo este SDK: la manda en cada solicitud
9
9
  * (Fiscalisto-Version), así actualizar la API no cambia lo que recibe hasta que actualice el SDK.
@@ -17,6 +17,8 @@ export declare const ErrorCode: {
17
17
  readonly BranchHasInvoices: "branch_has_invoices";
18
18
  /** La API se llama desde su servidor, nunca desde el navegador: la llave secreta quedaría expuesta. */
19
19
  readonly BrowserNotSupported: "browser_not_supported";
20
+ /** Mezcló las dos formas de emitir un recibo de nómina: POST /v1/payroll_receipts calcula el recibo con los datos del empleado (emp_…); POST /v1/payroll_receipts/external timbra los importes que calculó su sistema. Use el endpoint que corresponde. */
21
+ readonly CalculationModeAmbiguous: "calculation_mode_ambiguous";
20
22
  /** El SAT no aceptó la solicitud de cancelación; message dice por qué. */
21
23
  readonly CancellationFailed: "cancellation_failed";
22
24
  /** El catálogo del SAT no respondió (503). Reintente en unos segundos. */
@@ -39,7 +41,7 @@ export declare const ErrorCode: {
39
41
  readonly EfirmaInvalid: "efirma_invalid";
40
42
  /** Para pedirle al SAT las facturas de un emisor en producción, guarde antes su e.firma: POST /v1/issuers/{id}/efirma con keep_for_downloads: true. También si la guardada venció. */
41
43
  readonly EfirmaRequired: "efirma_required";
42
- /** No se pudo mandar el correo; el comprobante sí está timbrado. */
44
+ /** No se pudo mandar el correo; lo demás sí se hizo: el comprobante está timbrado o la cotización quedó enviada (su url funciona). Repita el envío con su ruta /send. */
43
45
  readonly EmailFailed: "email_failed";
44
46
  /** Ya hay un webhook con esa dirección en este modo; el mensaje dice cuál. Cámbielo en vez de crear otro. */
45
47
  readonly EndpointExists: "endpoint_exists";
@@ -103,8 +105,18 @@ export declare const ErrorCode: {
103
105
  readonly ParameterMissing: "parameter_missing";
104
106
  /** Mandó un campo o un parámetro de la URL que no existe (casi siempre un nombre mal escrito, como legalName en vez de legal_name, o ?statuss= en vez de ?status=). Nunca se ignora en silencio. */
105
107
  readonly ParameterUnknown: "parameter_unknown";
106
- /** El recibo de nómina no se puede calcular o timbrar con esos datos (periodo, días, registro patronal del emisor…). */
108
+ /** Mandó el confirmation_token de una vista previa, pero el recibo que se calcularía ahora es otro (se timbró otro recibo del empleado ese mes, cambió su salario o se actualizaron las tablas). No se timbró: pida la vista previa otra vez y mande su token nuevo. */
109
+ readonly PayrollCalculationChanged: "payroll_calculation_changed";
110
+ /** Fiscalisto calcula solo la nómina ordinaria (sueldo, ISR con el subsidio para el empleo y cuotas obreras del IMSS). Aguinaldo, PTU, finiquitos, liquidaciones, pensiones y demás los calcula su sistema de nómina: timbre esos importes con POST /v1/payroll_receipts/external. param dice qué campo lo pidió. */
111
+ readonly PayrollCalculationUnsupported: "payroll_calculation_unsupported";
112
+ /** El recibo de nómina no se puede calcular o timbrar con esos datos (periodo, días, registro patronal del emisor…). En un recibo calculado por su sistema (/v1/payroll_receipts/external), errors trae todos los problemas, cada uno con su param, code (missing, not_allowed, invalid, catalog, totals_mismatch, rule) y message. No se usó ningún timbre. */
107
113
  readonly PayrollInvalid: "payroll_invalid";
114
+ /** El empleado ya tiene un recibo ordinario cuyo periodo se cruza con este (invoice). Un pago adicional del periodo va como recibo extraordinario (type E); para corregir aquel, use replaces. */
115
+ readonly PayrollPeriodOverlap: "payroll_period_overlap";
116
+ /** El empleado ya tiene un recibo vigente de ese periodo (ordinario) o de esa corrida (payroll_run_id, extraordinario) con otros importes. invoice es ese recibo: corríjalo con replaces o cancélelo antes. Con los mismos importes se devuelve el mismo recibo, sin error. */
117
+ readonly PayrollReceiptExists: "payroll_receipt_exists";
118
+ /** replaces no es un recibo de nómina vigente del mismo emisor y del mismo empleado. */
119
+ readonly PayrollReplacementInvalid: "payroll_replacement_invalid";
108
120
  /** La cotización no tiene los datos fiscales del cliente: agrégueselos con POST /v1/quotes/{id} (customer) o mándela con auto_invoice para que los dé al aceptarla. */
109
121
  readonly QuoteCustomerMissing: "quote_customer_missing";
110
122
  /** La cotización no se pudo guardar o ya no cambia (aceptada, rechazada o facturada), o no se puede mandar así. El mensaje dice por qué. */
@@ -155,7 +167,7 @@ export declare const ErrorCode: {
155
167
  readonly StoreNotAuthorized: "store_not_authorized";
156
168
  /** Esa plataforma aún no está disponible en Fiscalisto. */
157
169
  readonly StorePlatformUnavailable: "store_platform_unavailable";
158
- /** Los complementos de pago y las notas de crédito no se sustituyen: se cancelan y se emite otro. */
170
+ /** Los complementos de pago y las notas de crédito no se sustituyen: se cancelan y se emite otro. Un recibo de nómina se sustituye con POST /v1/payroll_receipts/external y replaces. */
159
171
  readonly SubstitutionUnsupported: "substitution_unsupported";
160
172
  /** El reloj se está adelantando en otra solicitud (409, con Retry-After). Espere a test_clock.ready y repita. */
161
173
  readonly TestClockAdvancing: "test_clock_advancing";
@@ -18,6 +18,8 @@ export const ErrorCode = {
18
18
  BranchHasInvoices: "branch_has_invoices",
19
19
  /** La API se llama desde su servidor, nunca desde el navegador: la llave secreta quedaría expuesta. */
20
20
  BrowserNotSupported: "browser_not_supported",
21
+ /** Mezcló las dos formas de emitir un recibo de nómina: POST /v1/payroll_receipts calcula el recibo con los datos del empleado (emp_…); POST /v1/payroll_receipts/external timbra los importes que calculó su sistema. Use el endpoint que corresponde. */
22
+ CalculationModeAmbiguous: "calculation_mode_ambiguous",
21
23
  /** El SAT no aceptó la solicitud de cancelación; message dice por qué. */
22
24
  CancellationFailed: "cancellation_failed",
23
25
  /** El catálogo del SAT no respondió (503). Reintente en unos segundos. */
@@ -40,7 +42,7 @@ export const ErrorCode = {
40
42
  EfirmaInvalid: "efirma_invalid",
41
43
  /** Para pedirle al SAT las facturas de un emisor en producción, guarde antes su e.firma: POST /v1/issuers/{id}/efirma con keep_for_downloads: true. También si la guardada venció. */
42
44
  EfirmaRequired: "efirma_required",
43
- /** No se pudo mandar el correo; el comprobante sí está timbrado. */
45
+ /** No se pudo mandar el correo; lo demás sí se hizo: el comprobante está timbrado o la cotización quedó enviada (su url funciona). Repita el envío con su ruta /send. */
44
46
  EmailFailed: "email_failed",
45
47
  /** Ya hay un webhook con esa dirección en este modo; el mensaje dice cuál. Cámbielo en vez de crear otro. */
46
48
  EndpointExists: "endpoint_exists",
@@ -104,8 +106,18 @@ export const ErrorCode = {
104
106
  ParameterMissing: "parameter_missing",
105
107
  /** Mandó un campo o un parámetro de la URL que no existe (casi siempre un nombre mal escrito, como legalName en vez de legal_name, o ?statuss= en vez de ?status=). Nunca se ignora en silencio. */
106
108
  ParameterUnknown: "parameter_unknown",
107
- /** El recibo de nómina no se puede calcular o timbrar con esos datos (periodo, días, registro patronal del emisor…). */
109
+ /** Mandó el confirmation_token de una vista previa, pero el recibo que se calcularía ahora es otro (se timbró otro recibo del empleado ese mes, cambió su salario o se actualizaron las tablas). No se timbró: pida la vista previa otra vez y mande su token nuevo. */
110
+ PayrollCalculationChanged: "payroll_calculation_changed",
111
+ /** Fiscalisto calcula solo la nómina ordinaria (sueldo, ISR con el subsidio para el empleo y cuotas obreras del IMSS). Aguinaldo, PTU, finiquitos, liquidaciones, pensiones y demás los calcula su sistema de nómina: timbre esos importes con POST /v1/payroll_receipts/external. param dice qué campo lo pidió. */
112
+ PayrollCalculationUnsupported: "payroll_calculation_unsupported",
113
+ /** El recibo de nómina no se puede calcular o timbrar con esos datos (periodo, días, registro patronal del emisor…). En un recibo calculado por su sistema (/v1/payroll_receipts/external), errors trae todos los problemas, cada uno con su param, code (missing, not_allowed, invalid, catalog, totals_mismatch, rule) y message. No se usó ningún timbre. */
108
114
  PayrollInvalid: "payroll_invalid",
115
+ /** El empleado ya tiene un recibo ordinario cuyo periodo se cruza con este (invoice). Un pago adicional del periodo va como recibo extraordinario (type E); para corregir aquel, use replaces. */
116
+ PayrollPeriodOverlap: "payroll_period_overlap",
117
+ /** El empleado ya tiene un recibo vigente de ese periodo (ordinario) o de esa corrida (payroll_run_id, extraordinario) con otros importes. invoice es ese recibo: corríjalo con replaces o cancélelo antes. Con los mismos importes se devuelve el mismo recibo, sin error. */
118
+ PayrollReceiptExists: "payroll_receipt_exists",
119
+ /** replaces no es un recibo de nómina vigente del mismo emisor y del mismo empleado. */
120
+ PayrollReplacementInvalid: "payroll_replacement_invalid",
109
121
  /** La cotización no tiene los datos fiscales del cliente: agrégueselos con POST /v1/quotes/{id} (customer) o mándela con auto_invoice para que los dé al aceptarla. */
110
122
  QuoteCustomerMissing: "quote_customer_missing",
111
123
  /** La cotización no se pudo guardar o ya no cambia (aceptada, rechazada o facturada), o no se puede mandar así. El mensaje dice por qué. */
@@ -156,7 +168,7 @@ export const ErrorCode = {
156
168
  StoreNotAuthorized: "store_not_authorized",
157
169
  /** Esa plataforma aún no está disponible en Fiscalisto. */
158
170
  StorePlatformUnavailable: "store_platform_unavailable",
159
- /** Los complementos de pago y las notas de crédito no se sustituyen: se cancelan y se emite otro. */
171
+ /** Los complementos de pago y las notas de crédito no se sustituyen: se cancelan y se emite otro. Un recibo de nómina se sustituye con POST /v1/payroll_receipts/external y replaces. */
160
172
  SubstitutionUnsupported: "substitution_unsupported",
161
173
  /** El reloj se está adelantando en otra solicitud (409, con Retry-After). Espere a test_clock.ready y repita. */
162
174
  TestClockAdvancing: "test_clock_advancing",