API
Lee los datos de tu equipo desde tu propio código, por HTTPS, con respuestas JSON, y recibe sus eventos como webhooks firmados.
Autenticación
Crea una clave de API en los ajustes de tu equipo, en Claves de API, y envíala como token bearer. Una clave pertenece a un equipo, tiene permisos, puede caducar y se puede revocar en cualquier momento. Solo se muestra una vez, así que guárdala en un lugar seguro.
curl https://app.farinu.com/api/v1/members \
-H "Authorization: Bearer $API_KEY"Endpoints
GET /api/v1/members- Los miembros del equipo. Necesita una clave con el permiso read.
GET /api/v1/audit-log- El registro de auditoría del equipo. Necesita una clave con el permiso read, en un plan que incluya el registro de auditoría.
POST /api/v1/webhooks/:id/test- Envía un evento de prueba a uno de los endpoints de webhook del equipo y devuelve el ID de su envío. Necesita una clave con el permiso write, en un plan que incluya webhooks.
GET /api/v1/assistant/instructions- Las instrucciones del equipo para el asistente, null si no ha definido ninguna. Necesita una clave con el permiso read.
Cada endpoint, parámetro y respuesta se describe en el documento OpenAPI 3.1: openapi.json
Paginación
Las listas devuelven una página de elementos, los más antiguos primero, con el cursor desde el que continuar y si quedan más elementos.
limit- Cuántos elementos devolver, de 1 a 100. El valor por defecto es 50.
after- El cursor siguiente de una página, para obtener los elementos que la siguen. Sigue consultando con el último para recibir los elementos nuevos a medida que llegan.
{ "data": [ … ], "next": "1767225600000.…", "hasMore": true }Versiones
La API se versiona por fecha. Envía una cabecera API-Version para fijar una; sin ella obtienes la versión actual. Cada respuesta indica su versión en API-Version, y una versión desconocida es un 400.
Los cambios que podrían romper tu código (quitar o renombrar un campo, cambiar un tipo o un error) se publican con una fecha nueva. Las incorporaciones, como campos, endpoints o eventos nuevos, llegan a todas las versiones. Una versión anterior sigue funcionando al menos 12 meses después de publicarse una más nueva.
curl https://app.farinu.com/api/v1/members \
-H "Authorization: Bearer $API_KEY" \
-H "API-Version: 2026-10-06"Idempotencia
Envía una cabecera Idempotency-Key (hasta 255 caracteres imprimibles, como un UUID) con un POST para reintentarlo de forma segura. Durante 24 horas, la misma clave y la misma solicitud devuelven de nuevo la primera respuesta, con Idempotent-Replayed: true, sin ejecutarla dos veces; la misma clave con otra solicitud es un 422, y una enviada mientras la primera sigue en curso, un 409.
curl -X POST https://app.farinu.com/api/v1/webhooks/$ENDPOINT_ID/test \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Webhooks
Los propietarios y administradores añaden endpoints HTTPS en los ajustes del equipo, en Webhooks, y eligen los eventos que enviar. Cada evento es un POST de JSON con su tipo, hora y datos, firmado al estilo de Standard Webhooks. Responde con cualquier 2xx en 15 segundos; cualquier otra cosa se reintenta tras 1, 5, 25, 125 y 625 minutos, y un endpoint cuyos envíos siguen fallando se desactiva y se avisa por correo a sus administradores.
POST /your/endpoint
webhook-id: whd_…
webhook-timestamp: 1767225600
webhook-signature: v1,…
{ "type": "member.added", "timestamp": "2026-01-01T00:00:00.000Z", "data": { "orgId": "…", "memberId": "…", "userId": "…", "role": "member" } }Para comprobar una solicitud, calcula el HMAC-SHA256 en base64 de webhook-id, webhook-timestamp y el cuerpo sin procesar unidos por puntos, con los bytes del secreto que siguen a whsec_ (base64) como clave, y compáralo en tiempo constante con el valor que sigue a v1, en webhook-signature. Rechaza una marca de tiempo con más de 5 minutos de diferencia y omite un webhook-id que ya hayas procesado.
Eventos: member.added, member.removed, subscription.changed, file.uploaded y webhook.test, además de los del propio producto. El documento OpenAPI describe cada cuerpo.
Errores
Un error devuelve su código de estado y un cuerpo JSON con un código que comprobar y un mensaje que mostrar.
{ "error": { "code": "forbidden", "message": "…" } }400 badRequest- Un parámetro de consulta no es válido.
401 unauthorized- Falta la clave, o es incorrecta, está revocada o ha caducado.
402 upgradeRequired- El plan del equipo no incluye la API o este endpoint.
403 forbidden- La clave no tiene el permiso que necesita este endpoint.
409 conflict- El recurso está en un estado que no permite esto, o una solicitud con la misma Idempotency-Key sigue en curso.
422 idempotencyMismatch- La Idempotency-Key ya se usó para otra solicitud.
429 rateLimited- Demasiadas solicitudes. Cada clave puede hacer 100 por minuto; espera los segundos que indica la cabecera Retry-After.