# Fiscalisto para agentes de IA

> Pídale a su agente de código «agrega facturación con Fiscalisto a mi app»: conecte la documentación como servidor MCP, dele la guía en una página y deje que pruebe en modo de pruebas antes de escribir el código.

Claude Code, Cursor, Codex, Copilot y los demás agentes de código pueden integrar Fiscalisto solos si leen lo correcto. Esta página dice cómo darles la documentación, la guía de integración y una forma de probar, para que el código salga bien a la primera: con el SDK oficial, una `Idempotency-Key` por comprobante, los datos del cliente como el SAT los pide y los webhooks verificados.

## Lo más rápido

En la carpeta de su proyecto:

```bash
npx fiscalisto login           # su llave de pruebas, por el navegador
npx fiscalisto init --agents   # SDK, llave en .env, AGENTS.md y la guía para su agente
```

`--agents` agrega a su `AGENTS.md` (o `CLAUDE.md`) una sección de cómo facturar y deja la guía completa en `.claude/skills/fiscalisto/SKILL.md`, que Claude Code y otros agentes leen solos cuando la tarea es facturar. Después pídale a su agente, por ejemplo: «Agrega facturación con Fiscalisto: cuando un pedido se pague, timbra su factura y mándasela al cliente».

## Conectar la documentación (MCP)

El servidor MCP de esta documentación no pide llave ni cuenta. Su agente busca y lee las guías, describe cada ruta con el código de su lenguaje y prueba solicitudes en modo de pruebas mientras programa.

