fiscalisto 0.1.11 → 0.1.13

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- 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";
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`; toda la n\u00F3mina en una solicitud con `/v1/payroll_batches`),\n retenciones (`/v1/retentions`), lotes de hasta 1,000 (`/v1/invoice_batches`), factura global\n 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;
@@ -79,8 +79,9 @@ const invoice = await fiscalisto.invoices.create(
79
79
  - **A crédito (PPD):** \`payment_method: "PPD"\`, \`payment_form: "99"\`; cada cobro lleva su
80
80
  complemento de pago (\`POST /v1/payments\`) a más tardar el día 5 del mes siguiente.
81
81
  - Otros comprobantes: notas de crédito (\`/v1/credit_notes\`), anticipos (\`/v1/advances\`), nómina
82
- (\`/v1/payroll_receipts\`), retenciones (\`/v1/retentions\`), lotes de hasta 1,000
83
- (\`/v1/invoice_batches\`), factura global y autofactura por ticket (\`/v1/tickets\`).
82
+ (\`/v1/payroll_receipts\`; toda la nómina en una solicitud con \`/v1/payroll_batches\`),
83
+ retenciones (\`/v1/retentions\`), lotes de hasta 1,000 (\`/v1/invoice_batches\`), factura global
84
+ y autofactura por ticket (\`/v1/tickets\`).
84
85
 
85
86
  ## Errores
86
87
 
package/dist/cli.js CHANGED
@@ -964,11 +964,14 @@ async function satLists(args, g) {
964
964
  * «fiscalisto payroll preview|create --data @recibo.json [--external]»: a recibo de nómina.
965
965
  * Without --external Fiscalisto calculates it from the employee (emp_…) and the period; with it,
966
966
  * the amounts your payroll system calculated are checked and stamped exactly as sent.
967
+ * «fiscalisto payroll batch --data @nomina.json»: a whole payroll run (POST /v1/payroll_batches).
967
968
  */
968
969
  async function payroll(args, g) {
969
970
  const [sub, ...rest] = args;
971
+ if (sub === "batch")
972
+ return payrollBatch(rest, g);
970
973
  if (sub !== "preview" && sub !== "create")
971
- throw new UsageError("Uso: fiscalisto payroll preview|create --data @recibo.json [--external] [--idempotency-key …]");
974
+ throw new UsageError("Uso: fiscalisto payroll preview|create --data @recibo.json [--external] [--idempotency-key …]\n fiscalisto payroll batch --data @nomina.json [--idempotency-key …]");
972
975
  const { values } = parseArgs({
973
976
  args: rest,
974
977
  options: {
@@ -1004,6 +1007,26 @@ async function payroll(args, g) {
1004
1007
  line(dim(` PDF: fiscalisto invoices pdf ${invoice.id}`));
1005
1008
  });
1006
1009
  }
1010
+ /** A whole payroll run in one request: stamped in the background, each employee's result. */
1011
+ async function payrollBatch(args, g) {
1012
+ const { values } = parseArgs({
1013
+ args,
1014
+ options: {
1015
+ data: { type: "string", short: "d" },
1016
+ "idempotency-key": { type: "string" },
1017
+ },
1018
+ });
1019
+ const body = await readData(values.data);
1020
+ if (!body)
1021
+ throw new UsageError('Pase --data con el lote (JSON, @archivo o -): {"period": {…}, "receipts": [{"employee": "emp_…"}, …]} o {"external_receipts": [{…}, …]}.');
1022
+ const api = await client(g);
1023
+ await confirmLive(api, g, "Timbrar");
1024
+ const batch = await api.request({ method: "POST", path: "/v1/payroll_batches", body, idempotent: true }, { idempotencyKey: values["idempotency-key"] });
1025
+ return print(batch, () => {
1026
+ line(`${green("✓")} ${bold(batch.id)}: ${batch.total} recibos, timbrándose en segundo plano.`);
1027
+ line(dim(` Resultado de cada empleado: fiscalisto api /v1/payroll_batches/${batch.id}`));
1028
+ });
1029
+ }
1007
1030
  // ── api ────────────────────────────────────────────────────────────────────
1008
1031
  async function rawApi(args, g) {
1009
1032
  const { values, positionals } = parseArgs({
@@ -1020,7 +1043,7 @@ async function rawApi(args, g) {
1020
1043
  const api = await client(g);
1021
1044
  const body = await readData(values.data);
1022
1045
  const stamps = method === "POST" &&
1023
- /^\/v1\/(invoices|payments|credit_notes|advances|retentions|payroll_receipts(\/external)?|invoice_batches)(\/[^/]+\/substitute)?$/.test(path.split("?")[0] ?? "");
1046
+ /^\/v1\/(invoices|payments|credit_notes|advances|retentions|payroll_receipts(\/external)?|invoice_batches|payroll_batches)(\/[^/]+\/substitute)?$/.test(path.split("?")[0] ?? "");
1024
1047
  if (stamps)
1025
1048
  await confirmLive(api, g, "Timbrar");
1026
1049
  const [p, q] = path.split("?");
@@ -1338,6 +1361,7 @@ ${bold("Facturas")}
1338
1361
  ${bold("Nómina")}
1339
1362
  payroll preview|create --data @recibo.json Fiscalisto calcula el recibo del empleado (emp_…)
1340
1363
  payroll preview|create --external --data @recibo.json Timbra tal cual los importes que calculó su sistema
1364
+ payroll batch --data @nomina.json Toda la nómina (hasta 1,000 recibos) en una solicitud
1341
1365
 
1342
1366
  ${bold("Webhooks")}
1343
1367
  listen [--forward-to URL] Reenvía los eventos a su computadora, firmados
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.11";
7
+ export declare const VERSION = "0.1.13";
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.11";
6
+ export const VERSION = "0.1.13";
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.
@@ -105,6 +105,10 @@ export declare const ErrorCode: {
105
105
  readonly ParameterMissing: "parameter_missing";
106
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. */
107
107
  readonly ParameterUnknown: "parameter_unknown";
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";
108
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. */
109
113
  readonly PayrollInvalid: "payroll_invalid";
110
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. */
@@ -151,7 +155,7 @@ export declare const ErrorCode: {
151
155
  readonly SatRequestRejected: "sat_request_rejected";
152
156
  /** El SAT no contestó o no dejó entrar con la e.firma del emisor. El mensaje trae lo que dijo; no se usó ningún timbre. Reintente en 10 minutos. */
153
157
  readonly SatUnavailable: "sat_unavailable";
154
- /** Demasiados timbres seguidos del mismo emisor. Espere lo que dice Retry-After; para muchas facturas use POST /v1/invoice_batches. */
158
+ /** Demasiados timbres seguidos del mismo emisor. Espere lo que dice Retry-After; para muchas facturas use POST /v1/invoice_batches, y para una nómina POST /v1/payroll_batches. */
155
159
  readonly StampRateLimit: "stamp_rate_limit";
156
160
  /** Esa tienda ya está conectada a este emisor. */
157
161
  readonly StoreAlreadyConnected: "store_already_connected";
@@ -106,6 +106,10 @@ export const ErrorCode = {
106
106
  ParameterMissing: "parameter_missing",
107
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. */
108
108
  ParameterUnknown: "parameter_unknown",
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",
109
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. */
110
114
  PayrollInvalid: "payroll_invalid",
111
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. */
@@ -152,7 +156,7 @@ export const ErrorCode = {
152
156
  SatRequestRejected: "sat_request_rejected",
153
157
  /** El SAT no contestó o no dejó entrar con la e.firma del emisor. El mensaje trae lo que dijo; no se usó ningún timbre. Reintente en 10 minutos. */
154
158
  SatUnavailable: "sat_unavailable",
155
- /** Demasiados timbres seguidos del mismo emisor. Espere lo que dice Retry-After; para muchas facturas use POST /v1/invoice_batches. */
159
+ /** Demasiados timbres seguidos del mismo emisor. Espere lo que dice Retry-After; para muchas facturas use POST /v1/invoice_batches, y para una nómina POST /v1/payroll_batches. */
156
160
  StampRateLimit: "stamp_rate_limit",
157
161
  /** Esa tienda ya está conectada a este emisor. */
158
162
  StoreAlreadyConnected: "store_already_connected",
@@ -794,6 +794,15 @@ export interface Employee {
794
794
  export interface PayrollReceiptPreview {
795
795
  /** Qué tipo de objeto es («invoice», «customer»…). */
796
796
  object: "payroll_receipt_preview";
797
+ /** Mándelo en POST /v1/payroll_receipts para timbrar exactamente este recibo: si al timbrar se calcula otro, contesta 409 payroll_calculation_changed sin timbrar. */
798
+ confirmation_token: string;
799
+ /** Lo que el recibo no incluye o pronto no se podrá calcular; no impide timbrar. */
800
+ warnings: {
801
+ /** finiquito_not_included: el empleado se fue en el periodo y el recibo no trae su finiquito; payroll_rates_pending: aún no se cargan los valores (ISR, subsidio, salario mínimo, UMA) de una fecha próxima. */
802
+ code: string;
803
+ /** Qué pasó y cómo corregirlo, para una persona. */
804
+ message: string;
805
+ }[];
797
806
  /** El empleado (emp_…). */
798
807
  employee: string;
799
808
  /** Periodicidad del pago (PeriodicidadPago): 02 semanal, 03 catorcenal, 04 quincenal (por omisión), 05 mensual. */
@@ -1032,6 +1041,63 @@ export interface InvoiceBatch {
1032
1041
  error: string | null;
1033
1042
  }[];
1034
1043
  }
1044
+ /** Una nómina completa (hasta 1,000 recibos) timbrada en segundo plano. */
1045
+ export interface PayrollBatch {
1046
+ /** Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). */
1047
+ id: string;
1048
+ /** true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. */
1049
+ livemode: boolean;
1050
+ /** Qué tipo de objeto es («invoice», «customer»…). */
1051
+ object: "payroll_batch";
1052
+ /** El emisor (iss_…). */
1053
+ issuer: string;
1054
+ /** Nombre del lote, para usted. */
1055
+ name: string;
1056
+ /** fiscalisto: Fiscalisto calculó cada recibo (receipts); external: se timbraron los importes de su sistema (external_receipts). */
1057
+ calculation: "fiscalisto" | "external";
1058
+ /** processing: timbrando. completed: ya no queda ningún recibo por timbrar. */
1059
+ status: "processing" | "completed";
1060
+ /** Cuántos recibos tiene el lote. */
1061
+ total: number;
1062
+ /** Cuántos recibos se timbraron. */
1063
+ stamped: number;
1064
+ /** Cuántos no se timbraron (cada uno con su error). */
1065
+ failed: number;
1066
+ /** Cuántos faltan por timbrar. */
1067
+ processing: number;
1068
+ /** Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00). */
1069
+ created_at: string | null;
1070
+ /** Cuándo terminó. */
1071
+ completed_at: string | null;
1072
+ /** El recibo de cada empleado, en el orden en que los mandó (no viene en listas). */
1073
+ receipts?: {
1074
+ /** Su posición en receipts (o external_receipts), desde 0. */
1075
+ index: number;
1076
+ /** Su identificador de esta factura (su número de pedido), hasta 100 caracteres. */
1077
+ reference: string | null;
1078
+ /** El empleado (emp_…), cuando Fiscalisto calculó el recibo. */
1079
+ employee: string | null;
1080
+ /** El RFC del empleado. */
1081
+ tax_id: string;
1082
+ /** Nombre. */
1083
+ name: string | null;
1084
+ /** Estado del objeto. */
1085
+ status: "processing" | "valid" | "failed";
1086
+ /** El recibo (inv_…, una factura tipo N); también el que el SAT rechazó. */
1087
+ invoice: string | null;
1088
+ /** Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas. */
1089
+ uuid: string | null;
1090
+ /** El neto del recibo timbrado. */
1091
+ total: number | null;
1092
+ /** Por qué no se timbró este recibo: su código y su mensaje. */
1093
+ error: {
1094
+ /** payroll_invalid, payroll_period_overlap, payroll_receipt_exists, invoice_rejected, invoice_invalid, insufficient_balance… */
1095
+ code: string;
1096
+ /** Qué pasó y cómo corregirlo, para una persona. */
1097
+ message: string;
1098
+ } | null;
1099
+ }[];
1100
+ }
1035
1101
  /** Una clave de un catálogo del SAT. */
1036
1102
  export interface SatCatalogEntry {
1037
1103
  /** La clave en el catálogo del SAT. */
@@ -2665,14 +2731,14 @@ export interface WebhookTest {
2665
2731
  };
2666
2732
  }
2667
2733
  /** Lo que puede pasar: el tipo de cada evento. */
2668
- export type EventType = "invoice.stamped" | "invoice.failed" | "invoice.canceled" | "invoice.cancellation_pending" | "invoice.cancellation_rejected" | "invoice.paid" | "invoice.partially_paid" | "retention.stamped" | "retention.failed" | "retention.canceled" | "invoice_batch.completed" | "customer_data_request.completed" | "sat_download.completed" | "sat_download.failed" | "sat_declaration.created" | "sat_declaration.updated" | "ticket.invoiced" | "ticket.included_in_global" | "recurring_invoice.failed" | "quote.viewed" | "quote.accepted" | "quote.changes_requested" | "quote.rejected" | "issuer.ready" | "balance.low" | "test_clock.ready";
2734
+ export type EventType = "invoice.stamped" | "invoice.failed" | "invoice.canceled" | "invoice.cancellation_pending" | "invoice.cancellation_rejected" | "invoice.paid" | "invoice.partially_paid" | "retention.stamped" | "retention.failed" | "retention.canceled" | "invoice_batch.completed" | "payroll_batch.completed" | "customer_data_request.completed" | "sat_download.completed" | "sat_download.failed" | "sat_declaration.created" | "sat_declaration.updated" | "ticket.invoiced" | "ticket.included_in_global" | "recurring_invoice.failed" | "quote.viewed" | "quote.accepted" | "quote.changes_requested" | "quote.rejected" | "issuer.ready" | "balance.low" | "test_clock.ready";
2669
2735
  /** Algo que pasó en su cuenta: el objeto completo como quedó. Se manda a sus webhooks firmado (Standard Webhooks). */
2670
2736
  export interface EventBase<T extends EventType = EventType, O = unknown> {
2671
2737
  /** Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). */
2672
2738
  id: string;
2673
2739
  /** Qué tipo de objeto es («invoice», «customer»…). */
2674
2740
  object: "event";
2675
- /** Qué pasó: invoice.stamped, invoice.failed, invoice.canceled, invoice.cancellation_pending, invoice.cancellation_rejected, invoice.paid, invoice.partially_paid, retention.stamped, retention.failed, retention.canceled, invoice_batch.completed, customer_data_request.completed, sat_download.completed, sat_download.failed, sat_declaration.created, sat_declaration.updated, ticket.invoiced, ticket.included_in_global, recurring_invoice.failed, quote.viewed, quote.accepted, quote.changes_requested, quote.rejected, issuer.ready, balance.low o test_clock.ready. */
2741
+ /** Qué pasó: invoice.stamped, invoice.failed, invoice.canceled, invoice.cancellation_pending, invoice.cancellation_rejected, invoice.paid, invoice.partially_paid, retention.stamped, retention.failed, retention.canceled, invoice_batch.completed, payroll_batch.completed, customer_data_request.completed, sat_download.completed, sat_download.failed, sat_declaration.created, sat_declaration.updated, ticket.invoiced, ticket.included_in_global, recurring_invoice.failed, quote.viewed, quote.accepted, quote.changes_requested, quote.rejected, issuer.ready, balance.low o test_clock.ready. */
2676
2742
  type: T;
2677
2743
  /** Versión de la API con que se armó el objeto. */
2678
2744
  api_version: string;
@@ -2686,7 +2752,7 @@ export interface EventBase<T extends EventType = EventType, O = unknown> {
2686
2752
  };
2687
2753
  }
2688
2754
  /** Un evento: según su type, data.object es la factura, la constancia o el lote. */
2689
- export type Event = EventBase<"invoice.stamped", Invoice> | EventBase<"invoice.failed", Invoice> | EventBase<"invoice.canceled", Invoice> | EventBase<"invoice.cancellation_pending", Invoice> | EventBase<"invoice.cancellation_rejected", Invoice> | EventBase<"invoice.paid", Invoice> | EventBase<"invoice.partially_paid", Invoice> | EventBase<"retention.stamped", Retention> | EventBase<"retention.failed", Retention> | EventBase<"retention.canceled", Retention> | EventBase<"invoice_batch.completed", InvoiceBatch> | EventBase<"customer_data_request.completed", CustomerDataRequest> | EventBase<"sat_download.completed", SatDownload> | EventBase<"sat_download.failed", SatDownload> | EventBase<"sat_declaration.created", SatDeclaration> | EventBase<"sat_declaration.updated", SatDeclaration> | EventBase<"ticket.invoiced", Ticket> | EventBase<"ticket.included_in_global", Ticket> | EventBase<"recurring_invoice.failed", RecurringInvoice> | EventBase<"quote.viewed", Quote> | EventBase<"quote.accepted", Quote> | EventBase<"quote.changes_requested", Quote> | EventBase<"quote.rejected", Quote> | EventBase<"issuer.ready", Issuer> | EventBase<"balance.low", Balance> | EventBase<"test_clock.ready", TestClock>;
2755
+ export type Event = EventBase<"invoice.stamped", Invoice> | EventBase<"invoice.failed", Invoice> | EventBase<"invoice.canceled", Invoice> | EventBase<"invoice.cancellation_pending", Invoice> | EventBase<"invoice.cancellation_rejected", Invoice> | EventBase<"invoice.paid", Invoice> | EventBase<"invoice.partially_paid", Invoice> | EventBase<"retention.stamped", Retention> | EventBase<"retention.failed", Retention> | EventBase<"retention.canceled", Retention> | EventBase<"invoice_batch.completed", InvoiceBatch> | EventBase<"payroll_batch.completed", PayrollBatch> | EventBase<"customer_data_request.completed", CustomerDataRequest> | EventBase<"sat_download.completed", SatDownload> | EventBase<"sat_download.failed", SatDownload> | EventBase<"sat_declaration.created", SatDeclaration> | EventBase<"sat_declaration.updated", SatDeclaration> | EventBase<"ticket.invoiced", Ticket> | EventBase<"ticket.included_in_global", Ticket> | EventBase<"recurring_invoice.failed", RecurringInvoice> | EventBase<"quote.viewed", Quote> | EventBase<"quote.accepted", Quote> | EventBase<"quote.changes_requested", Quote> | EventBase<"quote.rejected", Quote> | EventBase<"issuer.ready", Issuer> | EventBase<"balance.low", Balance> | EventBase<"test_clock.ready", TestClock>;
2690
2756
  /** Confirmación de que se borró. */
2691
2757
  export interface Deleted {
2692
2758
  /** Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). */
@@ -2798,6 +2864,16 @@ export interface EmployeeList {
2798
2864
  /** La ruta de esta lista. */
2799
2865
  url: string;
2800
2866
  }
2867
+ export interface PayrollBatchList {
2868
+ /** Qué tipo de objeto es («invoice», «customer»…). */
2869
+ object: "list";
2870
+ /** Los objetos de esta página. */
2871
+ data: PayrollBatch[];
2872
+ /** true si hay más: pida la siguiente con starting_after igual al id del último. */
2873
+ has_more: boolean;
2874
+ /** La ruta de esta lista. */
2875
+ url: string;
2876
+ }
2801
2877
  export interface InvoiceBatchList {
2802
2878
  /** Qué tipo de objeto es («invoice», «customer»…). */
2803
2879
  object: "list";
@@ -4076,7 +4152,7 @@ export interface UpdateAccountParams {
4076
4152
  api_version: string;
4077
4153
  }
4078
4154
  export interface ResetTestDataParams {
4079
- /** true (por omisión) para dejarle a cada emisor de pruebas 3 clientes y 3 productos de ejemplo. false para dejarlo vacío. */
4155
+ /** true (por omisión) para dejarle a cada emisor de pruebas 2 clientes y 3 productos de ejemplo. false para dejarlo vacío. */
4080
4156
  seed?: boolean;
4081
4157
  }
4082
4158
  export interface CreateSandboxParams {
@@ -4762,6 +4838,8 @@ export interface CreatePayrollReceiptParams {
4762
4838
  send_email?: boolean;
4763
4839
  /** Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks. */
4764
4840
  metadata?: Record<string, string>;
4841
+ /** El confirmation_token de POST /v1/payroll_receipts/preview: timbra solo si el recibo calculado ahora es exactamente el que revisó (si no, 409 payroll_calculation_changed y no timbra). Sin él, timbra el que calcule en ese momento. */
4842
+ confirmation_token?: string;
4765
4843
  }
4766
4844
  export interface PreviewPayrollReceiptParams {
4767
4845
  /** El empleado (emp_…). */
@@ -4782,6 +4860,57 @@ export interface PreviewPayrollReceiptParams {
4782
4860
  /** Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks. */
4783
4861
  metadata?: Record<string, string>;
4784
4862
  }
4863
+ export interface CreatePayrollBatchParams {
4864
+ /** Emisor (iss_…). Si la llave tiene un solo emisor o la cuenta tiene uno solo, puede omitirse. */
4865
+ issuer?: string;
4866
+ /** Nombre del lote, para usted (Quincena 20). */
4867
+ name?: string;
4868
+ /** El periodo de pago: primer y último día (FechaInicialPago, FechaFinalPago) y, si no es el último, el día de pago (FechaPago). Va para todos los recibos de receipts que no traen el suyo. */
4869
+ period?: {
4870
+ /** Primer día pagado (FechaInicialPago). */
4871
+ start: string;
4872
+ /** Último día pagado (FechaFinalPago). */
4873
+ end: string;
4874
+ /** Día de pago (FechaPago); sin él, el último día del periodo. */
4875
+ payment_date?: string;
4876
+ };
4877
+ /** Mandar a cada empleado su recibo por correo (a los que tienen correo). Solo con receipts. */
4878
+ send_email?: boolean;
4879
+ /** Los recibos que Fiscalisto calcula: un empleado (emp_…) en cada uno, como en POST /v1/payroll_receipts. */
4880
+ receipts?: {
4881
+ /** El empleado (emp_…) del emisor del lote. */
4882
+ employee: string;
4883
+ /** Su periodo de pago (FechaInicialPago, FechaFinalPago y FechaPago), si no es el del lote (period). */
4884
+ period?: {
4885
+ /** Primer día pagado (FechaInicialPago). */
4886
+ start: string;
4887
+ /** Último día pagado (FechaFinalPago). */
4888
+ end: string;
4889
+ /** Día de pago (FechaPago); sin él, el último día del periodo. */
4890
+ payment_date?: string;
4891
+ };
4892
+ /** Días pagados; sin él, todos los días que le tocan del periodo. */
4893
+ days?: number;
4894
+ /** Mandarle su recibo por correo; sin él, lo que diga send_email del lote. Con true el empleado debe tener correo. */
4895
+ send_email?: boolean;
4896
+ /** Su identificador de este recibo, hasta 100 caracteres. */
4897
+ reference?: string;
4898
+ }[];
4899
+ /** Los recibos que calculó su sistema de nómina, timbrados tal cual. En lugar de receipts. */
4900
+ external_receipts?: (ExternalPayrollReceiptCreate & {
4901
+ /** Su identificador de este recibo, hasta 100 caracteres. */
4902
+ reference?: string;
4903
+ })[];
4904
+ }
4905
+ /** Los parámetros de GET /v1/payroll_batches. */
4906
+ export interface ListPayrollBatchesParams {
4907
+ /** Cuántos por página, de 1 a 100. Por omisión 10. */
4908
+ limit?: number;
4909
+ /** El id del último de la página anterior, para la siguiente. */
4910
+ starting_after?: string;
4911
+ /** El emisor (iss_…). Puede omitirse si la llave o la cuenta tienen uno solo. */
4912
+ issuer?: string;
4913
+ }
4785
4914
  export interface CreateInvoiceBatchParams {
4786
4915
  /** Emisor (iss_…). Si la llave tiene un solo emisor o la cuenta tiene uno solo, puede omitirse. */
4787
4916
  issuer?: string;
@@ -5872,7 +6001,7 @@ export interface RollWebhookSecretParams {
5872
6001
  }
5873
6002
  export interface TestWebhookEndpointParams {
5874
6003
  /** El evento a mandar. Por omisión invoice.stamped. */
5875
- type?: "invoice.stamped" | "invoice.failed" | "invoice.canceled" | "invoice.cancellation_pending" | "invoice.cancellation_rejected" | "invoice.paid" | "invoice.partially_paid" | "retention.stamped" | "retention.failed" | "retention.canceled" | "invoice_batch.completed" | "customer_data_request.completed" | "sat_download.completed" | "sat_download.failed" | "sat_declaration.created" | "sat_declaration.updated" | "ticket.invoiced" | "ticket.included_in_global" | "recurring_invoice.failed" | "quote.viewed" | "quote.accepted" | "quote.changes_requested" | "quote.rejected" | "issuer.ready" | "balance.low" | "test_clock.ready";
6004
+ type?: "invoice.stamped" | "invoice.failed" | "invoice.canceled" | "invoice.cancellation_pending" | "invoice.cancellation_rejected" | "invoice.paid" | "invoice.partially_paid" | "retention.stamped" | "retention.failed" | "retention.canceled" | "invoice_batch.completed" | "payroll_batch.completed" | "customer_data_request.completed" | "sat_download.completed" | "sat_download.failed" | "sat_declaration.created" | "sat_declaration.updated" | "ticket.invoiced" | "ticket.included_in_global" | "recurring_invoice.failed" | "quote.viewed" | "quote.accepted" | "quote.changes_requested" | "quote.rejected" | "issuer.ready" | "balance.low" | "test_clock.ready";
5876
6005
  }
5877
6006
  /** Los parámetros de GET /v1/events. */
5878
6007
  export interface ListEventsParams {
@@ -5881,7 +6010,7 @@ export interface ListEventsParams {
5881
6010
  /** El id del último de la página anterior, para la siguiente. */
5882
6011
  starting_after?: string;
5883
6012
  /** Solo de este tipo (invoice.stamped), o todos los de un recurso con un comodín (invoice.*). */
5884
- type?: "invoice.stamped" | "invoice.failed" | "invoice.canceled" | "invoice.cancellation_pending" | "invoice.cancellation_rejected" | "invoice.paid" | "invoice.partially_paid" | "retention.stamped" | "retention.failed" | "retention.canceled" | "invoice_batch.completed" | "customer_data_request.completed" | "sat_download.completed" | "sat_download.failed" | "sat_declaration.created" | "sat_declaration.updated" | "ticket.invoiced" | "ticket.included_in_global" | "recurring_invoice.failed" | "quote.viewed" | "quote.accepted" | "quote.changes_requested" | "quote.rejected" | "issuer.ready" | "balance.low" | "test_clock.ready" | "invoice.*" | "invoice_batch.*" | "recurring_invoice.*" | "quote.*" | "ticket.*" | "retention.*" | "customer_data_request.*" | "sat_download.*" | "sat_declaration.*" | "issuer.*" | "balance.*" | "test_clock.*";
6013
+ type?: "invoice.stamped" | "invoice.failed" | "invoice.canceled" | "invoice.cancellation_pending" | "invoice.cancellation_rejected" | "invoice.paid" | "invoice.partially_paid" | "retention.stamped" | "retention.failed" | "retention.canceled" | "invoice_batch.completed" | "payroll_batch.completed" | "customer_data_request.completed" | "sat_download.completed" | "sat_download.failed" | "sat_declaration.created" | "sat_declaration.updated" | "ticket.invoiced" | "ticket.included_in_global" | "recurring_invoice.failed" | "quote.viewed" | "quote.accepted" | "quote.changes_requested" | "quote.rejected" | "issuer.ready" | "balance.low" | "test_clock.ready" | "invoice.*" | "invoice_batch.*" | "payroll_batch.*" | "recurring_invoice.*" | "quote.*" | "ticket.*" | "retention.*" | "customer_data_request.*" | "sat_download.*" | "sat_declaration.*" | "issuer.*" | "balance.*" | "test_clock.*";
5885
6014
  /** Solo los de este objeto (inv_…, ret_…, bat_…). */
5886
6015
  object?: string;
5887
6016
  /** false: los que algún webhook no recibió (su último intento falló). true: los que recibieron todos los webhooks a los que se mandaron. */
@@ -5917,7 +6046,7 @@ export declare class TestDataResource {
5917
6046
  /**
5918
6047
  * Reiniciar los datos de prueba
5919
6048
  *
5920
- * Deja el modo de pruebas como nuevo: cada emisor de pruebas conserva su RFC y su CSD de pruebas pero pierde sus facturas, clientes, productos, lotes, ligas y descargas, y se borran los eventos y el registro de solicitudes de pruebas. Las llaves y los webhooks se quedan. Con seed (por omisión) deja 3 clientes y 3 productos de ejemplo. Solo con una llave fk_test_; producción nunca se toca.
6049
+ * Deja el modo de pruebas como nuevo: cada emisor de pruebas conserva su RFC y su CSD de pruebas pero pierde sus facturas, clientes, productos, lotes, ligas y descargas, y se borran los eventos y el registro de solicitudes de pruebas. Las llaves y los webhooks se quedan. Con seed (por omisión) deja 2 clientes y 3 productos de ejemplo. Solo con una llave fk_test_; producción nunca se toca.
5921
6050
  *
5922
6051
  * POST /v1/test_data/reset
5923
6052
  * @see https://fiscalisto.com/docs/api/referencia/cuenta/reset-test-data
@@ -6540,7 +6669,7 @@ export declare class PayrollReceiptsResource {
6540
6669
  /**
6541
6670
  * Timbrar un recibo de nómina
6542
6671
  *
6543
- * Nómina ordinaria (Nómina 1.2): Fiscalisto calcula sueldo, ISR con subsidio al empleo e IMSS del empleado y el periodo, como la app. Queda como factura tipo N (GET /v1/invoices/{id}). El emisor necesita employer_registration.
6672
+ * Nómina ordinaria (Nómina 1.2): Fiscalisto calcula sueldo, ISR con subsidio al empleo e IMSS del empleado y el periodo, como la app, y nada más: aguinaldo, PTU, finiquitos, bonos, horas extra, Infonavit o préstamos los calcula su sistema y se timbran con POST /v1/payroll_receipts/external (pedirlos aquí contesta payroll_calculation_unsupported). Revise antes el recibo con POST /v1/payroll_receipts/preview y mande su confirmation_token: así solo se timbra el recibo que revisó (si cambió, 409 payroll_calculation_changed). Queda como factura tipo N (GET /v1/invoices/{id}). El emisor necesita employer_registration.
6544
6673
  *
6545
6674
  * POST /v1/payroll_receipts
6546
6675
  * @see https://fiscalisto.com/docs/api/referencia/nomina/create-payroll-receipt
@@ -6549,7 +6678,7 @@ export declare class PayrollReceiptsResource {
6549
6678
  /**
6550
6679
  * Calcular un recibo sin timbrar
6551
6680
  *
6552
- * El recibo como se timbraría (percepciones, ISR con el subsidio para el empleo, cuotas IMSS y el neto), sin timbrar ni usar timbres.
6681
+ * El recibo como se timbraría (percepciones, ISR con el subsidio para el empleo, cuotas IMSS y el neto), sin timbrar ni usar timbres, con el confirmation_token que lo timbra tal cual y los avisos de lo que no incluye (un finiquito, valores del año que aún no se cargan).
6553
6682
  *
6554
6683
  * POST /v1/payroll_receipts/preview
6555
6684
  * @see https://fiscalisto.com/docs/api/referencia/nomina/preview-payroll-receipt
@@ -6574,6 +6703,38 @@ export declare class PayrollReceiptsResource {
6574
6703
  */
6575
6704
  previewExternal(params: ExternalPayrollReceiptCreate, options?: RequestOptions): Promise<ExternalPayrollReceiptPreview>;
6576
6705
  }
6706
+ /** Nómina: fiscalisto.payrollBatches. */
6707
+ export declare class PayrollBatchesResource {
6708
+ #private;
6709
+ constructor(client: Client);
6710
+ /**
6711
+ * Timbrar una nómina completa (lote)
6712
+ *
6713
+ * Toda una corrida de nómina en una solicitud: hasta 1,000 recibos de un emisor, timbrados en segundo plano uno tras otro, sin el límite de timbres por segundo de una sola solicitud. De una de dos formas, nunca mezcladas: receipts (ids de empleado; Fiscalisto calcula cada recibo con el periodo del lote) o external_receipts (los recibos que calculó su sistema, como en POST /v1/payroll_receipts/external, con reference en lugar de metadata). Todo lo que se puede revisar antes se revisa antes: si algo falla, no se timbra ninguno y el error dice qué recibo (param receipts.3.employee). Lo que solo se sabe al timbrar (un periodo ya pagado, el SAT que rechaza un RFC) queda en ese recibo, con su error. Un recibo por empleado y periodo: mandar la corrida otra vez, aun con otra Idempotency-Key, devuelve los recibos que ya tiene. Responde 202; escuche payroll_batch.completed o consulte el lote.
6714
+ *
6715
+ * POST /v1/payroll_batches
6716
+ * @see https://fiscalisto.com/docs/api/referencia/nomina/create-payroll-batch
6717
+ */
6718
+ create(params?: CreatePayrollBatchParams, options?: RequestOptions): Promise<PayrollBatch>;
6719
+ /**
6720
+ * Listar lotes de nómina
6721
+ *
6722
+ * Los lotes de nómina, los más recientes primero, con cuántos recibos se timbraron y cuántos no.
6723
+ *
6724
+ * GET /v1/payroll_batches
6725
+ * @see https://fiscalisto.com/docs/api/referencia/nomina/list-payroll-batches
6726
+ */
6727
+ list(params?: ListPayrollBatchesParams, options?: RequestOptions): List<PayrollBatch>;
6728
+ /**
6729
+ * Ver un lote de nómina
6730
+ *
6731
+ * Con el recibo de cada empleado: timbrado (su factura y UUID) o por qué no (error.code y error.message).
6732
+ *
6733
+ * GET /v1/payroll_batches/{id}
6734
+ * @see https://fiscalisto.com/docs/api/referencia/nomina/get-payroll-batch
6735
+ */
6736
+ get(id: string, options?: RequestOptions): Promise<PayrollBatch>;
6737
+ }
6577
6738
  /** Lotes: fiscalisto.invoiceBatches. */
6578
6739
  export declare class InvoiceBatchesResource {
6579
6740
  #private;
@@ -7561,6 +7722,7 @@ export declare class FiscalistoApi extends Core {
7561
7722
  readonly retentions: RetentionsResource;
7562
7723
  readonly employees: EmployeesResource;
7563
7724
  readonly payrollReceipts: PayrollReceiptsResource;
7725
+ readonly payrollBatches: PayrollBatchesResource;
7564
7726
  readonly invoiceBatches: InvoiceBatchesResource;
7565
7727
  readonly taxIds: TaxIdsResource;
7566
7728
  readonly branches: BranchesResource;
package/dist/generated.js CHANGED
@@ -38,7 +38,7 @@ export class TestDataResource {
38
38
  /**
39
39
  * Reiniciar los datos de prueba
40
40
  *
41
- * Deja el modo de pruebas como nuevo: cada emisor de pruebas conserva su RFC y su CSD de pruebas pero pierde sus facturas, clientes, productos, lotes, ligas y descargas, y se borran los eventos y el registro de solicitudes de pruebas. Las llaves y los webhooks se quedan. Con seed (por omisión) deja 3 clientes y 3 productos de ejemplo. Solo con una llave fk_test_; producción nunca se toca.
41
+ * Deja el modo de pruebas como nuevo: cada emisor de pruebas conserva su RFC y su CSD de pruebas pero pierde sus facturas, clientes, productos, lotes, ligas y descargas, y se borran los eventos y el registro de solicitudes de pruebas. Las llaves y los webhooks se quedan. Con seed (por omisión) deja 2 clientes y 3 productos de ejemplo. Solo con una llave fk_test_; producción nunca se toca.
42
42
  *
43
43
  * POST /v1/test_data/reset
44
44
  * @see https://fiscalisto.com/docs/api/referencia/cuenta/reset-test-data
@@ -811,7 +811,7 @@ export class PayrollReceiptsResource {
811
811
  /**
812
812
  * Timbrar un recibo de nómina
813
813
  *
814
- * Nómina ordinaria (Nómina 1.2): Fiscalisto calcula sueldo, ISR con subsidio al empleo e IMSS del empleado y el periodo, como la app. Queda como factura tipo N (GET /v1/invoices/{id}). El emisor necesita employer_registration.
814
+ * Nómina ordinaria (Nómina 1.2): Fiscalisto calcula sueldo, ISR con subsidio al empleo e IMSS del empleado y el periodo, como la app, y nada más: aguinaldo, PTU, finiquitos, bonos, horas extra, Infonavit o préstamos los calcula su sistema y se timbran con POST /v1/payroll_receipts/external (pedirlos aquí contesta payroll_calculation_unsupported). Revise antes el recibo con POST /v1/payroll_receipts/preview y mande su confirmation_token: así solo se timbra el recibo que revisó (si cambió, 409 payroll_calculation_changed). Queda como factura tipo N (GET /v1/invoices/{id}). El emisor necesita employer_registration.
815
815
  *
816
816
  * POST /v1/payroll_receipts
817
817
  * @see https://fiscalisto.com/docs/api/referencia/nomina/create-payroll-receipt
@@ -822,7 +822,7 @@ export class PayrollReceiptsResource {
822
822
  /**
823
823
  * Calcular un recibo sin timbrar
824
824
  *
825
- * El recibo como se timbraría (percepciones, ISR con el subsidio para el empleo, cuotas IMSS y el neto), sin timbrar ni usar timbres.
825
+ * El recibo como se timbraría (percepciones, ISR con el subsidio para el empleo, cuotas IMSS y el neto), sin timbrar ni usar timbres, con el confirmation_token que lo timbra tal cual y los avisos de lo que no incluye (un finiquito, valores del año que aún no se cargan).
826
826
  *
827
827
  * POST /v1/payroll_receipts/preview
828
828
  * @see https://fiscalisto.com/docs/api/referencia/nomina/preview-payroll-receipt
@@ -853,6 +853,46 @@ export class PayrollReceiptsResource {
853
853
  return this.#client.request({ method: "POST", path: "/v1/payroll_receipts/external/preview", body: params, idempotent: true }, options);
854
854
  }
855
855
  }
856
+ /** Nómina: fiscalisto.payrollBatches. */
857
+ export class PayrollBatchesResource {
858
+ #client;
859
+ constructor(client) {
860
+ this.#client = client;
861
+ }
862
+ /**
863
+ * Timbrar una nómina completa (lote)
864
+ *
865
+ * Toda una corrida de nómina en una solicitud: hasta 1,000 recibos de un emisor, timbrados en segundo plano uno tras otro, sin el límite de timbres por segundo de una sola solicitud. De una de dos formas, nunca mezcladas: receipts (ids de empleado; Fiscalisto calcula cada recibo con el periodo del lote) o external_receipts (los recibos que calculó su sistema, como en POST /v1/payroll_receipts/external, con reference en lugar de metadata). Todo lo que se puede revisar antes se revisa antes: si algo falla, no se timbra ninguno y el error dice qué recibo (param receipts.3.employee). Lo que solo se sabe al timbrar (un periodo ya pagado, el SAT que rechaza un RFC) queda en ese recibo, con su error. Un recibo por empleado y periodo: mandar la corrida otra vez, aun con otra Idempotency-Key, devuelve los recibos que ya tiene. Responde 202; escuche payroll_batch.completed o consulte el lote.
866
+ *
867
+ * POST /v1/payroll_batches
868
+ * @see https://fiscalisto.com/docs/api/referencia/nomina/create-payroll-batch
869
+ */
870
+ create(params, options) {
871
+ return this.#client.request({ method: "POST", path: "/v1/payroll_batches", body: params, idempotent: true }, options);
872
+ }
873
+ /**
874
+ * Listar lotes de nómina
875
+ *
876
+ * Los lotes de nómina, los más recientes primero, con cuántos recibos se timbraron y cuántos no.
877
+ *
878
+ * GET /v1/payroll_batches
879
+ * @see https://fiscalisto.com/docs/api/referencia/nomina/list-payroll-batches
880
+ */
881
+ list(params, options) {
882
+ return this.#client.list({ path: "/v1/payroll_batches", query: params }, options);
883
+ }
884
+ /**
885
+ * Ver un lote de nómina
886
+ *
887
+ * Con el recibo de cada empleado: timbrado (su factura y UUID) o por qué no (error.code y error.message).
888
+ *
889
+ * GET /v1/payroll_batches/{id}
890
+ * @see https://fiscalisto.com/docs/api/referencia/nomina/get-payroll-batch
891
+ */
892
+ get(id, options) {
893
+ return this.#client.request({ method: "GET", path: `/v1/payroll_batches/${encodeURIComponent(id)}` }, options);
894
+ }
895
+ }
856
896
  /** Lotes: fiscalisto.invoiceBatches. */
857
897
  export class InvoiceBatchesResource {
858
898
  #client;
@@ -2076,6 +2116,7 @@ export class FiscalistoApi extends Core {
2076
2116
  retentions = new RetentionsResource(this);
2077
2117
  employees = new EmployeesResource(this);
2078
2118
  payrollReceipts = new PayrollReceiptsResource(this);
2119
+ payrollBatches = new PayrollBatchesResource(this);
2079
2120
  invoiceBatches = new InvoiceBatchesResource(this);
2080
2121
  taxIds = new TaxIdsResource(this);
2081
2122
  branches = new BranchesResource(this);