Integraciones, API y webhooks

Orquiva se conecta con 12 herramientas: Slack, Microsoft Teams, Discord, Google Workspace, Outlook Calendar, feeds iCalendar, inicio de sesión único (SSO), API pública, webhooks salientes, n8n, Zapier y Make. No hay integraciones con ERP ni con programas de nóminas.

Integraciones

Antes de empezar

El catálogo está en la entrada Integraciones del menú. Cada integración tiene además su página en el grupo Integraciones de Organización. Las configura el administrador o quien tenga el permiso de esa integración.

En Organización, Slack, Teams, Google Workspace y Outlook Calendar pueden aparecer con la insignia Pro. La API pública es un complemento que se contrata aparte en cualquier plan: sin él, su página no se abre. Compruébalo en Facturación, plan y módulos.

El catálogo

Arriba eliges la vista: Marketplace (todas) o Mis integraciones (las conectadas). Ver todas abre la lista completa, con buscador y el filtro Categoría: Comunicación, Productividad, Calendario, Seguridad y Desarrollo.

Cada tarjeta dice Conectar, Conectada o Falla. Falla significa que está conectada pero la última comprobación no funcionó (por ejemplo, un permiso de Google revocado).

Integración	Qué hace
Slack	Con la app (Conectar con Slack) envía avisos al Canal por defecto y deja aprobar o rechazar ausencias desde el mensaje. El Webhook (modo clásico) solo envía avisos, sin botones ni comandos.
Microsoft Teams y Discord	Pegas la Webhook URL del canal y activas la integración. Solo reciben avisos.
Google Workspace	Conectar con Google enlaza una cuenta. Permite Exportar empleados a Sheets y Ver eventos próximos. En Drive solo toca los archivos que crea Orquiva.
Outlook Calendar	Conectar Outlook envía las ausencias aprobadas del equipo a un calendario. Sincronizar ahora fuerza la sincronización.
iCalendar	Cada persona saca su feed ICS desde sus Preferencias y lo suscribe en su calendario.
SSO	Google, Microsoft y otros proveedores OIDC (Okta, Entra ID, Keycloak). No hay SAML. Se configura en Organización › Seguridad.
n8n, Zapier y Make	Son guías: se conectan con los webhooks salientes y la API pública.

En Slack, Teams y Discord, Enviar prueba confirma que el mensaje llega. Qué avisos llegan al chat: Avisos en Slack y Teams. El SSO se explica en Seguridad. Para n8n, Zapier y Make, sigue Conectar n8n, Zapier o Make.

Configurar un webhook saliente

Abre Webhooks salientes.
En Endpoints, elige el Tipo de evento (o todos).
Escribe la URL de destino y un Secreto de firma de al menos 8 caracteres.
Pulsa Añadir endpoint y guarda el secreto: no vuelve a mostrarse.
Pulsa Probar para encolar un evento de prueba.

Los eventos son: ausencia solicitada, aprobada, rechazada, modificada y cancelada; empleado creado, editado y eliminado; fichaje registrado, modificado y eliminado; y tarea de onboarding completada.

Cada envío es un POST JSON con estas cabeceras: X-Orquiva-Signature (v1= y el HMAC-SHA256 en hexadecimal de timestamp.idEvento.cuerpo, firmado con tu secreto), X-Orquiva-Timestamp, X-Orquiva-Event-Id y X-Orquiva-Event-Type. Si el secreto se filtra, usa Rotar secreto.

Vigilar las entregas

Orquiva hace hasta 5 intentos, con esperas de 1 minuto, 5 minutos, 15 minutos y 1 hora.

Estado	Qué significa	Qué puedes hacer
En cola	Aún no se ha enviado.	Esperar.
Enviando	El envío está en curso.	Esperar.
Reintentando	Falló y se volverá a intentar.	Arreglar tu destino mientras tanto.
Entregado	Tu destino lo aceptó.	Nada.
Fallido	Agotó los intentos. Aparece en Envíos fallidos.	Pulsar Reintentar cuando el destino funcione.

En Entregas recientes, pulsa un evento para ver cada intento con su código HTTP y su error.

Crear una clave de la API pública

En API Pública, pulsa Crear clave API.
Pon un nombre y marca los Permisos mínimos que necesita.
Si quieres, añade Fecha de expiración (opcional) e IPs permitidas (opcional), que admiten rangos CIDR.
Copia la clave antes de cerrar la ventana.

La clave se muestra una vez

Después no se puede volver a ver. Si la pierdes, pulsa Rotar: se genera otra y la anterior deja de funcionar al momento.

La clave nace Pendiente de aprobar y no funciona hasta que un administrador pulsa Aprobar. Después puede estar Activa, Revocada o Expirada.

Plan	Claves	Peticiones por minuto
Starter	3	60
Professional	10	300
Enterprise	100	1.000

Conectar n8n, Zapier o Make

Orquiva no tiene un conector propio para ninguna de las tres. Sus páginas del catálogo son guías con dos botones, Gestionar webhooks y Gestionar API keys, que llevan a las dos piezas con las que se conectan. Puedes usar una sola o las dos.

Pieza	Para qué	Qué necesitas
Webhooks salientes	Que algo que pasa en Orquiva arranque tu flujo.	Nada más: están en todos los planes.
API pública	Que tu flujo consulte o cambie datos de Orquiva.	El complemento de API pública, que se contrata aparte en cualquier plan.

La cuenta de n8n, Zapier o Make es tuya y se paga aparte, con sus propias condiciones.

Recibir eventos en tu flujo

