Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Skill para asistentes de IA

Descarga el skill de Ecuafact para que Claude Code, Copilot, Cursor u otro agente conozca la API y genere integraciones correctas.

Si programas con un asistente de IA, puedes darle el conocimiento de nuestra API con nuestro skill, para que escriba la integración contigo sin inventar campos ni códigos. El skill es un paquete de archivos markdown con lo que el asistente necesita saber, desde la autenticación hasta los campos de cada tipo de comprobante.

En esta página descargas el skill, lo instalas en la carpeta de tu asistente y compruebas que lo está usando. Al final verás cómo mantenerlo al día cuando cambia el contrato.

Conceptos#

Un skill es una carpeta con un archivo SKILL.md, que contiene las instrucciones y el mapa de recursos, y con archivos de referencia que el asistente lee solo cuando los necesita. Sigue el estándar abierto Agent Skills, así que es markdown portable, no depende de un proveedor de IA y no ejecuta nada por sí mismo.

Las instrucciones del skill están en inglés, que es el idioma en que los asistentes siguen mejor las indicaciones, pero todo lo que forma parte del contrato se mantiene en español, tal como lo recibe la API: nombres de campos, rutas, códigos de error, mensajes y valores de catálogo. El asistente te responde en el idioma en que le escribes, y el código que genera usa los nombres exactos del contrato.

Con el skill, tu asistente aprende cómo se integra la API y te ayuda a escribir el código. Si además necesitas que consulte o emita comprobantes por ti, puedes conectarlo a nuestro servidor MCP, con los permisos que le des al conectarlo.

Requisitos#

  • Un asistente compatible con Agent Skills, como Claude Code, GitHub Copilot, Cursor u otro agente que cargue carpetas con SKILL.md.
  • Opcionalmente, una API Key de pruebas, si quieres que el asistente, además de escribir código, lo ejecute contra el ambiente de pruebas. Si todavía no tienes una, crea un sandbox.

Descarga#

Descargar el paquete (ecuafact.zip)

El .zip contiene directamente SKILL.md y la carpeta reference/, sin una carpeta raíz que los agrupe. Esta tabla muestra qué trae cada archivo y cuándo lo lee el asistente:

Archivo Contenido El asistente lo lee cuando...
SKILL.md Ambientes, autenticación, ciclo de vida, emisión, endpoints y mapa de recursos. Siempre que el skill se activa.
reference/codigos-sri.md Tipos de identificación, IVA, formas de pago y retenciones. Necesita un código exacto del SRI.
reference/emision/factura-01.md Campos y ejemplo de la factura. Emites o validas una factura (01).
reference/emision/liquidacion-03.md Campos y ejemplo de la liquidación de compra. Emites una liquidación (03).
reference/emision/nota-credito-04.md Campos y ejemplo de la nota de crédito. Emites una nota de crédito (04).
reference/emision/nota-debito-05.md Campos y ejemplo de la nota de débito. Emites una nota de débito (05).
reference/emision/guia-remision-06.md Campos y ejemplo de la guía de remisión. Emites una guía de remisión (06).
reference/emision/retencion-07.md Campos y ejemplo del comprobante de retención. Emites una retención (07).
reference/consultas.md Contexto, operación, cupo, RIDE/XML y perfil. Consultas o descargas algo ya emitido.
reference/consultas-sri.md Contribuyente, establecimientos, validar identificación y decodificar clave. Consultas el catastro del SRI.
reference/webhooks.md Eventos y sus estado y codEstado, firma, reintentos y verificación de webhooks. Implementas el receptor de webhooks.
reference/errores-limites.md Catálogo de codEstado con "Qué hacer", límites y soporte. Manejas errores o límites.
reference/herramientas.md SDK, CLI ecuafact, colección de Postman y servidores MCP. Eliges cómo integrarte o usas una de esas herramientas.

Los ejemplos del skill usan los datos de prueba publicados.

Instalación#

El skill también está publicado en GitHub, en Ecuanexus/ecuafact-skill. Si usas la CLI de skills, instálalo con un solo comando:

npx skills add Ecuanexus/ecuafact-skill

Para instalarlo a mano con el .zip, sigue estos pasos:

  1. Descarga ecuafact.zip.
  2. Crea una carpeta llamada ecuafact dentro de la carpeta de skills de tu asistente, que encontrarás en la tabla siguiente.
  3. Descomprime el .zip dentro de ecuafact, de modo que queden ecuafact/SKILL.md y ecuafact/reference/....
  4. Reinicia el asistente o abre una sesión nueva.
Asistente Carpeta del skill
Claude Code (solo este proyecto) .claude/skills/ecuafact/ en la raíz del proyecto
Claude Code (todos tus proyectos) ~/.claude/skills/ecuafact/
GitHub Copilot en VS Code (solo este proyecto) .github/skills/ecuafact/ en la raíz del proyecto
Cursor y otros agentes compatibles con Agent Skills La carpeta de skills que indique la documentación de tu herramienta, con la misma estructura ecuafact/SKILL.md + ecuafact/reference/

En Linux o macOS, estos comandos instalan el skill para Claude Code en el proyecto actual:

mkdir -p .claude/skills/ecuafact
curl -sL https://docs.mynexusapi.com/downloads/v1/skills/ecuafact.zip -o ecuafact.zip
unzip -o ecuafact.zip -d .claude/skills/ecuafact
ls .claude/skills/ecuafact   # debe mostrar SKILL.md y reference

En Windows, estos son los mismos comandos en PowerShell:

New-Item -ItemType Directory -Force .claude\skills\ecuafact | Out-Null
Invoke-WebRequest https://docs.mynexusapi.com/downloads/v1/skills/ecuafact.zip -OutFile ecuafact.zip
Expand-Archive ecuafact.zip -DestinationPath .claude\skills\ecuafact -Force
Get-ChildItem .claude\skills\ecuafact   # debe mostrar SKILL.md y reference

Para otro asistente, cambia .claude/skills/ecuafact por la carpeta que indica la tabla.

Verifica la instalación#

Pregunta al asistente: "Con el skill de ecuafact, ¿qué cabeceras necesito para emitir una factura?". La instalación funcionó si responde X-Api-Key, Idempotency-Key y Content-Type: application/json, y si menciona que la respuesta es 202 Accepted. En Claude Code también puedes comprobar que el skill aparece en la lista de skills disponibles.

Mantenerlo actualizado#

El skill es una copia de la documentación tal como estaba al momento de la descarga. Cuando el changelog registre un cambio de contrato, descarga el paquete de nuevo y reemplaza la carpeta completa. Borra la carpeta anterior antes de descomprimir, para no dejar archivos sobrantes.

Si tu asistente tiene acceso a internet, también puede consultar la documentación vigente sin depender de la copia local:

  • llms.txt: índice de todas las guías con su descripción.
  • llms-full.txt: toda la documentación en un solo archivo.
  • Markdown por guía: agrega .md a la URL (por ejemplo, /v1/guias/emision-01.md) o pide la guía con Accept: text/markdown.

Si el skill y la guía en línea difieren, la guía en línea es la vigente.

Siguientes pasos#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.