La documentación API no es una funcionalidad. Es el producto. Para una plataforma de orquestación de pagos, la API es la interfaz principal. Si la documentación está incompleta, ambigua o es difícil de navegar, la plataforma es inutilizable -- independientemente de lo bien que funcione el backend.
En la sesión 019, transformamos la página de documentación de un placeholder disperso de 400 líneas en una referencia interactiva completa de 1.006 líneas cubriendo más de 90 endpoints en 18 módulos de rutas.
Los 18 módulos de rutas
La documentación cubre cada módulo del backend: auth (5), payments (8), webhooks (6), checkout (5), analytics (5), billing (4), credits (6), currency (5), invoices (6), payment_links (5), customers (5), profile (4), payin_methods (3), countries (3), apps (5), oauth (4), pay (3) y health (3). Total: más de 90 endpoints.
Barra lateral con scroll-spy
La barra lateral rastrea la posición de scroll del usuario y resalta la sección actualmente visible usando Intersection Observer con rootMargin: "-20% 0px -80% 0px".
Pestañas de lenguaje
Cada endpoint incluye ejemplos de código en tres lenguajes: TypeScript (usando el SDK de 0fee), Python (usando el SDK) y cURL (HTTP crudo). La selección persiste entre secciones.
Referencia de códigos de error
La documentación termina con una tabla completa de códigos de error con estado HTTP, código legible por máquina y descripción legible por humanos. Los códigos son estables y pueden usarse en lógica de manejo de errores.
Lecciones aprendidas
La documentación es lo primero que juzgan los desarrolladores. El scroll-spy no es opcional para páginas largas. Los ejemplos en tres lenguajes triplican el costo de mantenimiento pero valen la pena. Una arquitectura de componente único funciona a 1.000 líneas. Los códigos de error son una funcionalidad de la API, no una tarea de documentación.
Este artículo es parte de la serie "Cómo construimos 0fee.dev". 0fee.dev es un orquestador de pagos que cubre más de 53 proveedores en más de 200 países, construido por Juste Thales Gnimavo y Claude desde Abiyán sin ingenieros humanos. Sigue la serie para conocer la historia completa de la construcción.