Ir al contenido
Quiet Social

Límites y convenciones

Esta documentación está traducida del francés. Si ambas versiones difieren, prevalece la versión francesa.

Lo que la API limita, y las convenciones que sigue en todas sus rutas: frecuencia, paginación, identificadores, fechas y cuotas.

Límites de frecuencia

Dos límites, que no miden lo mismo:

Límite Por defecto Cuenta
Por dirección IP 300 peticiones por minuto Todas las peticiones, incluidas las que fallan en la autenticación.
Por cliente de API 120 peticiones por minuto Las peticiones autenticadas de este cliente, sea cual sea la dirección desde la que salen.

El primero protege de un barrido de identificadores, que no pertenece a ningún cliente; el segundo, de una integración que se desboca.

Una respuesta autenticada lleva las cabeceras del límite del cliente:

Cabecera Significado
X-RateLimit-Limit El número de peticiones permitidas por minuto.
X-RateLimit-Remaining Las que quedan en el minuto en curso.

Por encima de uno u otro, la API responde 429:

{
  "error": {
    "code": "too_many_requests",
    "message": "Too many requests. Retry after the delay given by the Retry-After header."
  }
}

La respuesta lleva entonces Retry-After (en segundos), X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (marca de tiempo Unix de la puesta a cero) del límite alcanzado. Espera el plazo de Retry-After antes de continuar, y vigila X-RateLimit-Remaining en las respuestas correctas para ir más despacio antes de que te detengan. Una petición rechazada por el límite del cliente no se cuenta en el consumo del espacio.

La notificación de control de un webhook tiene su propio límite: 5 por minuto y por endpoint (consulta Webhooks).

Paginación

GET /destinations, GET /publications y GET /media están paginadas. per_page vale 25 por defecto y está acotado entre 1 y 100. GET /brands y GET /webhooks devuelven la lista completa.

Las tres listas paginadas aceptan también brand_id: un cliente que cubre todo el espacio de trabajo lee en ellas una sola marca. Una marca fuera del alcance del cliente devuelve una lista vacía, sin error.

Una respuesta paginada lleva tres claves: data, links y meta.

{
  "data": ["…"],
  "links": {
    "first": "https://quietsocial.dev/api/v1/publications?page=1",
    "last": "https://quietsocial.dev/api/v1/publications?page=3",
    "prev": null,
    "next": "https://quietsocial.dev/api/v1/publications?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "links": ["…"],
    "path": "https://quietsocial.dev/api/v1/publications",
    "per_page": 25,
    "to": 25,
    "total": 61
  }
}

Pagina siguiendo links.next hasta que valga null. Los parámetros de la petición — filtros incluidos — se conservan en esos enlaces. meta.links sirve para mostrar una paginación; sus etiquetas no forman parte del contrato.

Identificadores

La API nunca expone un número secuencial: se podría adivinar, y permitiría sondear los recursos de otro espacio. Cada recurso lleva un identificador público, con prefijo e inmutable:

Prefijo Recurso
qsc_ Cliente de API
brd_ Marca
dst_ Destino
pub_ Publicación
med_ Medio
whe_ Endpoint de webhook
whd_ Entrega de webhook

Tras el prefijo viene una secuencia de caracteres en minúsculas (pub_01k4b8y5t2v9h6p8w0y2z4b6c8). Trata el identificador como una cadena opaca, y no deduzcas nada de él.

Fechas y zonas horarias

Las fechas devueltas están en ISO 8601 con su desfase, en UTC. Las fechas enviadas deben seguir ISO 8601 y pueden llevar cualquier desfase: 2026-10-02T08:00:00+02:00 y 2026-10-02T06:00:00Z designan el mismo instante. Sin desfase, la hora se lee en UTC; cualquier otra forma se rechaza con 422.

timezone (zona horaria IANA, Europe/Paris) acompaña a una publicación; por defecto es la de la marca.

Cuotas

Una marca puede tener dos topes mensuales, legibles en GET /brands:

  • monthly_publication_limit — publicaciones creadas en el mes. Por encima, la creación responde 422 publication_not_publishable.
  • monthly_delivery_limit — entregas con éxito en una red en el mes. Se comprueba cuando una publicación retenida se libera con publish: 409 transition_not_allowed si los objetivos que liberar superan lo que queda.

null significa «sin tope». Los contadores vuelven a cero el día 1 de cada mes, a medianoche UTC.

Lo que la API no hace

  • No crea conexiones, destinos ni marcas: eso se hace en el panel.
  • No valida una publicación sometida a validación; solo el equipo lo hace, en el panel.
  • No devuelve direcciones de descarga de los medios.