En tu herramienta, crea el disparador que da una URL: en n8n, un nodo «Webhook»; en Zapier, «Webhooks by Zapier» › «Catch Hook»; en Make, «Webhooks» › «Custom webhook». Copia la URL.
En Orquiva, abre Webhooks salientes y, en Endpoints, elige el Tipo de evento.
Pega la URL en URL de destino, escribe un Secreto de firma y pulsa Añadir endpoint. Guarda el secreto en tu flujo: no vuelve a mostrarse.
Pulsa Probar para comprobar que llega. Para que tu herramienta aprenda la forma de un evento real, provoca uno en Orquiva, por ejemplo una solicitud de ausencia de prueba.

Cada envío es un POST cuyo cuerpo es el JSON del evento; el tipo y el identificador van en las cabeceras. Ten en cuenta:

Cada endpoint recibe un tipo de evento o Todos los eventos. Para varios concretos, crea un endpoint por evento con la misma URL.
Con Todos los eventos también te llegan los fichajes: un envío por cada uno que se registra, modifica o elimina.
La URL tiene que empezar por https:// y ser accesible desde internet. Orquiva no envía a direcciones privadas ni locales, así que una n8n instalada en tu red sin dirección pública no recibe nada.
Tu flujo tiene que contestar con un código 2xx en menos de 8 segundos. Si no, el envío cuenta como fallido y se reintenta, como se explica en Vigilar las entregas.

Comprobar la firma

Cada envío trae estas cabeceras:

Cabecera	Qué lleva
`X-Orquiva-Signature`	`v1=` seguido de la firma, en hexadecimal.
`X-Orquiva-Timestamp`	El momento del envío, en segundos Unix.
`X-Orquiva-Event-Id`	El identificador del evento. Se repite en los reintentos.
`X-Orquiva-Event-Type`	El tipo de evento.
`X-Orquiva-Tenant-Id`	El identificador de tu empresa en Orquiva.

Para comprobar que el envío viene de Orquiva, añade a tu flujo un paso de código que haga esto:

Toma el cuerpo tal como llega, sin volver a formatear el JSON.
Une con puntos la marca de tiempo, el identificador del evento y el cuerpo: timestamp.idEvento.cuerpo.
Calcula el HMAC-SHA256 de ese texto con tu secreto, en hexadecimal.
Compáralo con lo que va detrás de v1=. Si no coincide, descarta el envío.

const crypto = require("crypto");
const base = `${timestamp}.${eventId}.${rawBody}`;
const expected = crypto.createHmac("sha256", secret).update(base).digest("hex");
const valid = signature === `v1=${expected}`;

Descarta también los envíos con una marca de tiempo de hace más de unos minutos, y usa X-Orquiva-Event-Id para no procesar dos veces el mismo evento cuando llegue un reintento. Si pulsas Rotar secreto, cambia el secreto también en tu flujo.

Llamar a la API pública desde tu flujo

Crea una clave con los Permisos mínimos, como se explica en Crear una clave de la API pública, y pide a un administrador que la apruebe.
En tu herramienta, añade una petición HTTP: en n8n, «HTTP Request»; en Zapier, «Webhooks by Zapier» › «Custom Request»; en Make, «HTTP» › «Make a request».
Añade la cabecera X-Api-Key con tu clave.
Usa como dirección la misma con la que entras en Orquiva, seguida de /public-api/v1/.

La cabecera es X-Api-Key

Las guías de n8n, Zapier y Make dentro de Orquiva indican la cabecera Authorization: Bearer. Con ella, la API contesta 401. Usa X-Api-Key.

Para probar la clave, pide GET /public-api/v1/ping: no necesita ningún permiso y devuelve "status": "ok". Un ejemplo real, con el permiso Leer empleados: GET /public-api/v1/employees?is_active=true&size=100 devuelve las personas en activo. Las listas llegan en data, con la paginación en meta (page, size, total_items, total_pages); las páginas empiezan en 0 y admiten hasta 100 elementos. La especificación completa, en formato OpenAPI, está en /v3/api-docs/public-api de esa misma dirección.

Si algo falla, el código te dice por qué: 401 si la clave falta, no existe, no está aprobada, está revocada o caducada, o tu empresa ya no tiene el complemento; 403 si la petición sale de una IP no permitida o a la clave le falta el permiso; 402 si la suscripción de tu empresa no está activa, y 429 si pasas del límite por minuto (espera 60 segundos).

Qué ocurre después

Una integración no cambia quién ve qué: los permisos siguen siendo los de Orquiva. Los webhooks empiezan a enviar en cuanto se produce el primer evento del tipo elegido.

Si algo no sale

No puedo aprobar ausencias desde Teams o Discord. Solo reciben avisos. Para decidir desde el chat necesitas Slack con la app instalada.

Los botones o /orquiva whoisout no funcionan en Slack. Estás en el modo clásico. Instala la app con Conectar con Slack.

Una tarjeta dice Falla. La conexión se ha roto, casi siempre por un permiso revocado en la otra herramienta. Abre la integración, desconéctala y vuelve a conectar.

Mi clave de API da 401 o 403. Mira si sigue Pendiente de aprobar, si está revocada o expirada, si la petición sale de una IP fuera de la lista y si sus permisos cubren lo que pides.

Mis envíos acaban en Fallido. Tu destino devolvía error o no respondía. Mira los intentos, corrige el destino y pulsa Reintentar.

No veo API Pública. Hace falta el complemento de API pública. Revísalo en Facturación, plan y módulos.