fiscalisto 0.1.4 → 0.1.6
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.
- package/README.md +12 -0
- package/dist/agent-guide.d.ts +10 -0
- package/dist/agent-guide.js +156 -0
- package/dist/cli.js +15 -4
- package/dist/core.d.ts +1 -1
- package/dist/core.js +1 -1
- package/dist/error-codes.d.ts +6 -0
- package/dist/error-codes.js +6 -0
- package/dist/generated.d.ts +855 -22
- package/dist/generated.js +312 -0
- package/dist/mock-routes.gen.js +1 -1
- package/package.json +7 -2
package/README.md
CHANGED
|
@@ -30,6 +30,18 @@ const invoice = await fiscalisto.invoices.create(
|
|
|
30
30
|
console.log(invoice.uuid, invoice.total);
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
+
## Con agentes de IA
|
|
34
|
+
|
|
35
|
+
Para que Claude Code, Cursor, Codex u otro agente integre Fiscalisto, conecte el servidor MCP de la documentación (sin llave) y pídale que empiece con `get_started`:
|
|
36
|
+
|
|
37
|
+
`npx fiscalisto init --agents` deja además la guía en `.claude/skills/fiscalisto/SKILL.md` y una sección en su `AGENTS.md`. Para conectar la documentación:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
claude mcp add --transport http fiscalisto-docs https://fiscalisto.com/docs/api/mcp
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
La guía de integración en una página está en [fiscalisto.com/docs/api/SKILL.md](https://fiscalisto.com/docs/api/SKILL.md) y el índice de la documentación para agentes en [llms.txt](https://fiscalisto.com/docs/api/llms.txt). Otros clientes y más: [fiscalisto.com/docs/api/agentes](https://fiscalisto.com/docs/api/agentes).
|
|
44
|
+
|
|
33
45
|
## CLI
|
|
34
46
|
|
|
35
47
|
El mismo paquete trae el CLI: `npx fiscalisto login` inicia sesión por el navegador, `npx fiscalisto init` deja el SDK y su llave en su proyecto, y `npx fiscalisto listen --forward-to http://localhost:3000/webhooks` le manda los webhooks de pruebas a su computadora. Con `--json`, para agentes y scripts. Vea [fiscalisto.com/docs/api/cli](https://fiscalisto.com/docs/api/cli).
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a coding agent adds Fiscalisto to an app, in one page: the Agent Skill that
|
|
3
|
+
* `fiscalisto init --agents` leaves in .claude/skills/fiscalisto/SKILL.md, the same text the site
|
|
4
|
+
* serves at https://fiscalisto.com/docs/api/SKILL.md and the docs MCP answers with get_started.
|
|
5
|
+
* Written by hand; keep it short (an agent reads all of it) and true to the docs it links.
|
|
6
|
+
*/
|
|
7
|
+
export declare const AGENT_SKILL_DESCRIPTION = "Agregar facturaci\u00F3n electr\u00F3nica mexicana (CFDI 4.0) a una app con la API y los SDKs de Fiscalisto: timbrar facturas, pagos (PPD), notas de cr\u00E9dito, n\u00F3mina y retenciones, cancelar, webhooks. Use it whenever the user wants to issue Mexican invoices (CFDI, SAT, timbrado, factura electr\u00F3nica) or integrate Fiscalisto.";
|
|
8
|
+
export declare const AGENT_GUIDE = "# Facturar con Fiscalisto (CFDI 4.0)\n\nFiscalisto es una API REST que timbra comprobantes fiscales mexicanos (CFDI 4.0): revisa las reglas\ndel SAT antes de gastar un timbre, sella con el certificado del emisor y timbra con el PAC. Los\nnombres de la API est\u00E1n en ingl\u00E9s (`customer`, `items`, `unit_price`); la documentaci\u00F3n, los\nmensajes de error y los textos, en espa\u00F1ol (`Accept-Language: en` los da en ingl\u00E9s).\n\n- Base: `https://api.fiscalisto.com/v1`, JSON, `Authorization: Bearer <llave>`.\n- Llaves: `fk_test_\u2026` timbra en el ambiente de pruebas del SAT, gratis; `fk_live_\u2026` timbra CFDI\n reales y usa un timbre cada uno. Se crean en **Desarrolladores \u203A Llaves**.\n- Documentaci\u00F3n para agentes: https://fiscalisto.com/docs/api/llms.txt (\u00EDndice; cada p\u00E1gina tambi\u00E9n en `.md`), la\n referencia OpenAPI 3.1 en https://api.fiscalisto.com/v1/openapi.json y el servidor MCP\n https://fiscalisto.com/docs/api/mcp (sin llave) con search_docs, describe_operation, describe_object, explain_error y\n call_api.\n\n## Antes de escribir c\u00F3digo\n\n1. **La llave.** P\u00EDdasela a la persona y gu\u00E1rdela en `FISCALISTO_API_KEY` (en `.env`, nunca en el\n repositorio). Si no tiene: `npx fiscalisto login` abre el navegador y guarda su llave de\n pruebas; `npx fiscalisto init` instala el SDK y deja la llave en `.env`. Nunca invente una.\n2. **Sin llave todav\u00EDa:** `npx fiscalisto mock` levanta la API en http://127.0.0.1:12111, sin\n internet (`new Fiscalisto(\"fk_test_mock\", { baseUrl: \"http://127.0.0.1:12111\" })`). Contesta\n como la API pero no revisa reglas del SAT: pruebe despu\u00E9s con una `fk_test_`.\n3. **El SDK de su lenguaje** (los seis tienen cada ruta, tipos e Idempotency-Key autom\u00E1tica):\n\n| Lenguaje | Instalar | Cliente |\n| --- | --- | --- |\n| TypeScript / JavaScript | `npm install fiscalisto` | `new Fiscalisto()` |\n| Python | `pip install fiscalisto` | `Fiscalisto()` |\n| PHP | `composer require fiscalisto/fiscalisto` | `new Fiscalisto\\Fiscalisto()` |\n| Go | `go get fiscalisto.com/go` | `fiscalisto.NewClient(\"\")` |\n| Java | Maven `com.fiscalisto:fiscalisto` | `new FiscalistoClient()` |\n| C# / .NET | `dotnet add package Fiscalisto` | `new FiscalistoClient()` |\n\nSin argumento, cada cliente lee `FISCALISTO_API_KEY`. El c\u00F3digo de cada operaci\u00F3n en cada lenguaje:\n`describe_operation` del MCP (con `language`) o la p\u00E1gina `.md` de la referencia.\n\n## Timbrar una factura\n\n```ts\nimport { Fiscalisto } from \"fiscalisto\";\n\nconst fiscalisto = new Fiscalisto(); // FISCALISTO_API_KEY\n\nconst invoice = await fiscalisto.invoices.create(\n {\n customer: { tax_id: \"ICV060329BY0\", legal_name: \"INMOBILIARIA CVA\", tax_system: \"601\", zip: \"33826\" },\n payment_form: \"03\", // transferencia\n items: [{ description: \"Mensualidad\", product_key: \"86121700\", quantity: 2, unit_price: 2500 }],\n },\n { idempotencyKey: `pedido-${order.id}` },\n);\n// Guarde invoice.id (inv_\u2026) y invoice.uuid (el folio fiscal) con su pedido.\n```\n\n- **Idempotency-Key = el id de su pedido.** Si la respuesta se pierde, repetir con la misma nunca\n timbra dos veces. No use una al azar en cada intento.\n- **El cliente (Receptor) va exactamente como en su constancia de situaci\u00F3n fiscal:** RFC\n (`tax_id`), nombre sin r\u00E9gimen de capital (sin \u00ABS.A. de C.V.\u00BB), r\u00E9gimen (`tax_system`, c_RegimenFiscal)\n y c\u00F3digo postal (`zip`). Si su app no tiene esos datos, p\u00EDdalos con una liga\n (`POST /v1/customer_data_requests`) o rev\u00EDselos con `POST /v1/tax_ids/validate`; guarde clientes\n frecuentes con `/v1/customers` y mande su `cus_\u2026`.\n- Lo que omite toma el valor usual: PUE, MXN, uso G03 (S01 con r\u00E9gimen 616), objeto de impuesto 02,\n IVA 16 %, cantidad 1, unidad E48. `unit_price` es sin IVA, en pesos.\n- **Claves del SAT:** no las invente. B\u00FAsquelas en los cat\u00E1logos (`/v1/sat_catalogs/{name}`, por ejemplo\n `product_keys`) o guarde productos (`/v1/products`, `prd_\u2026`) con su clave.\n- **La respuesta** trae `status: \"valid\"` con UUID, PDF y XML. Si el PAC tarda llega\n `processing`: no repita con otra llave de idempotencia; espere el webhook `invoice.stamped`\n (o `invoice.failed`).\n- **PDF y XML:** `invoices.pdf(id)`, `invoices.xml(id)`; `invoices.send(id)` lo manda por correo.\n- **A cr\u00E9dito (PPD):** `payment_method: \"PPD\"`, `payment_form: \"99\"`; cada cobro lleva su\n complemento de pago (`POST /v1/payments`) a m\u00E1s tardar el d\u00EDa 5 del mes siguiente.\n- Otros comprobantes: notas de cr\u00E9dito (`/v1/credit_notes`), anticipos (`/v1/advances`), n\u00F3mina\n (`/v1/payroll_receipts`), retenciones (`/v1/retentions`), lotes de hasta 1,000\n (`/v1/invoice_batches`), factura global y autofactura por ticket (`/v1/tickets`).\n\n## Errores\n\nCada error trae `error.type`, `error.code`, `error.message` (en espa\u00F1ol) y `error.param` (el\ncampo a corregir). Un rechazo del SAT llega como `invoice_rejected` con su regla en\n`error.sat_code` (CFDI40\u2026): muestre el mensaje a la persona y corrija el dato; no reintente igual.\nEl SDK solo reintenta lo que es seguro repetir. `explain_error` del MCP dice qu\u00E9 hacer con cada\nc\u00F3digo; la lista completa est\u00E1 en https://fiscalisto.com/docs/api/errores.md.\n\n## Webhooks\n\nLo que pasa despu\u00E9s (timbrado tard\u00EDo, cancelaci\u00F3n aceptada d\u00EDas despu\u00E9s, lotes) llega a su endpoint\ncomo evento firmado. Cr\u00E9elo en **Desarrolladores \u203A Webhooks** o con `POST /v1/webhook_endpoints`\ny guarde su secreto `whsec_\u2026` en `FISCALISTO_WEBHOOK_SECRET`.\n\n```ts\nimport { FiscalistoWebhookError, verifyWebhook } from \"fiscalisto\";\n\nexport async function POST(request: Request) {\n try {\n // El cuerpo tal como lleg\u00F3 (texto), sin interpretarlo antes.\n const event = await verifyWebhook(await request.text(), request.headers, process.env.FISCALISTO_WEBHOOK_SECRET!);\n if (event.type === \"invoice.stamped\") await marcarFacturado(event.data.object);\n return new Response(null, { status: 200 });\n } catch (error) {\n if (error instanceof FiscalistoWebhookError) return new Response(null, { status: 400 });\n throw error;\n }\n}\n```\n\nConteste 2xx r\u00E1pido y procese aparte; un evento puede llegar m\u00E1s de una vez: ignore el `evt_\u2026` que\nya proces\u00F3. En desarrollo, `npx fiscalisto listen --forward-to http://localhost:3000/webhooks` le\nreenv\u00EDa los eventos de pruebas y `npx fiscalisto trigger invoice.stamped` provoca uno.\n\n## Cancelar\n\n`invoices.cancel(id, { motive: \"02\" })`: 02 con errores y sin sustituir (el usual), 01 con errores y sustituida\n(`substitution: \"inv_\u2026\"`, o `invoices.substitute` timbra la nueva y cancela la anterior), 03 no\nse llev\u00F3 a cabo y 04 solo en una factura global (una venta se factur\u00F3 despu\u00E9s a nombre del\ncliente). Si el cliente debe aceptar llega\n`invoice.cancellation_pending` y despu\u00E9s `invoice.canceled` o `invoice.cancellation_rejected`.\n\n## Probar\n\n- Las llaves `fk_test_` aplican las mismas revisiones del SAT que producci\u00F3n; una cuenta nueva ya\n tiene un emisor de pruebas listo.\n- RFC de prueba que provocan cada rechazo del SAT (por ejemplo `NOM010101FK9` \u2192 `CFDI40145`):\n https://fiscalisto.com/docs/api/pruebas-y-produccion.md#provocar-cada-rechazo-del-sat.\n- `call_api` del MCP prueba un cuerpo real con la llave de pruebas antes de escribirlo en c\u00F3digo.\n- Pruebas autom\u00E1ticas: `POST /v1/test_data/reset` deja el modo de pruebas como nuevo.\n\n## Nunca\n\n- Poner la llave en el navegador o en una app m\u00F3vil: la API rechaza el navegador\n (`browser_not_supported`). Llame desde su servidor.\n- Usar una `fk_live_` para probar: timbra CFDI reales con valor fiscal.\n- Inventar folios, UUID, RFC, reg\u00EDmenes o claves del SAT: cons\u00FAltelos.\n\n## Pasar a producci\u00F3n\n\nEmisor real (`POST /v1/issuers`), su CSD (`/certificates`), la firma con e.firma del contrato\ncon el PAC (`/efirma`) o, m\u00E1s f\u00E1cil, una liga para que el due\u00F1o lo haga\n(`POST /v1/issuers/{id}/onboarding_links`); timbres en **Desarrolladores \u203A Timbres**; y la llave\n`fk_live_` en el servidor. Detalle: https://fiscalisto.com/docs/api/pruebas-y-produccion.md#pasar-a-produccion.\n";
|
|
9
|
+
/** The guide as an Agent Skill (agentskills.io): SKILL.md with its name and description. */
|
|
10
|
+
export declare const AGENT_SKILL: string;
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a coding agent adds Fiscalisto to an app, in one page: the Agent Skill that
|
|
3
|
+
* `fiscalisto init --agents` leaves in .claude/skills/fiscalisto/SKILL.md, the same text the site
|
|
4
|
+
* serves at https://fiscalisto.com/docs/api/SKILL.md and the docs MCP answers with get_started.
|
|
5
|
+
* Written by hand; keep it short (an agent reads all of it) and true to the docs it links.
|
|
6
|
+
*/
|
|
7
|
+
const DOCS = "https://fiscalisto.com/docs/api";
|
|
8
|
+
export const AGENT_SKILL_DESCRIPTION = "Agregar facturación electrónica mexicana (CFDI 4.0) a una app con la API y los SDKs de Fiscalisto: timbrar facturas, pagos (PPD), notas de crédito, nómina y retenciones, cancelar, webhooks. Use it whenever the user wants to issue Mexican invoices (CFDI, SAT, timbrado, factura electrónica) or integrate Fiscalisto.";
|
|
9
|
+
export const AGENT_GUIDE = `# Facturar con Fiscalisto (CFDI 4.0)
|
|
10
|
+
|
|
11
|
+
Fiscalisto es una API REST que timbra comprobantes fiscales mexicanos (CFDI 4.0): revisa las reglas
|
|
12
|
+
del SAT antes de gastar un timbre, sella con el certificado del emisor y timbra con el PAC. Los
|
|
13
|
+
nombres de la API están en inglés (\`customer\`, \`items\`, \`unit_price\`); la documentación, los
|
|
14
|
+
mensajes de error y los textos, en español (\`Accept-Language: en\` los da en inglés).
|
|
15
|
+
|
|
16
|
+
- Base: \`https://api.fiscalisto.com/v1\`, JSON, \`Authorization: Bearer <llave>\`.
|
|
17
|
+
- Llaves: \`fk_test_…\` timbra en el ambiente de pruebas del SAT, gratis; \`fk_live_…\` timbra CFDI
|
|
18
|
+
reales y usa un timbre cada uno. Se crean en **Desarrolladores › Llaves**.
|
|
19
|
+
- Documentación para agentes: ${DOCS}/llms.txt (índice; cada página también en \`.md\`), la
|
|
20
|
+
referencia OpenAPI 3.1 en https://api.fiscalisto.com/v1/openapi.json y el servidor MCP
|
|
21
|
+
${DOCS}/mcp (sin llave) con search_docs, describe_operation, describe_object, explain_error y
|
|
22
|
+
call_api.
|
|
23
|
+
|
|
24
|
+
## Antes de escribir código
|
|
25
|
+
|
|
26
|
+
1. **La llave.** Pídasela a la persona y guárdela en \`FISCALISTO_API_KEY\` (en \`.env\`, nunca en el
|
|
27
|
+
repositorio). Si no tiene: \`npx fiscalisto login\` abre el navegador y guarda su llave de
|
|
28
|
+
pruebas; \`npx fiscalisto init\` instala el SDK y deja la llave en \`.env\`. Nunca invente una.
|
|
29
|
+
2. **Sin llave todavía:** \`npx fiscalisto mock\` levanta la API en http://127.0.0.1:12111, sin
|
|
30
|
+
internet (\`new Fiscalisto("fk_test_mock", { baseUrl: "http://127.0.0.1:12111" })\`). Contesta
|
|
31
|
+
como la API pero no revisa reglas del SAT: pruebe después con una \`fk_test_\`.
|
|
32
|
+
3. **El SDK de su lenguaje** (los seis tienen cada ruta, tipos e Idempotency-Key automática):
|
|
33
|
+
|
|
34
|
+
| Lenguaje | Instalar | Cliente |
|
|
35
|
+
| --- | --- | --- |
|
|
36
|
+
| TypeScript / JavaScript | \`npm install fiscalisto\` | \`new Fiscalisto()\` |
|
|
37
|
+
| Python | \`pip install fiscalisto\` | \`Fiscalisto()\` |
|
|
38
|
+
| PHP | \`composer require fiscalisto/fiscalisto\` | \`new Fiscalisto\\Fiscalisto()\` |
|
|
39
|
+
| Go | \`go get fiscalisto.com/go\` | \`fiscalisto.NewClient("")\` |
|
|
40
|
+
| Java | Maven \`com.fiscalisto:fiscalisto\` | \`new FiscalistoClient()\` |
|
|
41
|
+
| C# / .NET | \`dotnet add package Fiscalisto\` | \`new FiscalistoClient()\` |
|
|
42
|
+
|
|
43
|
+
Sin argumento, cada cliente lee \`FISCALISTO_API_KEY\`. El código de cada operación en cada lenguaje:
|
|
44
|
+
\`describe_operation\` del MCP (con \`language\`) o la página \`.md\` de la referencia.
|
|
45
|
+
|
|
46
|
+
## Timbrar una factura
|
|
47
|
+
|
|
48
|
+
\`\`\`ts
|
|
49
|
+
import { Fiscalisto } from "fiscalisto";
|
|
50
|
+
|
|
51
|
+
const fiscalisto = new Fiscalisto(); // FISCALISTO_API_KEY
|
|
52
|
+
|
|
53
|
+
const invoice = await fiscalisto.invoices.create(
|
|
54
|
+
{
|
|
55
|
+
customer: { tax_id: "ICV060329BY0", legal_name: "INMOBILIARIA CVA", tax_system: "601", zip: "33826" },
|
|
56
|
+
payment_form: "03", // transferencia
|
|
57
|
+
items: [{ description: "Mensualidad", product_key: "86121700", quantity: 2, unit_price: 2500 }],
|
|
58
|
+
},
|
|
59
|
+
{ idempotencyKey: \`pedido-\${order.id}\` },
|
|
60
|
+
);
|
|
61
|
+
// Guarde invoice.id (inv_…) y invoice.uuid (el folio fiscal) con su pedido.
|
|
62
|
+
\`\`\`
|
|
63
|
+
|
|
64
|
+
- **Idempotency-Key = el id de su pedido.** Si la respuesta se pierde, repetir con la misma nunca
|
|
65
|
+
timbra dos veces. No use una al azar en cada intento.
|
|
66
|
+
- **El cliente (Receptor) va exactamente como en su constancia de situación fiscal:** RFC
|
|
67
|
+
(\`tax_id\`), nombre sin régimen de capital (sin «S.A. de C.V.»), régimen (\`tax_system\`, c_RegimenFiscal)
|
|
68
|
+
y código postal (\`zip\`). Si su app no tiene esos datos, pídalos con una liga
|
|
69
|
+
(\`POST /v1/customer_data_requests\`) o revíselos con \`POST /v1/tax_ids/validate\`; guarde clientes
|
|
70
|
+
frecuentes con \`/v1/customers\` y mande su \`cus_…\`.
|
|
71
|
+
- Lo que omite toma el valor usual: PUE, MXN, uso G03 (S01 con régimen 616), objeto de impuesto 02,
|
|
72
|
+
IVA 16 %, cantidad 1, unidad E48. \`unit_price\` es sin IVA, en pesos.
|
|
73
|
+
- **Claves del SAT:** no las invente. Búsquelas en los catálogos (\`/v1/sat_catalogs/{name}\`, por ejemplo
|
|
74
|
+
\`product_keys\`) o guarde productos (\`/v1/products\`, \`prd_…\`) con su clave.
|
|
75
|
+
- **La respuesta** trae \`status: "valid"\` con UUID, PDF y XML. Si el PAC tarda llega
|
|
76
|
+
\`processing\`: no repita con otra llave de idempotencia; espere el webhook \`invoice.stamped\`
|
|
77
|
+
(o \`invoice.failed\`).
|
|
78
|
+
- **PDF y XML:** \`invoices.pdf(id)\`, \`invoices.xml(id)\`; \`invoices.send(id)\` lo manda por correo.
|
|
79
|
+
- **A crédito (PPD):** \`payment_method: "PPD"\`, \`payment_form: "99"\`; cada cobro lleva su
|
|
80
|
+
complemento de pago (\`POST /v1/payments\`) a más tardar el día 5 del mes siguiente.
|
|
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\`).
|
|
84
|
+
|
|
85
|
+
## Errores
|
|
86
|
+
|
|
87
|
+
Cada error trae \`error.type\`, \`error.code\`, \`error.message\` (en español) y \`error.param\` (el
|
|
88
|
+
campo a corregir). Un rechazo del SAT llega como \`invoice_rejected\` con su regla en
|
|
89
|
+
\`error.sat_code\` (CFDI40…): muestre el mensaje a la persona y corrija el dato; no reintente igual.
|
|
90
|
+
El SDK solo reintenta lo que es seguro repetir. \`explain_error\` del MCP dice qué hacer con cada
|
|
91
|
+
código; la lista completa está en ${DOCS}/errores.md.
|
|
92
|
+
|
|
93
|
+
## Webhooks
|
|
94
|
+
|
|
95
|
+
Lo que pasa después (timbrado tardío, cancelación aceptada días después, lotes) llega a su endpoint
|
|
96
|
+
como evento firmado. Créelo en **Desarrolladores › Webhooks** o con \`POST /v1/webhook_endpoints\`
|
|
97
|
+
y guarde su secreto \`whsec_…\` en \`FISCALISTO_WEBHOOK_SECRET\`.
|
|
98
|
+
|
|
99
|
+
\`\`\`ts
|
|
100
|
+
import { FiscalistoWebhookError, verifyWebhook } from "fiscalisto";
|
|
101
|
+
|
|
102
|
+
export async function POST(request: Request) {
|
|
103
|
+
try {
|
|
104
|
+
// El cuerpo tal como llegó (texto), sin interpretarlo antes.
|
|
105
|
+
const event = await verifyWebhook(await request.text(), request.headers, process.env.FISCALISTO_WEBHOOK_SECRET!);
|
|
106
|
+
if (event.type === "invoice.stamped") await marcarFacturado(event.data.object);
|
|
107
|
+
return new Response(null, { status: 200 });
|
|
108
|
+
} catch (error) {
|
|
109
|
+
if (error instanceof FiscalistoWebhookError) return new Response(null, { status: 400 });
|
|
110
|
+
throw error;
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
\`\`\`
|
|
114
|
+
|
|
115
|
+
Conteste 2xx rápido y procese aparte; un evento puede llegar más de una vez: ignore el \`evt_…\` que
|
|
116
|
+
ya procesó. En desarrollo, \`npx fiscalisto listen --forward-to http://localhost:3000/webhooks\` le
|
|
117
|
+
reenvía los eventos de pruebas y \`npx fiscalisto trigger invoice.stamped\` provoca uno.
|
|
118
|
+
|
|
119
|
+
## Cancelar
|
|
120
|
+
|
|
121
|
+
\`invoices.cancel(id, { motive: "02" })\`: 02 con errores y sin sustituir (el usual), 01 con errores y sustituida
|
|
122
|
+
(\`substitution: "inv_…"\`, o \`invoices.substitute\` timbra la nueva y cancela la anterior), 03 no
|
|
123
|
+
se llevó a cabo y 04 solo en una factura global (una venta se facturó después a nombre del
|
|
124
|
+
cliente). Si el cliente debe aceptar llega
|
|
125
|
+
\`invoice.cancellation_pending\` y después \`invoice.canceled\` o \`invoice.cancellation_rejected\`.
|
|
126
|
+
|
|
127
|
+
## Probar
|
|
128
|
+
|
|
129
|
+
- Las llaves \`fk_test_\` aplican las mismas revisiones del SAT que producción; una cuenta nueva ya
|
|
130
|
+
tiene un emisor de pruebas listo.
|
|
131
|
+
- RFC de prueba que provocan cada rechazo del SAT (por ejemplo \`NOM010101FK9\` → \`CFDI40145\`):
|
|
132
|
+
${DOCS}/pruebas-y-produccion.md#provocar-cada-rechazo-del-sat.
|
|
133
|
+
- \`call_api\` del MCP prueba un cuerpo real con la llave de pruebas antes de escribirlo en código.
|
|
134
|
+
- Pruebas automáticas: \`POST /v1/test_data/reset\` deja el modo de pruebas como nuevo.
|
|
135
|
+
|
|
136
|
+
## Nunca
|
|
137
|
+
|
|
138
|
+
- Poner la llave en el navegador o en una app móvil: la API rechaza el navegador
|
|
139
|
+
(\`browser_not_supported\`). Llame desde su servidor.
|
|
140
|
+
- Usar una \`fk_live_\` para probar: timbra CFDI reales con valor fiscal.
|
|
141
|
+
- Inventar folios, UUID, RFC, regímenes o claves del SAT: consúltelos.
|
|
142
|
+
|
|
143
|
+
## Pasar a producción
|
|
144
|
+
|
|
145
|
+
Emisor real (\`POST /v1/issuers\`), su CSD (\`/certificates\`), la firma con e.firma del contrato
|
|
146
|
+
con el PAC (\`/efirma\`) o, más fácil, una liga para que el dueño lo haga
|
|
147
|
+
(\`POST /v1/issuers/{id}/onboarding_links\`); timbres en **Desarrolladores › Timbres**; y la llave
|
|
148
|
+
\`fk_live_\` en el servidor. Detalle: ${DOCS}/pruebas-y-produccion.md#pasar-a-produccion.
|
|
149
|
+
`;
|
|
150
|
+
/** The guide as an Agent Skill (agentskills.io): SKILL.md with its name and description. */
|
|
151
|
+
export const AGENT_SKILL = `---
|
|
152
|
+
name: fiscalisto
|
|
153
|
+
description: ${JSON.stringify(AGENT_SKILL_DESCRIPTION)}
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
${AGENT_GUIDE}`;
|
package/dist/cli.js
CHANGED
|
@@ -15,6 +15,7 @@ import { homedir, hostname } from "node:os";
|
|
|
15
15
|
import { dirname, join, resolve } from "node:path";
|
|
16
16
|
import { createInterface } from "node:readline/promises";
|
|
17
17
|
import { parseArgs } from "node:util";
|
|
18
|
+
import { AGENT_SKILL } from "./agent-guide.js";
|
|
18
19
|
import { FiscalistoError, VERSION } from "./core.js";
|
|
19
20
|
import { Fiscalisto } from "./index.js";
|
|
20
21
|
import { createMock } from "./mock.js";
|
|
@@ -486,14 +487,18 @@ const AGENTS_SECTION = `
|
|
|
486
487
|
## Facturación (Fiscalisto)
|
|
487
488
|
|
|
488
489
|
Facturas electrónicas (CFDI 4.0) con la API de Fiscalisto. La llave está en \`FISCALISTO_API_KEY\`
|
|
489
|
-
(\`.env\`; \`fk_test_\` timbra en pruebas sin costo).
|
|
490
|
-
|
|
490
|
+
(\`.env\`; \`fk_test_\` timbra en pruebas sin costo). La guía de integración completa está en
|
|
491
|
+
\`.claude/skills/fiscalisto/SKILL.md\` (también en https://fiscalisto.com/docs/api/SKILL.md); el índice de la
|
|
492
|
+
documentación en https://fiscalisto.com/docs/api/llms.txt y el servidor MCP de la documentación, sin llave,
|
|
493
|
+
en https://fiscalisto.com/docs/api/mcp (empiece con get_started).
|
|
491
494
|
|
|
492
495
|
- Use el SDK \`fiscalisto\` (npm, PyPI, Packagist, Go, Maven, NuGet). Cada timbrado lleva una Idempotency-Key
|
|
493
496
|
(el id del pedido): repetirla nunca timbra dos veces.
|
|
494
497
|
- El cliente va con su RFC, nombre, régimen y código postal exactamente como en su constancia.
|
|
498
|
+
- Llame a la API solo desde el servidor; verifique cada webhook con \`verifyWebhook\` y su secreto \`whsec_\`.
|
|
495
499
|
- Para probar rechazos del SAT use los RFC de prueba (NOM010101FK9 y otros, ver "Pruebas y producción").
|
|
496
|
-
- El CLI hace todo desde la terminal: \`npx fiscalisto --help\`
|
|
500
|
+
- Sin internet o sin llave: \`npx fiscalisto mock\`. El CLI hace todo desde la terminal: \`npx fiscalisto --help\`
|
|
501
|
+
(\`--json\` para leerlo).
|
|
497
502
|
`;
|
|
498
503
|
async function init(args, g) {
|
|
499
504
|
const { values } = parseArgs({
|
|
@@ -581,6 +586,12 @@ async function init(args, g) {
|
|
|
581
586
|
await appendFile(agentsPath, AGENTS_SECTION);
|
|
582
587
|
done.push(`${agentsPath.slice(dir.length + 1)}: cómo facturar, para su agente`);
|
|
583
588
|
}
|
|
589
|
+
const skillPath = join(dir, ".claude", "skills", "fiscalisto", "SKILL.md");
|
|
590
|
+
if (!existsSync(skillPath)) {
|
|
591
|
+
await mkdir(dirname(skillPath), { recursive: true });
|
|
592
|
+
await writeFile(skillPath, AGENT_SKILL);
|
|
593
|
+
done.push(".claude/skills/fiscalisto/SKILL.md: la guía completa, para su agente");
|
|
594
|
+
}
|
|
584
595
|
}
|
|
585
596
|
print({ lang, dir, done, run: example.run }, () => {
|
|
586
597
|
line(`${green("✓")} Listo para facturar (${lang}):`);
|
|
@@ -1269,7 +1280,7 @@ const HELP = `${bold("fiscalisto")} ${dim(VERSION)} · facturación electrónica
|
|
|
1269
1280
|
|
|
1270
1281
|
${bold("Empezar")}
|
|
1271
1282
|
login [--live] [--key fk_…] Inicia sesión por el navegador y guarda su llave de pruebas
|
|
1272
|
-
init [--lang node|python|php|go|dotnet|java] Deja el SDK, la llave en .env y un ejemplo en su proyecto (--agents: AGENTS.md)
|
|
1283
|
+
init [--lang node|python|php|go|dotnet|java] Deja el SDK, la llave en .env y un ejemplo en su proyecto (--agents: AGENTS.md y la guía para su agente)
|
|
1273
1284
|
whoami Cuenta, modo, timbres y emisores
|
|
1274
1285
|
logout Olvida las llaves en esta computadora
|
|
1275
1286
|
|
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.
|
|
7
|
+
export declare const VERSION = "0.1.6";
|
|
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.
|
|
6
|
+
export const VERSION = "0.1.6";
|
|
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.
|
package/dist/error-codes.d.ts
CHANGED
|
@@ -11,6 +11,10 @@ export declare const ErrorCode: {
|
|
|
11
11
|
readonly BatchInvalid: "batch_invalid";
|
|
12
12
|
/** El cuerpo pasa de 10 MB. Divida el trabajo en varios lotes. */
|
|
13
13
|
readonly BodyTooLarge: "body_too_large";
|
|
14
|
+
/** El emisor ya tiene una sucursal con ese código postal (cada una lleva el suyo); el mensaje dice cuál. Si está archivada, restáurela con archived: false. */
|
|
15
|
+
readonly BranchExists: "branch_exists";
|
|
16
|
+
/** La sucursal ya facturó, así que no se borra: archívela con archived: true y sus facturas la siguen nombrando. */
|
|
17
|
+
readonly BranchHasInvoices: "branch_has_invoices";
|
|
14
18
|
/** La API se llama desde su servidor, nunca desde el navegador: la llave secreta quedaría expuesta. */
|
|
15
19
|
readonly BrowserNotSupported: "browser_not_supported";
|
|
16
20
|
/** El SAT no aceptó la solicitud de cancelación; message dice por qué. */
|
|
@@ -59,6 +63,8 @@ export declare const ErrorCode: {
|
|
|
59
63
|
readonly InvalidJson: "invalid_json";
|
|
60
64
|
/** La respuesta no se pudo leer (api_error): no es el JSON de la API, sino la página de un proxy o de un portal de la red. status dice qué contestó. */
|
|
61
65
|
readonly InvalidResponse: "invalid_response";
|
|
66
|
+
/** Inventario no lo permite: el mensaje dice por qué (un lote que no es de ese producto, otro ajuste del mismo almacén en curso). */
|
|
67
|
+
readonly InventoryRefused: "inventory_refused";
|
|
62
68
|
/** La factura no cumple una regla del SAT que Fiscalisto revisa antes de mandarla al PAC (uso contra régimen, totales, complementos…). No se usó ningún timbre. */
|
|
63
69
|
readonly InvoiceInvalid: "invoice_invalid";
|
|
64
70
|
/** Solo una factura de ingreso PUE vigente se marca pagada o por cobrar; una PPD se paga con su complemento de pago (type P). */
|
package/dist/error-codes.js
CHANGED
|
@@ -12,6 +12,10 @@ export const ErrorCode = {
|
|
|
12
12
|
BatchInvalid: "batch_invalid",
|
|
13
13
|
/** El cuerpo pasa de 10 MB. Divida el trabajo en varios lotes. */
|
|
14
14
|
BodyTooLarge: "body_too_large",
|
|
15
|
+
/** El emisor ya tiene una sucursal con ese código postal (cada una lleva el suyo); el mensaje dice cuál. Si está archivada, restáurela con archived: false. */
|
|
16
|
+
BranchExists: "branch_exists",
|
|
17
|
+
/** La sucursal ya facturó, así que no se borra: archívela con archived: true y sus facturas la siguen nombrando. */
|
|
18
|
+
BranchHasInvoices: "branch_has_invoices",
|
|
15
19
|
/** La API se llama desde su servidor, nunca desde el navegador: la llave secreta quedaría expuesta. */
|
|
16
20
|
BrowserNotSupported: "browser_not_supported",
|
|
17
21
|
/** El SAT no aceptó la solicitud de cancelación; message dice por qué. */
|
|
@@ -60,6 +64,8 @@ export const ErrorCode = {
|
|
|
60
64
|
InvalidJson: "invalid_json",
|
|
61
65
|
/** La respuesta no se pudo leer (api_error): no es el JSON de la API, sino la página de un proxy o de un portal de la red. status dice qué contestó. */
|
|
62
66
|
InvalidResponse: "invalid_response",
|
|
67
|
+
/** Inventario no lo permite: el mensaje dice por qué (un lote que no es de ese producto, otro ajuste del mismo almacén en curso). */
|
|
68
|
+
InventoryRefused: "inventory_refused",
|
|
63
69
|
/** La factura no cumple una regla del SAT que Fiscalisto revisa antes de mandarla al PAC (uso contra régimen, totales, complementos…). No se usó ningún timbre. */
|
|
64
70
|
InvoiceInvalid: "invoice_invalid",
|
|
65
71
|
/** Solo una factura de ingreso PUE vigente se marca pagada o por cobrar; una PPD se paga con su complemento de pago (type P). */
|