Metas de la semana

• [x] Una guía de integración que lleve de cero a cobrar en testnet
• [x] Una referencia de la API con cada función pública de los cinco paquetes
• [x] Alguien de fuera del proyecto la sigue desde cero, solo con lo escrito
• [x] Corregir en la guía cada lugar donde esa corrida se trabó

Resumen

Qué es Local402. Local402 permite cobrar por una API en la moneda local, con x402 en Stellar. x402 es un estándar abierto para pagar por HTTP: la API responde "402 Payment Required" con el precio, y el cliente (una persona o un agente de IA) paga y repite la petición. El vendedor pone el precio en cualquiera de 24 monedas o en UF; quien paga usa USDC, XLM o EURC en una sola transacción y el vendedor recibe el monto exacto en USDC.

Esta semana. Hasta ahora, para integrar Local402 estaba el quickstart del README y poco más. Desde esta semana hay una guía de integración que lleva de cero a cobrar en testnet en 10 pasos, y una referencia de la API con cada función pública de los cinco paquetes de npm. Para comprobar que la guía sirve, Pau Koh, de la comunidad de Stellar Chile y fuera del proyecto, la siguió desde cero en su Mac, solo con lo escrito: llegó al final de los 10 pasos al primer intento, en unos 8 minutos. Encontró 10 cosas que mejorar, y todas quedaron corregidas en la guía.

Changelog

Agregado

• docs/integration-guide.md, la guía de integración, en 10 pasos:
  1. Levantar un facilitador (el servicio que revisa el pago, lo envía a la red y paga la comisión).
  2. Crear el proyecto del vendedor.
  3. Crear dos cuentas de testnet, una que cobra y otra que paga.
  4. Ponerle precio en pesos chilenos a una ruta de la API.
  5. Leer el 402: qué responde la API cuando nadie ha pagado.
  6. Pagarlo con USDC o con XLM. Con XLM, el contrato FxPay cambia el XLM a USDC en Soroswap (un exchange de Stellar) dentro de la misma transacción, y el vendedor recibe el USDC exacto.
  7. Las guardas del cliente: frenan un pago si el precio pasa del máximo que puso quien paga.
  8. Los recibos de cada venta, exportados a un CSV.
  9. La misma ruta en otra moneda, como la UF.
  10. Qué cambia para pasar a mainnet (la red con dinero real).
• Al final de la guía, una tabla "When a step fails" con los errores más comunes y qué hacer con cada uno.
• docs/api-reference.md: cada función pública de local402-server, local402-client, local402-pricing, local402-fx y local402-facilitator, con sus parámetros y lo que devuelve. Los códigos de error siguen en su propia página, docs/errors.md.
• Los dos README (inglés y español) enlazan la guía y la referencia.

Corregido

La corrida de Pau está en el issue #3, con capturas de cada paso. Sus 10 hallazgos (7 detalles y 3 cosas que confundían) quedaron corregidos en la guía en el commit 1395f3c:

• Paso 2: las instalaciones van con versión exacta (--save-exact), y la guía explica los avisos de seguridad de npm, que vienen de dependencias de terceros fijadas en una versión.
• Paso 3: quien paga queda con unos 9.999 XLM, no 10.000, porque compra 1 USDC al crearse.
• Paso 4: el precio y la URL del explorador quedan en constantes, que se reusan en los pasos 9 y 10.