# API REST para CRM con webhooks firmados | AiCrm

> CRM con API REST pública: crea y consulta contactos con una cabecera X-Api-Key, hasta 20 claves por integración y webhooks salientes firmados con HMAC-SHA256. Alta de leads desde tu web sin duplicados.

- **Fuente (source):** https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados
- **Plataforma (platform):** AIstoHire
- **Idioma (language):** es

## En resumen

- API REST pública con varias API keys y webhooks firmados
- Da de alta clientes desde tu web, tu formulario o tu backend con una llamada HTTP, y recibe cada cambio en tu servidor firmado con HMAC-SHA256.
- Alta de contactos con una sola llamada
- Sin duplicados por diseño
- Hasta 20 claves con nombre

## API REST pública con varias API keys y webhooks firmados

AiCrm, la app de CRM de AIsToHire, expone una API REST pública sobre tus propios contactos. Con una clave en la cabecera `X-Api-Key` puedes crear, listar, consultar, actualizar y borrar contactos, y añadir actividades a cualquiera de ellos, desde el formulario de tu web, tu chatbot, un Zap, un script de Python o tu propio backend. Las respuestas son JSON con la forma `{ success, data }`, y el límite es de 100 peticiones por minuto y clave.

El alta por API no duplica: si el email que envías ya existe en tu base, AiCrm actualiza la ficha que ya tenías (completa el teléfono, el nombre o la empresa que faltaran, une las etiquetas) y registra un nuevo envío en su timeline, devolviendo HTTP 200; si es nuevo, lo crea y devuelve 201. Cada contacto que entra por API se etiqueta automáticamente como `api-lead`, conserva las etiquetas que tú mandes y guarda el `subId` de origen, además del país, la IP y el navegador desde los que llegó.

Puedes tener hasta 20 API keys con nombre propio, además de la clave interna de la app. Así das una clave distinta a cada integración —la web, el formulario de la campaña de mayo, el becario, el proveedor— y la revocas sola cuando esa integración termina, sin tocar las demás. El valor completo de una clave se muestra una única vez, al crearla; después solo se ve enmascarada en el listado.

En la otra dirección, los webhooks avisan a tus sistemas. Configuras hasta 10 destinos, eliges a qué eventos se suscribe cada uno (`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`) y AiCrm hace un POST a tu URL con las cabeceras `X-AiCrm-Event` y `X-AiCrm-Signature: sha256=…`, la firma HMAC-SHA256 del cuerpo con el secreto de ese webhook, para que verifiques que la entrega es legítima. Al guardar la URL, una guarda anti-SSRF rechaza localhost, 127.0.0.0/8, 10.x, 192.168.x, 172.16-31.x, ::1, 0.0.0.0 y los dominios `.local` e `.internal`.

## Qué incluye

- **Alta de contactos con una sola llamada** — un POST a `/api/apps/public/crm/customers` con el email y las etiquetas que quieras, y el lead ya está en tu CRM clasificado.
- **Sin duplicados por diseño** — si el email ya existe, se actualiza la ficha y se apunta el nuevo envío en su timeline en lugar de crear una segunda ficha.
- **Hasta 20 claves con nombre** — una por integración, revocable por separado. Si una clave se filtra, borras esa y nada más deja de funcionar.
- **Webhooks firmados con HMAC-SHA256** — verificas la cabecera `X-AiCrm-Signature` con tu secreto y sabes que el aviso viene de tu CRM y no de un tercero.
- **Guarda anti-SSRF incluida** — la app se niega a entregar webhooks a localhost o a rangos de red privados, así que tu CRM no puede usarse para sondear una red interna.
- **CRUD completo, no solo altas** — listar con paginación y filtros (búsqueda, estado, etiquetas, país), consultar un contacto con su actividad, actualizarlo, borrarlo y registrarle actividades.
- **Origen trazado automáticamente** — cada alta por API guarda el `subId` que envías más el país, la IP y el navegador, y queda etiquetada como `api-lead` para filtrarla luego en la app.
- **Pruebas sin adivinar** — la app trae la documentación de los endpoints con un ejemplo de `curl` copiable y un botón para enviar una entrega de prueba a cada webhook, con el estado y la hora del último intento.

## Preguntas frecuentes

### ¿Cómo creo un contacto en el CRM desde mi web?

