Crea tu propia superficie de control

El contrato propuesto de versión uno separa los recursos del catálogo de los recursos de la cuenta. Las ubicaciones y los planes admiten la configuración. Los servicios representan configuraciones aceptadas y el estado de cumplimiento. La facturación contiene facturas y el estado de pago. Los tickets admiten una conversación de soporte rastreable. El sitio web implementa sus propios formularios y espacio de trabajo; los ejemplos a continuación son un contrato de diseño, no rutas a un API público.

El modelo de autenticación preparado usa un token Bearer en el encabezado Authorization. Los ámbitos de catálogo o servicio de solo lectura no deberían poder crear, reconstruir ni cancelar un servicio. Los ámbitos de escritura necesitan una decisión distinta y una ruta de revocación. Mantenga las credenciales en un entorno de servidor privado y nunca incruste un token secreto en una página ni en un paquete del navegador.

GET /v1/services
Authorization: Bearer <private-token>
Accept: application/json

# Proposed scope: services:read

Utilice un identificador estable para cada recurso y un ID de solicitud para soporte. Las llamadas que modifican datos deberían aceptar una clave de idempotencia para que un reintento pueda conciliarse en lugar de crear otro pedido.

POST /v1/services
Idempotency-Key: <one-key-per-request>

{
  "plan_id": "umbra-1",
  "location": "iceland",
  "billing_cycle": "monthly",
  "image": "Ubuntu"
}

Los límites de tasa propuestos a nivel de cuenta son 60 lecturas por minuto y 20 escrituras por minuto, con una tolerancia de ráfaga del doble de esos valores. Una solicitud rechazada devuelve HTTP 429 con Retry-After; la automatización debe esperar según lo indicado y aplicar retroceso. Los errores deben incluir un código estable, un mensaje legible por humanos y un request_id, con los detalles sensibles eliminados.

{
  "error": {
    "code": "unsupported_location",
    "message": "This plan is not listed in that region.",
    "request_id": "req_example"
  }
}

El modelo de webhook preparado cubre el pago de facturas, la preparación del servicio, la suspensión y las actualizaciones de tickets. La entrega debe tener un ID de evento y una marca de tiempo, con una firma HMAC-SHA256 verificada sobre el cuerpo de la solicitud original usando un secreto de firma privado. Rechace las firmas obsoletas o no válidas, deduplique los ID de evento y confirme solo después de que el evento se haya aceptado de forma duradera. Los consumidores deben tolerar entregas desordenadas y repetidas.

La ruta propuesta de API incluye su versión principal. Los cambios aditivos deben preservar los clientes existentes; los cambios incompatibles necesitan una nueva versión y un aviso de retirada de seis meses para la antigua. La disponibilidad, los SDK y un host de producción de API deben publicarse solo después de la revisión de integración y seguridad.

La aplicación de cuenta tiene solicitudes de pago con dirección fija y cotizaciones de servidor USD con caducidad. La observación de transacciones es una integración de confianza solo del servidor; no hay endpoint público de confirmación, monitor de blockchain conectado ni worker de aprovisionamiento. El sondeo del navegador lee el estado de pago existente del cliente con sesión iniciada y no puede atestiguar una transacción. El API público ilustrativo y el contrato de webhook anteriores siguen siendo trabajo de diseño futuro.

• Proteger la tasa y la lógica de observación en el servidor.
• Asocia los destinos de recepción reutilizados con una transacción verificada y una referencia de pedido explícita.
• Mantén lo pagado y lo aprovisionado separados; una transacción verificada no debe crear hardware ficticio.