La API de Arcalotl

• Una URL base, con alcance por comunidad

  Todos los recursos viven bajo https://api.arcalotl.com/v1. Cada recurso está limitado a la comunidad propietaria de la clave de API usada para llamarlo. Un id que pertenece a otra comunidad responde 404 en lugar de 403, así que las respuestas no pueden usarse para sondear los datos de otra comunidad.

• Claves de API bearer con permisos explícitos

  Cada solicitud lleva una cabecera Authorization con una clave bearer creada en el panel, en Desarrolladores y luego Claves de API. Una clave contiene los permisos elegidos al crearla, y una solicitud sin el permiso que exige una ruta devuelve 403 con el código missing_scope. La clave completa se muestra exactamente una vez al crearla; después solo se guarda un prefijo visible.

• Las lecturas cubren toda la facturación

  Los endpoints GET devuelven suscripciones con filtros de estado, plan y nivel, niveles de plan con sus planes de facturación anidados, miembros con sus identidades de plataforma, los derechos de acceso resueltos de un miembro, compras únicas, códigos de descuento con recuento de canjes y un resumen de analíticas con MRR, suscriptores activos y altas y cancelaciones recientes.

• Las escrituras son pocas y deliberadas

  Las escrituras cubren todo el ciclo de vida de la suscripción: crear un enlace de pago para un comprador concreto, cambiar una suscripción de plan, cancelarla al final del periodo o reactivarla, abrir el portal de miembros para un miembro, asociar tu propio id de usuario a un miembro y gestionar endpoints de webhook. Los enlaces de pago aceptan una identidad de plataforma conectada, un id de miembro existente o un id de usuario externo con espacio de nombres que te pertenece, que es como una aplicación controlada por el operador vende a través de Arcalotl.

• La paginación se basa en cursores

  Los endpoints de listado reciben un cursor opaco y un límite, con un máximo de 100 y un valor predeterminado de 25, y devuelven un next_cursor. El campo es null o no aparece en la última página. Devuelve el valor tal cual; la forma interna de un cursor no forma parte del contrato, así que no construyas ni analices uno.

• Las claves de idempotencia hacen seguros los reintentos

  Las solicitudes de cancelación y de enlace de pago aceptan una cabecera Idempotency-Key. La misma clave con el mismo cuerpo dentro de 24 horas repite la respuesta original y añade Idempotent-Replayed: true. La misma clave con un cuerpo distinto devuelve 422 idempotency_key_reuse, y reutilizarla mientras la primera solicitud sigue en curso devuelve 409 request_in_flight. Genera una clave nueva por operación lógica.

• Los errores son documentos problem según RFC 9457

  Los fallos devuelven application/problem+json con un miembro code estable, por ejemplo unauthorized, missing_scope, not_found, invalid_request, conflict, not_eligible o rate_limited. Compara con code. Los campos title y detail son legibles por personas y su redacción puede cambiar sin aviso.

• Los límites de tasa se publican en cada respuesta

  El tráfico autenticado se limita por clave a 300 solicitudes por minuto con una ráfaga de 60. Las solicitudes con clave ausente o inválida se limitan por IP de cliente a 20 por minuto con una ráfaga de 10, y no afectan a las llamadas autenticadas correctamente. Cada respuesta lleva RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset, y un 429 añade Retry-After en segundos.

• Los webhooks siguen la especificación Standard Webhooks

  Cada entrega lleva las cabeceras webhook-id, webhook-timestamp y webhook-signature. La firma es HMAC-SHA256 sobre el id, la marca de tiempo y el cuerpo sin procesar unidos por puntos, con la parte decodificada de tu secreto whsec_ como clave. Verifica contra el cuerpo sin procesar antes de analizar el JSON, acepta cualquiera de los tokens v1 separados por espacios para que la rotación de secretos funcione, y rechaza una marca de tiempo a más de cinco minutos de tu reloj.

• La entrega es al menos una vez, con reintentos y desactivación automática

  Cualquier 2xx cuenta como éxito. Cualquier otra cosa se reintenta según un calendario fijo de unos diez intentos repartidos en unos 2,3 días antes de marcar la entrega como agotada. Un endpoint con diez entregas agotadas consecutivas se desactiva automáticamente, y cualquier éxito reinicia ese contador. Una comunidad puede registrar hasta cinco endpoints HTTPS, inspeccionar el registro de intentos y volver a encolar una entrega concreta.

• El feed de eventos cubre lo que los webhooks se pierden

  GET /v1/events devuelve los mismos sobres que reciben tus endpoints, los más recientes primero, filtrables por tipo y por after_id para que puedas seguir un punto de control en lugar de una marca de tiempo. Los eventos proyectados se conservan 90 días y los registros de entrega 30, así que puedes reconciliar mucho después de que un registro de entrega haya caducado.

• Los cambios dentro de una versión son solo aditivos

  La API y el sobre de webhook comparten una sola cadena de versión. Dentro de una versión recibes campos nuevos, parámetros opcionales nuevos, tipos de evento nuevos y endpoints nuevos, y los campos existentes no cambian de forma ni de significado. Ignora los campos que no reconozcas y los cambios aditivos nunca romperán tu integración.

• El contrato se publica como OpenAPI 3.1

  El contrato completo de solicitudes y respuestas es un documento OpenAPI 3.1 servido desde el sitio, y las páginas de referencia de la API se generan a partir de ese mismo documento, así que la referencia no puede desviarse de la especificación que lee tu generador de código.

Permisos de las claves de API