Haces un POST a `/api/apps/public/crm/customers` con la cabecera `X-Api-Key` y un JSON con al menos el email o el teléfono. Puedes enviar también nombre, teléfono, empresa, país, estado, notas, etiquetas y un `subId` para identificar la campaña o el formulario de origen. AiCrm devuelve 201 si lo crea y 200 si ese contacto ya existía.

### ¿Qué pasa si el mismo email entra dos veces por la API?

No se duplica. AiCrm busca el email (o el teléfono, si no mandas email) y, si lo encuentra, actualiza la ficha existente rellenando los campos que estuvieran vacíos, une las etiquetas nuevas con las que ya tenía y registra el nuevo envío en su timeline de actividad. La respuesta indica que el contacto ya existía y te devuelve su id.

### ¿Cuántas API keys puedo tener y puedo revocar una sola?

Puedes crear hasta 20 claves con nombre propio, además de la clave interna de la app, que no se puede borrar. Cada clave se elimina de forma independiente, así que puedes dar una distinta a cada integración y revocarla sin afectar al resto. El valor completo se muestra solo en el momento de crearla; después aparece enmascarado en el listado. Todas las claves comparten el límite de 100 peticiones por minuto por clave.

### ¿Cómo verifico que un webhook viene de verdad de mi CRM?

Cada entrega lleva la cabecera `X-AiCrm-Signature: sha256=<firma>`, que es el HMAC-SHA256 del cuerpo exacto de la petición usando el secreto que la app te muestra al crear el webhook. Calcula ese HMAC en tu servidor sobre el cuerpo recibido y compáralo. Además viaja la cabecera `X-AiCrm-Event` con el nombre del evento: `customer.created`, `customer.updated`, `customer.deleted` o `activity.created`.

### ¿Qué ocurre si mi endpoint de webhook está caído?

La entrega es best-effort: AiCrm espera hasta 5 segundos y, si falla, reintenta una vez pasado un segundo y medio. No hay cola persistente de reintentos, así que una caída larga de tu servidor puede hacerte perder avisos; en ese caso reconcilia con un GET a `/api/apps/public/crm/customers`. La app te muestra el estado y la hora del último intento de cada webhook, y puedes lanzar una entrega de prueba cuando quieras.

- [AiCrm — CRM ligero con API para dar de alta clientes desde cualquier sistema](https://aistohire.com/es/aicrm-crm-ligero-con-api-109)

## Sobre la plataforma

**AiCrm — CRM ligero con API para dar de alta clientes desde cualquier sistema** — aplicación de AIstoHire. Disponible en: https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados

### Otros idiomas

- `en`: https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks
- `fr`: https://aistohire.com/fr/aicrm-crm-leger-avec-api-109/f/api-rest-crm-webhooks-signes
- `it`: https://aistohire.com/it/aicrm-crm-leggero-con-api-109/f/api-rest-crm-webhook-firmati
- `pt`: https://aistohire.com/pt/aicrm-crm-leve-com-api-109/f/api-rest-crm-webhooks-assinados
- `de`: https://aistohire.com/de/aicrm-leichtes-crm-mit-api-109/f/api-rest-crm-signierte-webhooks
- `bg`: https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove
- `ja`: https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks
- `nl`: https://aistohire.com/nl/aicrm-eenvoudige-crm-met-api-om-klanten-en-leads-te-beheren-109/f/rest-api-crm-ondertekende-webhooks
- `ko`: https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook
- `sv`: https://aistohire.com/sv/aicrm-enkelt-crm-med-api-for-att-hantera-kunder-och-leads-109/f/rest-api-crm-signerade-webhooks
- `da`: https://aistohire.com/da/aicrm-enkelt-crm-med-api-til-at-styre-kunder-og-leads-109/f/rest-api-crm-signerede-webhooks
- `ar`: https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109/f/crm-rest-api-webhooks
- `no`: https://aistohire.com/no/aicrm-enkelt-crm-med-api-for-a-styre-kunder-og-leads-109/f/rest-api-crm-signerte-webhooks
- `fi`: https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit
- `zh`: https://aistohire.com/zh/ai-crm-rest-api-webhooks-109/f/crm-rest-api-webhook
- `pl`: https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki
- `he`: https://aistohire.com/he/aicrm-crm-pshot-am-api-lnihol-lkochot-vlidim-109/f/api-rest-crm-webhooks-chatumim
- `cs`: https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky
- `id`: https://aistohire.com/id/aicrm-crm-sederhana-dengan-api-untuk-mengelola-pelanggan-dan-lead-109/f/api-rest-crm-webhook-bertanda-tangan
