| Requisito | Condición |
|---|---|
| Plan de Safina | Pro o Business |
| Tu rol en Safina | Propietario o administrador del equipo |
Una clave de API permite que una herramienta de automatización use la API REST de Safina para tu equipo. Con una clave, Zapier, n8n, Make o tu propio script pueden leer tus llamadas y sus resúmenes, buscar y crear contactos e iniciar un flujo de trabajo después de cada llamada. La clave solo funciona con la API de Safina. Las aplicaciones de IA como Claude o ChatGPT se conectan de otra forma. Consulta Conectar Safina con tu asistente de IA.
Crear una clave de API
- En la app de Safina, abre la pestaña Perfil y toca Claves de API.

- Toca + junto a Tus claves de API. Si aún no tienes ninguna clave, toca Crear clave de API debajo de la lista vacía.

- Arriba en la página Nueva clave de API, toca el título y escribe un nombre que te diga dónde usas la clave, por ejemplo “Zapier”.

-
En ¿Qué puede hacer esta clave?, elige:
- Solo lectura: puede leer llamadas, contactos y asistentes.
- Lectura y escritura: también puede crear y cambiar contactos y webhooks.
No puedes cambiarlo después. Para otro acceso, crea una clave nueva.
-
En Caduca después de, elige cuándo caduca la clave: 30 días, 90 días (seleccionado por defecto), 1 año o Sin caducidad.
-
Toca Crear clave de API.

- La página muestra ahora Tu nueva clave de API. Toca Copiar clave y pega la clave en tu automatización. Empieza por
safina_api_. Safina muestra la clave completa solo una vez.

- Toca Hecho para volver a la lista.
Cada solicitud envía la clave en el encabezado Authorization: Bearer <clave>. La lista Tus claves de API muestra cuándo se creó cada clave, cuándo caduca y cuándo se usó por última vez. Para desactivar una clave al instante, toca la papelera junto a ella y confirma con Eliminar. Las automatizaciones que la usan dejan de funcionar.
Qué puede hacer una clave de API
| Área | Solo lectura | Lectura y escritura |
|---|---|---|
| Asistentes | Listar los asistentes del equipo | Igual |
| Llamadas | Listar llamadas (las más recientes primero, con filtros por número de teléfono, fecha y duración) y obtener una llamada con resumen, llamante y duración | Igual |
| Contactos | Buscar contactos y encontrar un contacto por número de teléfono | También crear y actualizar contactos |
| Webhooks | – | Suscribirse al evento call.ended y eliminar la suscripción |
Todas las rutas, campos y respuestas están en la referencia de la API (en inglés).
Zapier
- App Safina AI para Zapier: la app tiene el activador New Call, las acciones Create Contact y Update Contact, y las búsquedas Find Call, Find Contact, Find Contact by Text y Find or Create Contact. La conectas con una clave de API. La app todavía no está en el directorio de apps de Zapier. Para obtener acceso, escribe a info@safina.ai.
- Webhooks by Zapier: un Catch Hook recibe los datos de cada llamada cuando termina, sin clave de API. Los pasos están en Safina + Zapier.
n8n
- Nodo de Safina para n8n: el paquete
@sk-thinking/n8n-nodes-safinaañade dos nodos. Safina lee asistentes y llamadas, y crea, busca y actualiza contactos. También funciona como herramienta del AI Agent de n8n. Safina Trigger inicia un flujo de trabajo cuando termina una llamada y comprueba la firma de cada evento. Añades la clave como credencial del tipo Safina API. El nodo todavía no está en la lista de nodos de la comunidad de n8n. Para obtener acceso, escribe a info@safina.ai. El código fuente es público en GitHub. - Nodo HTTP Request: llama a cualquier ruta de la API con el encabezado
Authorization: Bearer <clave>. - Nodo Webhook: recibe los datos de cada llamada cuando termina. Los pasos están en Safina + n8n.
Make
Make todavía no tiene una app de Safina. Para llamar a la API, usa el módulo HTTP Make a request con el encabezado Authorization: Bearer <clave>. Para iniciar un escenario después de cada llamada, usa un Custom webhook, como se describe en Safina + Make.
Tu propio script
La dirección de la API es https://api.backend.safina.ai. Este ejemplo lee las cinco llamadas más recientes:
curl "https://api.backend.safina.ai/calls/me?limit=5" \
-H "Authorization: Bearer safina_api_..."
Los valores de consulta son JSON. Un valor de texto necesita comillas dobles, un número no:
curl -G "https://api.backend.safina.ai/contacts/me" \
--data-urlencode 'search="Miller"' \
-H "Authorization: Bearer safina_api_..."
Un webhook después de cada llamada
Con una clave de lectura y escritura, POST /webhooks con un name y una url suscribe el evento call.ended. Safina envía entonces un evento por llamada cuando el resumen está listo.
- Indica
"create_signing_secret": truepara firmar los eventos. La respuesta contiene el secreto una sola vez. Cómo comprobar el encabezadoX-Safina-Signaturese explica en Cómo comprobar que un webhook viene de verdad de Safina. - Safina intenta cada envío hasta tres veces. Un envío repetido tiene el mismo
event_id, así que descarta los eventos que ya hayas procesado. - Un equipo puede tener hasta 20 webhooks. Elimina con
DELETE /webhooks/{id}las suscripciones que ya no necesites. - Si la dirección responde
410 Goneen todos los intentos durante tres llamadas seguidas, Safina desactiva el webhook y envía un correo electrónico. Puedes volver a activarlo en la app, en Safina AI > Registro de llamadas > Webhooks.
Cuando una solicitud falla
| Respuesta | Significado |
|---|---|
401 | La clave es incorrecta, se eliminó o caducó: crea una clave nueva y actualiza tu automatización. También recibes 401 si la persona que creó la clave ya no es propietaria ni administradora del equipo, o si el equipo no tiene un plan activo. |
403 api_keys_not_enabled | Tu cuenta todavía no tiene acceso a las claves de API. |
403 plan_required | El equipo necesita el plan Pro o superior. |
403 con una clave de solo lectura | La solicitud cambia datos. Usa una clave de lectura y escritura. |
409 | El número de teléfono ya pertenece a un contacto, o el equipo ya tiene 20 webhooks. |
Preguntas frecuentes
¿Puedo usar un código de conexión de IA en lugar de una clave de API?
No. Un código de conexión solo funciona con asistentes de IA. Una clave de API solo funciona con la API REST.
¿Una clave funciona para todos mis equipos?
No. Una clave pertenece al equipo que estaba activo cuando la creaste. Para otro equipo, cambia de equipo en la app y crea allí una clave.
¿Qué pasa cuando una clave caduca?
Las solicitudes con esa clave reciben 401. Crea una clave nueva y sustituye la antigua en tu automatización.
Tu equipo de Safina