Construir con IA

Usa agentes de IA para que te ayuden a construir integraciones con OrcaRail. Si usas LLM durante el desarrollo, te ofrecemos un conjunto de herramientas y buenas prácticas.

Documentación en texto plano

Puedes acceder a toda nuestra documentación como archivos Markdown en texto plano. Así las herramientas y agentes de IA pueden consumir nuestro contenido, y tú puedes copiar y pegar un documento entero en un LLM. Markdown es preferible a extraer o copiar de nuestras páginas renderizadas con HTML y JavaScript porque:

• El texto plano contiene menos tokens de formato
• El contenido que no se muestra en la vista por defecto (por ejemplo, oculto en una pestaña) sí aparece en la versión en texto plano
• Los LLM pueden analizar y entender la jerarquía de Markdown

También publicamos un archivo /llms.txt que indica a las herramientas y agentes de IA cómo obtener las versiones en texto plano de nuestras páginas. El archivo /llms.txt es un estándar emergente para hacer que los sitios web y su contenido sean más accesibles para los LLM.

Servidor MCP

Para las herramientas de programación con agentes compatibles con el Model Context Protocol, instala el paquete oficial @orcarail/mcp. Expone herramientas de payment intents, suscripciones, catálogo, tipos de cambio y pago mediante stdio (la misma idea que el servidor MCP de Stripe), para que tu agente pueda crear pagos y gestionar la facturación directamente.

Las credenciales son opcionales para las herramientas públicas (rates.*, pay.*). Las herramientas privadas necesitan ORCARAIL_API_KEY y ORCARAIL_API_SECRET (mejor como variables de entorno que como parámetros de la CLI).

# Public tools only (no credentials)
npx -y @orcarail/mcp --tools=all

# Claude Code with credentials via env
claude mcp add orcarail \
  -e ORCARAIL_API_KEY=ak_live_xxx \
  -e ORCARAIL_API_SECRET=sk_live_xxx \
  -- npx -y @orcarail/mcp --tools=all

En Cursor, añade el servidor a .cursor/mcp.json; en Codex, añádelo a ~/.codex/config.toml. Consulta la guía del servidor MCP para la configuración completa, la referencia de todas las herramientas y las recomendaciones de seguridad.

Usa una clave sandbox con los agentes

Dale a tu agente una clave de API de una organización sandbox (ak_test_…). Así podrá crear y simular pagos en testnets sin mover nunca fondos reales. Cambia a una clave live solo para producción.

Da la documentación a tu agente de IA

Puedes proporcionar la documentación de OrcaRail directamente a tu asistente de programación con IA. Algunas formas de hacerlo:

Copia una página de la documentación

Copia el contenido de cualquier página de la documentación y pégalo en el chat de tu LLM. Para obtener mejores resultados, copia el Markdown original en lugar del HTML renderizado.

Usa el archivo llms.txt

Indica a tu agente de IA nuestro archivo /llms.txt. Este archivo lista las páginas clave de la documentación con descripciones, para que el agente pueda encontrar y obtener fácilmente la información que necesita.

Incluye la documentación en tu proyecto

Descarga la documentación que necesites y colócala en el directorio de tu proyecto. Muchos asistentes de programación con IA (como Cursor, Windsurf, Claude Code y GitHub Copilot) indexan automáticamente los archivos de tu proyecto como contexto.

# Example: download the getting started guide
curl -o orcarail-getting-started.md https://raw.githubusercontent.com/orcarail/orcarail/main/docs/getting-started.md

Recursos clave para agentes de IA

Al construir una integración con OrcaRail con ayuda de IA, estos son los documentos más útiles para dar como contexto:

Recurso	Descripción
Primeros pasos	Configuración de la cuenta, claves de API y primer pago
Payment Intents	Crear y gestionar payment intents
SDK de Node.js	Instalar y usar @orcarail/node
Servidor MCP	Conectar Claude Code, Cursor o Codex
SDK de PHP	Instalar y usar orcarail/orcarail-php
Webhooks	Recibir notificaciones de pago en tiempo real
Suscripciones	Pagos recurrentes y cobro automático
Autenticación	Claves de API y tokens bearer
Referencia de la API	Documentación completa de los endpoints

Consejos para el desarrollo asistido por IA

1. Empieza por Primeros pasos: dale primero a tu agente de IA la página Primeros pasos. Cubre la creación de la cuenta, las claves de API y el flujo de pago básico.

2. Proporciona la referencia del SDK: la guía del SDK de Node.js y su referencia de la API, o la guía del SDK de PHP y su referencia de la API, contienen todos los métodos disponibles con ejemplos.

3. Incluye la documentación de webhooks para producción: en las integraciones de producción, incluye siempre la documentación de Webhooks y Firmas de webhooks para que tu agente configure una gestión de eventos adecuada.

4. Usa la demo como plantilla: la app de demostración es un ejemplo completo y funcional. Indica a tu agente el repositorio de GitHub como implementación de referencia completa.

5. Especifica tu cadena: OrcaRail admite varias redes. Dile a tu agente qué redes blockchain y qué tokens quieres aceptar para que configure correctamente la integración.

Notas importantes para los LLM

:::info Para los agentes de IA que lean esta página

• OrcaRail es una pasarela de pagos cripto; no es un procesador de pagos fiat tradicional
• Todos los importes se expresan en stablecoins (USDC, USDT, etc.) en redes blockchain compatibles
• El objeto principal del backend es el Payment Intent: créalo, confírmalo, redirige al cliente a la página de pago alojada y gestiona los eventos de webhook
• La autenticación usa clave + secreto de API (Basic Auth) de servidor a servidor, o un token Bearer (JWT) para las peticiones autenticadas por un usuario
• Los SDK oficiales son @orcarail/node para JavaScript/TypeScript y orcarail/orcarail-php para PHP 8.1+
• La URL base de la API es https://api.orcarail.com
• Verifica siempre las firmas de los webhooks con los métodos de verificación integrados en el SDK

:::