fiscalisto 0.1.36 → 0.1.37

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- Costo en producci\u00F3n: paquetes de timbres prepagados, sin mensualidad. Cada CFDI timbrado usa 1;\n las consultas al SAT tambi\u00E9n (1 por cada 10 RFC en listas o constancias al mes, 1 por cada 100 CFDI\n descargados, 1 por consulta de declaraciones, opini\u00F3n o buz\u00F3n). Cancelar, leer, PDF/XML, correos y\n webhooks no cuestan. Sin timbres: `402` `insufficient_balance`. Precios:\n https://fiscalisto.com/docs/api/pruebas-y-produccion.md\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";
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- Costo en producci\u00F3n: paquetes de timbres prepagados, sin mensualidad. Cada CFDI timbrado usa 1;\n las consultas al SAT tambi\u00E9n (1 por cada 10 RFC en listas o constancias de clientes con `cif_id` al\n mes, 1 por cada 100 CFDI descargados, 1 por consulta de opini\u00F3n, constancia de situaci\u00F3n\n fiscal, buz\u00F3n o declaraciones del emisor; validar sin `cif_id` no cuesta). Cancelar, leer, PDF/XML, correos y\n webhooks no cuestan. Sin timbres: `402` `insufficient_balance`. Precios:\n https://fiscalisto.com/docs/api/pruebas-y-produccion.md\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;
@@ -17,8 +17,9 @@ mensajes de error y los textos, en español (\`Accept-Language: en\` los da en i
17
17
  - Llaves: \`fk_test_…\` timbra en el ambiente de pruebas del SAT, gratis; \`fk_live_…\` timbra CFDI
18
18
  reales y usa un timbre cada uno. Se crean en **Desarrolladores › Llaves**.
19
19
  - Costo en producción: paquetes de timbres prepagados, sin mensualidad. Cada CFDI timbrado usa 1;
20
- las consultas al SAT también (1 por cada 10 RFC en listas o constancias al mes, 1 por cada 100 CFDI
21
- descargados, 1 por consulta de declaraciones, opinión o buzón). Cancelar, leer, PDF/XML, correos y
20
+ las consultas al SAT también (1 por cada 10 RFC en listas o constancias de clientes con \`cif_id\` al
21
+ mes, 1 por cada 100 CFDI descargados, 1 por consulta de opinión, constancia de situación
22
+ fiscal, buzón o declaraciones del emisor; validar sin \`cif_id\` no cuesta). Cancelar, leer, PDF/XML, correos y
22
23
  webhooks no cuestan. Sin timbres: \`402\` \`insufficient_balance\`. Precios:
23
24
  ${DOCS}/pruebas-y-produccion.md
24
25
  - Documentación para agentes: ${DOCS}/llms.txt (índice; cada página también en \`.md\`), la
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.36";
7
+ export declare const VERSION = "0.1.37";
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.36";
6
+ export const VERSION = "0.1.37";
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.
@@ -1603,6 +1603,80 @@ export interface SatInvoice {
1603
1603
  /** Cuándo llegó. */
1604
1604
  downloaded_at: string | null;
1605
1605
  }
1606
+ /** Un CFDI de retenciones e información de pagos del emisor, recibido (la constancia que le dio un banco, una plataforma o quien le pagó) o emitido, como lo muestra Facturas › Retenciones. */
1607
+ export interface SatRetention {
1608
+ /** Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). */
1609
+ id: string;
1610
+ /** true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. */
1611
+ livemode: boolean;
1612
+ /** Qué tipo de objeto es («invoice», «customer»…). */
1613
+ object: "sat_retention";
1614
+ /** El emisor de su cuenta (iss_…) a quien pertenece esta constancia. */
1615
+ issuer: string;
1616
+ /** El folio fiscal (UUID del timbre). */
1617
+ uuid: string;
1618
+ /** received (se la dieron al emisor: un banco, una plataforma, quien le pagó) o issued (la emitió). */
1619
+ direction: "received" | "issued";
1620
+ /** La fecha de expedición (FechaExp). */
1621
+ date: string;
1622
+ /** Folio interno (FolioInt), o null. */
1623
+ internal_folio: string | null;
1624
+ /** Clave de la retención (CveRetenc), como 14 dividendos, 16 intereses o 26 plataformas. */
1625
+ code: string | null;
1626
+ /** Descripción de la retención (DescRetenc), o null. */
1627
+ description: string | null;
1628
+ /** Quien retuvo (Emisor). */
1629
+ issued_by: {
1630
+ /** RFC (Rfc), 12 caracteres una persona moral y 13 una física. */
1631
+ tax_id: string | null;
1632
+ /** Nombre o razón social tal como está en la constancia de situación fiscal, sin el régimen de capital (sin «S.A. de C.V.»). */
1633
+ legal_name: string | null;
1634
+ };
1635
+ /** A quien le retuvieron (Receptor). */
1636
+ issued_to: {
1637
+ /** RFC (Rfc), 12 caracteres una persona moral y 13 una física. */
1638
+ tax_id: string | null;
1639
+ /** Nombre o razón social tal como está en la constancia de situación fiscal, sin el régimen de capital (sin «S.A. de C.V.»). */
1640
+ legal_name: string | null;
1641
+ };
1642
+ /** Los meses y el ejercicio que cubre (Periodo), o null si no se pudo leer. */
1643
+ period: {
1644
+ /** Ejercicio (Ejercicio). */
1645
+ year: number;
1646
+ /** Mes inicial (MesIni), 1 a 12. */
1647
+ month_start: number;
1648
+ /** Mes final (MesFin), 1 a 12. */
1649
+ month_end: number;
1650
+ } | null;
1651
+ /** Los montos de Totales. */
1652
+ totals: {
1653
+ /** Monto total de la operación (MontoTotOperacion). */
1654
+ operation: number | null;
1655
+ /** Monto gravado (MontoTotGrav). Por omisión, operation menos exempt. */
1656
+ taxed: number | null;
1657
+ /** Monto exento (MontoTotExent). Por omisión 0. */
1658
+ exempt: number | null;
1659
+ /** Total retenido (MontoTotRet). */
1660
+ withheld: number | null;
1661
+ };
1662
+ /** Cada impuesto retenido (ImpRetenidos). */
1663
+ withheld_taxes: {
1664
+ /** Base del impuesto retenido (BaseRet). */
1665
+ base: number | null;
1666
+ /** Impuesto: isr, iva o ieps (ImpuestoRet 001, 002, 003). */
1667
+ tax: string | null;
1668
+ /** Importe. */
1669
+ amount: number | null;
1670
+ /** Tipo de pago de la retención (TipoPagoRet): 01 definitivo IVA, 02 definitivo IEPS, 03 definitivo ISR, 04 provisional ISR. Por omisión el usual de cada impuesto. */
1671
+ payment_type: string | null;
1672
+ }[];
1673
+ /** active o canceled: la canceló el emisor en Fiscalisto, o el SAT la reporta cancelada (se revisa cada mes). Una cancelada ya no es impuesto retenido. */
1674
+ status: "active" | "canceled";
1675
+ /** Si su XML no se pudo leer, por qué; sus campos quedan en null. Si no, null. */
1676
+ read_error: string | null;
1677
+ /** Cuándo llegó a Fiscalisto. */
1678
+ downloaded_at: string | null;
1679
+ }
1606
1680
  /** Una declaración que el emisor presentó ante el SAT (provisional o definitiva, anual o del servicio anterior Declaraciones y pagos), con sus cifras y sus archivos. */
1607
1681
  export interface SatDeclaration {
1608
1682
  /** Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). */
@@ -4147,6 +4221,16 @@ export interface SatInvoiceList {
4147
4221
  /** La ruta de esta lista. */
4148
4222
  url: string;
4149
4223
  }
4224
+ export interface SatRetentionList {
4225
+ /** Qué tipo de objeto es («invoice», «customer»…). */
4226
+ object: "list";
4227
+ /** Los objetos de esta página. */
4228
+ data: SatRetention[];
4229
+ /** true si hay más: pida la siguiente con starting_after igual al id del último. */
4230
+ has_more: boolean;
4231
+ /** La ruta de esta lista. */
4232
+ url: string;
4233
+ }
4150
4234
  export interface SatDeclarationList {
4151
4235
  /** Qué tipo de objeto es («invoice», «customer»…). */
4152
4236
  object: "list";
@@ -7172,6 +7256,27 @@ export interface UpdateSatInvoiceParams {
7172
7256
  /** Su centro de costo (ccn_…), o null para quitárselo. Los complementos de pago y los traslados no llevan. */
7173
7257
  cost_center?: string | null;
7174
7258
  }
7259
+ /** Los parámetros de GET /v1/sat_retentions. */
7260
+ export interface ListSatRetentionsParams {
7261
+ /** Cuántos por página, de 1 a 100. Por omisión 10. */
7262
+ limit?: number;
7263
+ /** El id del último de la página anterior, para la siguiente. */
7264
+ starting_after?: string;
7265
+ /** El emisor (iss_…). Puede omitirse si la llave o la cuenta tienen uno solo. */
7266
+ issuer?: string;
7267
+ /** received (por omisión) o issued. */
7268
+ direction?: "received" | "issued";
7269
+ /** active o canceled. Sin él, las dos. */
7270
+ status?: "active" | "canceled";
7271
+ /** El RFC de quien retuvo (recibidas) o a quien le retuvo (emitidas). */
7272
+ counterparty_tax_id?: string;
7273
+ /** Clave de la retención (CveRetenc) de dos dígitos, como 16 o 26. */
7274
+ code?: string;
7275
+ /** Solo las de un ejercicio, como 2025. */
7276
+ year?: number;
7277
+ /** Solo las que cubren este mes (1 a 12): una anual de enero a diciembre cubre todos. */
7278
+ month?: number;
7279
+ }
7175
7280
  export interface RefreshSatDeclarationsParams {
7176
7281
  /** El emisor (iss_…). Por omisión, su único emisor. */
7177
7282
  issuer?: string;
@@ -10045,6 +10150,47 @@ export declare class SatInvoicesResource {
10045
10150
  */
10046
10151
  pdf(id: string, options?: RequestOptions): Promise<Uint8Array>;
10047
10152
  }
10153
+ /** Descargas del SAT: fiscalisto.satRetentions. */
10154
+ export declare class SatRetentionsResource {
10155
+ #private;
10156
+ constructor(client: Client);
10157
+ /**
10158
+ * Listar constancias de retenciones
10159
+ *
10160
+ * Los CFDI de retenciones e información de pagos del emisor, como los muestra Facturas › Retenciones: los que recibió (descargados del SAT o subidos) o los que emitió, del más reciente al más antiguo, con las canceladas marcadas. Las que emite por la API también están en GET /v1/retentions.
10161
+ *
10162
+ * GET /v1/sat_retentions
10163
+ * @see https://fiscalisto.com/docs/api/referencia/descargas-del-sat/list-sat-retentions
10164
+ */
10165
+ list(params?: ListSatRetentionsParams, options?: RequestOptions): List<SatRetention>;
10166
+ /**
10167
+ * Ver una constancia de retenciones
10168
+ *
10169
+ * Una constancia de retenciones del emisor, con sus montos, impuestos y estado.
10170
+ *
10171
+ * GET /v1/sat_retentions/{id}
10172
+ * @see https://fiscalisto.com/docs/api/referencia/descargas-del-sat/get-sat-retention
10173
+ */
10174
+ get(id: string, options?: RequestOptions): Promise<SatRetention>;
10175
+ /**
10176
+ * Descargar el XML de una constancia de retenciones
10177
+ *
10178
+ * El CFDI de retenciones tal como llegó.
10179
+ *
10180
+ * GET /v1/sat_retentions/{id}/xml
10181
+ * @see https://fiscalisto.com/docs/api/referencia/descargas-del-sat/get-sat-retention-xml
10182
+ */
10183
+ xml(id: string, options?: RequestOptions): Promise<string>;
10184
+ /**
10185
+ * Descargar el PDF de una constancia de retenciones
10186
+ *
10187
+ * La constancia en PDF, como la ofrece Facturas › Retenciones. El XML es el documento válido ante el SAT.
10188
+ *
10189
+ * GET /v1/sat_retentions/{id}/pdf
10190
+ * @see https://fiscalisto.com/docs/api/referencia/descargas-del-sat/get-sat-retention-pdf
10191
+ */
10192
+ pdf(id: string, options?: RequestOptions): Promise<Uint8Array>;
10193
+ }
10048
10194
  /** Declaraciones del SAT: fiscalisto.satDeclarations. */
10049
10195
  export declare class SatDeclarationsResource {
10050
10196
  #private;
@@ -10756,6 +10902,7 @@ export declare class FiscalistoApi extends Core {
10756
10902
  readonly satLists: SatListsResource;
10757
10903
  readonly satDownloads: SatDownloadsResource;
10758
10904
  readonly satInvoices: SatInvoicesResource;
10905
+ readonly satRetentions: SatRetentionsResource;
10759
10906
  readonly satDeclarations: SatDeclarationsResource;
10760
10907
  readonly tickets: TicketsResource;
10761
10908
  readonly accounting: AccountingResource;
package/dist/generated.js CHANGED
@@ -2226,6 +2226,57 @@ export class SatInvoicesResource {
2226
2226
  return this.#client.request({ method: "GET", path: `/v1/sat_invoices/${encodeURIComponent(id)}/pdf`, as: "bytes" }, options);
2227
2227
  }
2228
2228
  }
2229
+ /** Descargas del SAT: fiscalisto.satRetentions. */
2230
+ export class SatRetentionsResource {
2231
+ #client;
2232
+ constructor(client) {
2233
+ this.#client = client;
2234
+ }
2235
+ /**
2236
+ * Listar constancias de retenciones
2237
+ *
2238
+ * Los CFDI de retenciones e información de pagos del emisor, como los muestra Facturas › Retenciones: los que recibió (descargados del SAT o subidos) o los que emitió, del más reciente al más antiguo, con las canceladas marcadas. Las que emite por la API también están en GET /v1/retentions.
2239
+ *
2240
+ * GET /v1/sat_retentions
2241
+ * @see https://fiscalisto.com/docs/api/referencia/descargas-del-sat/list-sat-retentions
2242
+ */
2243
+ list(params, options) {
2244
+ return this.#client.list({ path: "/v1/sat_retentions", query: params }, options);
2245
+ }
2246
+ /**
2247
+ * Ver una constancia de retenciones
2248
+ *
2249
+ * Una constancia de retenciones del emisor, con sus montos, impuestos y estado.
2250
+ *
2251
+ * GET /v1/sat_retentions/{id}
2252
+ * @see https://fiscalisto.com/docs/api/referencia/descargas-del-sat/get-sat-retention
2253
+ */
2254
+ get(id, options) {
2255
+ return this.#client.request({ method: "GET", path: `/v1/sat_retentions/${encodeURIComponent(id)}` }, options);
2256
+ }
2257
+ /**
2258
+ * Descargar el XML de una constancia de retenciones
2259
+ *
2260
+ * El CFDI de retenciones tal como llegó.
2261
+ *
2262
+ * GET /v1/sat_retentions/{id}/xml
2263
+ * @see https://fiscalisto.com/docs/api/referencia/descargas-del-sat/get-sat-retention-xml
2264
+ */
2265
+ xml(id, options) {
2266
+ return this.#client.request({ method: "GET", path: `/v1/sat_retentions/${encodeURIComponent(id)}/xml`, as: "text" }, options);
2267
+ }
2268
+ /**
2269
+ * Descargar el PDF de una constancia de retenciones
2270
+ *
2271
+ * La constancia en PDF, como la ofrece Facturas › Retenciones. El XML es el documento válido ante el SAT.
2272
+ *
2273
+ * GET /v1/sat_retentions/{id}/pdf
2274
+ * @see https://fiscalisto.com/docs/api/referencia/descargas-del-sat/get-sat-retention-pdf
2275
+ */
2276
+ pdf(id, options) {
2277
+ return this.#client.request({ method: "GET", path: `/v1/sat_retentions/${encodeURIComponent(id)}/pdf`, as: "bytes" }, options);
2278
+ }
2279
+ }
2229
2280
  /** Declaraciones del SAT: fiscalisto.satDeclarations. */
2230
2281
  export class SatDeclarationsResource {
2231
2282
  #client;
@@ -3093,6 +3144,7 @@ export class FiscalistoApi extends Core {
3093
3144
  satLists = new SatListsResource(this);
3094
3145
  satDownloads = new SatDownloadsResource(this);
3095
3146
  satInvoices = new SatInvoicesResource(this);
3147
+ satRetentions = new SatRetentionsResource(this);
3096
3148
  satDeclarations = new SatDeclarationsResource(this);
3097
3149
  tickets = new TicketsResource(this);
3098
3150
  accounting = new AccountingResource(this);