Claves y niveles de acceso

Cada petición lleva la clave en el encabezado X-API-Key. Las creas en ByDomu, en Configuración › API y webhooks; la completa se ve una sola vez.

Publicables y secretas

Publicabledomu_pk_live_

Para tu página web y el navegador: puede ir en el código de la página.

portal:read · leads:write · booking:write · finder:write · events:write

Solo lo público y recibir clientes.

Secretadomu_sk_live_

Solo desde un servidor: Zapier, Make, n8n, tu backend o un cliente MCP.

Cualquier permiso: *:read y, con aprobación, *:write

Desde un navegador responde 403.

Las claves de antes (domu_live_) siguen funcionando igual mientras las revisamos.

Modo de prueba

Las claves de prueba (domu_sk_test_ y domu_pk_test_) tienen todos los permisos sin solicitar acceso y solo ven tu organización de prueba, con datos de ejemplo: nada de lo que hagas con ellas llega a tus clientes. Límite: 100 peticiones y 30 escrituras por minuto.

Guía del modo de prueba

Niveles de acceso

Lo que puede hacer una clave depende del plan y de lo que apruebe soporte. Nunca hay API durante la prueba gratis ni con el correo sin verificar.

NivelPlanesCómo se obtiene

1Claves publicables300 peticiones y 60 escrituras por minuto · hasta 5 clavesCualquier plan pagadoSin solicitud

2Secretas de solo lectura60 peticiones por minuto · hasta 2 clavesBusiness · EnterpriseAutomático

3Escrituras, mensajes, webhooks y límites altosA la medida de lo aprobadoCualquier plan pagadoRevisión de soporte

Más límite o más permisos se piden desde Configuración › API y webhooks.

Límites y paginación

Cada respuesta dice cuánto te queda del minuto. Los listados se paginan con page y pageSize y traen meta.total y meta.totalPages.

Encabezados de respuesta

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 41
Retry-After: 41            # solo con 429
Idempotency-Status: replayed  # reintento con la misma Idempotency-Key

Errores

Siempre con la misma forma: { "error": { "code", "message" } }.

400VALIDATION_ERRORDatos de entrada inválidos

401UNAUTHORIZEDClave faltante o inválida

402PAYMENT_REQUIREDCuenta en solo lectura: escritura rechazada

403FORBIDDENLa clave no tiene ese permiso

403SECRET_KEY_IN_BROWSERClave secreta usada desde un navegador

403API_ACCESS_REQUIREDEl nivel de la cuenta no permite esta clave

403PLAN_LIMIT_REACHEDSe alcanzó un tope del plan

404NOT_FOUNDRecurso no encontrado

409IDEMPOTENCY_CONFLICTIdempotency-Key reutilizada con otro cuerpo

409IDEMPOTENCY_IN_PROGRESSOtra petición con la misma Idempotency-Key sigue en curso

429RATE_LIMITEDLímite por minuto superado

429TENANT_RATE_LIMITEDLímite de escrituras por minuto de la organización superado