- **Cursor**: [instalar con un clic](cursor://anysphere.cursor-deeplink/mcp/install?name=fiscalisto-docs&config=eyJ1cmwiOiJodHRwczovL2Zpc2NhbGlzdG8uY29tL2RvY3MvYXBpL21jcCJ9).
- **VS Code**: [instalar con un clic](https://vscode.dev/redirect/mcp/install?name=fiscalisto-docs&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Ffiscalisto.com%2Fdocs%2Fapi%2Fmcp%22%7D).
- **Claude Code**: `claude mcp add --transport http fiscalisto-docs https://fiscalisto.com/docs/api/mcp`
- **Codex**: `codex mcp add fiscalisto-docs --url https://fiscalisto.com/docs/api/mcp`
- **Claude** (web y escritorio): en [Personalizar › Conectores](https://claude.ai/customize/connectors) › Agregar conector personalizado, con la dirección `https://fiscalisto.com/docs/api/mcp`.
- **Otro cliente**: la dirección `https://fiscalisto.com/docs/api/mcp` como servidor MCP de tipo HTTP.

### A mano, en cada agente

La dirección es `https://fiscalisto.com/docs/api/mcp` (MCP por HTTP, sin llave).

#### Cursor

**Instalar** abre Cursor y agrega el servidor. A mano, en `.cursor/mcp.json` de su proyecto (o `~/.cursor/mcp.json` para todos):

```json
{
  "mcpServers": {
    "fiscalisto-docs": { "url": "https://fiscalisto.com/docs/api/mcp" }
  }
}
```

#### VS Code

**Instalar** abre VS Code y agrega el servidor para Copilot. A mano, en `.vscode/mcp.json`:

```json
{
  "servers": {
    "fiscalisto-docs": { "type": "http", "url": "https://fiscalisto.com/docs/api/mcp" }
  }
}
```

#### Claude Code

```bash
claude mcp add --transport http fiscalisto-docs https://fiscalisto.com/docs/api/mcp
```

Con `--scope project` queda en el `.mcp.json` del proyecto, para todo su equipo.

#### Codex

```bash
codex mcp add fiscalisto-docs --url https://fiscalisto.com/docs/api/mcp
```

El CLI, la extensión de Codex y la app de ChatGPT para escritorio comparten esta configuración.

#### Claude (web y escritorio)

En [Personalizar › Conectores](https://claude.ai/customize/connectors), **Agregar conector personalizado** con la dirección `https://fiscalisto.com/docs/api/mcp`.

#### Otro cliente

Agregue la dirección como servidor MCP de tipo HTTP (streamable HTTP).

### Sus herramientas

| Herramienta | Qué hace |
| --- | --- |
| `get_started` | La guía de integración completa en una página. Su agente la pide primero. |
| `search_docs` | Busca en las guías y la referencia, en español o en inglés. |
| `get_page`, `list_pages` | Lee una página completa o las lista todas. |
| `list_operations` | Cada operación con su `operationId`, método y ruta, por sección. |
| `describe_operation` | Una operación por su `operationId`, su método del SDK (`invoices.create`), «POST /v1/invoices» o en palabras («create invoice»): sus campos y el código con el SDK del `language` que elija. |
| `describe_object` | Los campos de un objeto (`Invoice`, `Event`…) con un ejemplo. |
| `explain_error` | Qué significa un `error.code` y cómo resolverlo. |
| `call_api` | Prueba una solicitud de verdad en modo de pruebas con su llave `fk_test_` y devuelve el código, el `Request-Id` y el JSON. Nunca acepta una `fk_live_`. |

Las solicitudes de `call_api` quedan en **Desarrolladores › Solicitudes** con la llave que usó.

## La guía en una página

[`/docs/api/SKILL.md`](https://fiscalisto.com/docs/api/SKILL.md) es todo lo que un agente necesita para integrar Fiscalisto: la llave, el SDK de cada lenguaje, timbrar con `Idempotency-Key`, los datos del cliente, los rechazos del SAT, los webhooks firmados, cancelar, probar y pasar a producción. Es una [Agent Skill](https://agentskills.io): guárdela en `.claude/skills/fiscalisto/SKILL.md` de su proyecto (lo hace `npx fiscalisto init --agents`) y su agente la usa cuando la tarea es facturar. Es el mismo texto que devuelve `get_started`.

## La documentación como texto

- [`/docs/api/llms.txt`](https://fiscalisto.com/docs/api/llms.txt): el índice de todas las páginas ([llmstxt.org](https://llmstxt.org)).
- Cada página existe en Markdown: agregue `.md` a su dirección (por ejemplo [`/docs/api/webhooks.md`](https://fiscalisto.com/docs/api/webhooks.md)), o pídala con `Accept: text/markdown`. Cada página tiene además **Copiar como Markdown**, **Abrir en ChatGPT** y **Abrir en Claude** arriba del título.
- [`/docs/api/llms-full.txt`](https://fiscalisto.com/docs/api/llms-full.txt): todas las guías y la referencia en un archivo, con los ejemplos de cURL y TypeScript.
- El documento OpenAPI 3.1 completo, sin llave: [`https://api.fiscalisto.com/v1/openapi.json`](https://api.fiscalisto.com/v1/openapi.json).
- `npx fiscalisto docs` imprime el índice en la terminal.

## Probar sin llave y con llave

- **Sin llave:** `npx fiscalisto mock` levanta la API en `http://127.0.0.1:12111`, sin internet, para que su agente escriba y corra pruebas desde el primer minuto. Contesta como la API pero no revisa las reglas del SAT. Vea [CLI](https://fiscalisto.com/docs/api/cli).
- **Con su llave de pruebas:** `call_api` del MCP, o el CLI con `--json` (`npx fiscalisto invoices create --example --json`), timbran en el ambiente de pruebas del SAT sin costo. Los [RFC de prueba](https://fiscalisto.com/docs/api/pruebas-y-produccion#provocar-cada-rechazo-del-sat) provocan cada rechazo del SAT para que su agente maneje los errores.

> **Su llave.** Dele a su agente solo la llave de pruebas (`fk_test_`) y guárdela en `.env`, nunca en el código. La de producción la pone usted en su servidor cuando todo funcione.