Integraciones de Altar
Conecta otros sistemas con tu cuenta de Altar. Hay dos caminos, y puedes usarlos juntos. Ninguno de los dos usa tu usuario ni tu contraseña.
| Mecanismo | Sentido | Para qué |
|---|---|---|
| API pública, con API key | Tu sistema → Altar | Leer los eventos, clientes, proveedores y tareas de tu cuenta. |
| Webhooks | Altar → tu sistema | Recibir un aviso en tu servidor cuando se crea un cliente, un proveedor, una tarea o un evento. |
Antes de empezar
- Plan. Las integraciones son del plan Enterprise con el pago al día. Con Pro, con Free o durante la prueba gratuita, la API responde
403concode: "ENTERPRISE_REQUIRED"y los webhooks no se envían. Se mira en cada request y en cada envío: si la cuenta deja Enterprise, las keys y los webhooks dejan de funcionar sin que tengas que tocarlos, y vuelven solos cuando la cuenta vuelve a Enterprise. Los eventos que ocurran mientras tanto no se envían después. - Quién las gestiona. Las API keys y los webhooks son de la cuenta, no de una persona, y solo los administra el dueño de la cuenta, desde Configuración → Integraciones. Los demás usuarios del equipo reciben
403concode: "SOLO_OWNER", y no hay permiso que lo habilite. Una key lee los datos de toda la cuenta y sigue funcionando aunque quien la creó deje la cuenta. - Base URL. La API pública está en
https://app.altarsoftware.com/api/v1. Las rutas comoGET /eventosvan a continuación:https://app.altarsoftware.com/api/v1/eventos.
API keys y autenticación
Crear una key
El dueño de la cuenta la crea desde Configuración → Integraciones, con:
- un nombre para reconocerla (por ejemplo, "Zapier");
- uno o más scopes (ver Scopes);
- un vencimiento opcional (
expiraEn, ver abajo).
Al crearla, Altar muestra la clave completa una sola vez. Tiene la forma ak_ seguido de 32 caracteres (letras, números, - y _). Guárdala en ese momento: Altar guarda solo un hash, y si la pierdes no se puede recuperar; hay que revocarla y crear otra.
Trátala como una contraseña: en variables de entorno o en un gestor de secretos, nunca en el código ni en un repositorio.
Usar la key
Mándala en el header x-api-key en cada request:
curl https://app.altarsoftware.com/api/v1/me \
-H "x-api-key: ak_Xx0Yy1Zz2…"Si falta, es inválida, está revocada o venció, la respuesta es 401 (verErrores).
Vencimiento (expiraEn)
Al crear la key se puede fijar una fecha de vencimiento (tiene que ser futura). Desde ese momento la key responde401 con el mensaje API key expirada. Una key vencida no se renueva: se crea otra. Sin vencimiento, la key vale hasta que la revoques.
Revocar
Desde Configuración → Integraciones. El efecto es inmediato: el request siguiente con esa key ya recibe401. El dueño puede revocar keys en cualquier plan, aunque la cuenta ya no tenga Enterprise.
Scopes
Cada key accede solo a lo que habilitan sus scopes. Por ahora la API es de solo lectura.
| Scope | Habilita |
|---|---|
eventos:read | GET /eventos |
clientes:read | GET /clientes |
proveedores:read | GET /proveedores |
tareas:read | GET /tareas |
GET /me no pide scope. Pedir un endpoint sin su scope da 403.
Las keys creadas antes con el scope finanzas:read siguen funcionando: ese scope se ignora, porque nunca habilitó ningún endpoint. Ya no se puede elegir al crear una key.
API pública
Es un contrato propio, separado de la app: los cambios internos de Altar no cambian estas respuestas.
Qué datos devuelve
Siempre los de tu cuenta, la dueña de la key, sin importar quién del equipo los haya cargado. Solo se incluyen los eventos propios de la cuenta: los eventos de otras cuentas en los que tu cuenta colabora no aparecen en /eventos ni sus tareas en /tareas. Los clientes y proveedores que están en la papelera no aparecen, ni los contactos borrados de un cliente.
Paginación
Los cuatro listados aceptan page y limit, y devuelven data y meta:
{
"data": [ … ],
"meta": { "page": 2, "limit": 50, "total": 128, "totalPages": 3 }
}| Parámetro | Default | Reglas |
|---|---|---|
page | 1 | Entero desde 1. Un valor inválido o menor a 1 se toma como 1. |
limit | 50 | Entre 1 y 200. Más de 200 se toma como 200; un valor inválido, como 50. |
totalPages es 1 aunque no haya resultados. Una página más allá de la última devuelve data: [].
Campos sin valor
Un campo sin valor puede venir como null o directamente no venir en la respuesta. Trata los dos casos igual. Los objetos anidados (ubicacion, presupuesto, cantidadInvitados,evento) siempre traen todas sus claves.
Las fechas son strings ISO 8601 en UTC ("2027-03-20T00:00:00.000Z"). Los id son strings de 24 caracteres hexadecimales.
GET /me
GET https://app.altarsoftware.com/api/v1/me
Identidad de la key. Sirve para probar la conexión. cuenta es el dueño de la cuenta, no quien creó la key.
{
"data": {
"cuenta": {
"id": "6650f1a2b3c4d5e6f7a8b9c0",
"nombre": "Ana",
"apellido": "Pérez",
"email": "ana@ejemplo.com",
"rol": "PLANNER"
},
"apiKey": { "nombre": "Zapier", "scopes": ["eventos:read", "clientes:read"] }
}
}GET /eventos
GET https://app.altarsoftware.com/api/v1/eventos
Scope eventos:read. Ordenados por fechaEvento descendente: primero la fecha más tardía.
| Filtro | Valores |
|---|---|
estado | PLANIFICANDO, EN_CURSO, FINALIZADO, CANCELADO, PAUSADO, ARCHIVADO |
{
"data": [
{
"id": "6650f1a2b3c4d5e6f7a8b9c1",
"nombre": "Boda de Ana y Juan",
"tipoEvento": "BODA",
"estado": "PLANIFICANDO",
"fechaEvento": "2027-03-20T00:00:00.000Z",
"descripcion": "Ceremonia y fiesta en la quinta",
"ubicacion": {
"salon": "Quinta Los Álamos",
"direccion": "Ruta 8 km 50",
"ciudad": "Pilar",
"provincia": "Buenos Aires"
},
"presupuesto": { "totalCentavos": 150000050, "moneda": "ARS" },
"cantidadInvitados": { "estimada": 150, "confirmada": 90 },
"createdAt": "2026-10-01T14:03:11.000Z",
"updatedAt": "2026-11-02T09:41:27.000Z"
}
],
"meta": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}tipoEvento:BODA,ANIVERSARIO,CUMPLEAÑOS,CORPORATIVOuOTRO.presupuesto.totalCentavoses un entero en centavos: la centésima parte de la unidad de la moneda, para toda moneda.150000050son 1.500.000,50 pesos. Para mostrarlo, divide por 100. Todos los montos de la API van así, en enteros y con el sufijoCentavosen el nombre, para que nunca viajen decimales.monedaes un código ISO 4217 (ARS,USD, …); los montos no se convierten entre monedas.presupuesto.totalCentavoses el presupuesto estimado del evento, el que carga la cuenta. No es el monto de un presupuesto comercial aceptado: aceptar uno no lo cambia.cantidadInvitados.estimadaes lo que cargó la cuenta;confirmada, los invitados que confirmaron asistencia.
GET /clientes
GET https://app.altarsoftware.com/api/v1/clientes
Scope clientes:read. Ordenados por última modificación, del más reciente al más viejo.
| Filtro | Valores |
|---|---|
estado | LEAD, CONTACTADO, PROPUESTA, ACTIVO, GANADO, PERDIDO, INACTIVO |
{
"data": [
{
"id": "6650f1a2b3c4d5e6f7a8b9c2",
"nombreMostrar": "Ana y Juan",
"estado": "ACTIVO",
"ubicacion": { "salon": null, "direccion": null, "ciudad": "CABA", "provincia": "CABA" },
"contactos": [
{
"nombre": "Ana",
"apellido": "Pérez",
"rol": "novia",
"email": "ana@ejemplo.com",
"telefono": "+54 11 5555-0000",
"whatsapp": "+54 9 11 5555-0000"
}
],
"createdAt": "2026-09-12T18:20:00.000Z",
"updatedAt": "2026-11-01T10:00:00.000Z"
}
],
"meta": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}contactos[].rol es texto libre (novia, novio, madre, organizador…).
GET /proveedores
GET https://app.altarsoftware.com/api/v1/proveedores
Scope proveedores:read. Primero los favoritos y después por última modificación.
| Filtro | Valores |
|---|---|
estado | ACTIVO, INACTIVO |
categoria | Texto exacto, respetando mayúsculas y acentos (Catering, Música/DJ, …). Es texto libre. |
{
"data": [
{
"id": "6650f1a2b3c4d5e6f7a8b9c3",
"nombreMostrar": "Catering Del Sur",
"categoria": "Catering",
"estado": "ACTIVO",
"favorito": true,
"email": "hola@cateringdelsur.com",
"telefono": "+54 341 555-0000",
"whatsapp": "+54 9 341 555-0000",
"sitioWeb": "https://cateringdelsur.com",
"ubicacion": { "ciudad": "Rosario", "provincia": "Santa Fe" },
"createdAt": "2026-08-30T12:00:00.000Z",
"updatedAt": "2026-10-15T16:45:00.000Z"
}
],
"meta": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}GET /tareas
GET https://app.altarsoftware.com/api/v1/tareas
Scope tareas:read. Las tareas de los eventos de la cuenta, las haya creado quien sea. Ordenadas porfechaFinalizacion ascendente; las que no tienen fecha de finalización van primero.
| Filtro | Valores |
|---|---|
estado | sin_iniciar, en_progreso, validando, completada |
eventoId | El id de un evento de la cuenta. El de un evento ajeno devuelve data: []. |
{
"data": [
{
"id": "6650f1a2b3c4d5e6f7a8b9c4",
"titulo": "Confirmar el DJ",
"descripcion": "Pedir la lista de temas",
"estado": "en_progreso",
"prioridad": "alta",
"fechaInicio": "2026-11-01T00:00:00.000Z",
"fechaFinalizacion": "2026-11-15T00:00:00.000Z",
"evento": { "id": "6650f1a2b3c4d5e6f7a8b9c1", "nombre": "Boda de Ana y Juan" },
"createdAt": "2026-10-20T11:00:00.000Z",
"updatedAt": "2026-11-03T08:30:00.000Z"
}
],
"meta": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}prioridad: baja, media o alta.
Un valor de estado (o de categoria) que no existe no da error: devuelve una lista vacía.
Límites
| Límite | Alcance | Al pasarlo |
|---|---|---|
| 120 requests por minuto | Por API key | 429 con code: "RATE_LIMIT_API_KEY" |
| 100 autenticaciones fallidas cada 15 minutos | Por IP | 429 con code: "API_KEY_BLOQUEADA" |
Las respuestas llevan los headers RateLimit-Limit, RateLimit-Remaining yRateLimit-Reset (segundos hasta que se renueva el cupo), y el 429 incluyeRetry-After.
El segundo límite cuenta solo los requests que terminan en 401: sin key, con una key inválida, revocada o vencida. Los que autentican no lo gastan, aunque den 403 por scope o por plan. Mientras una IP está bloqueada, todos sus requests a la API pública reciben 429, también los que traen una key válida.
Webhooks
Cuando pasa algo en tu cuenta, Altar hace un POST firmado a la URL que configures. El dueño de la cuenta los crea desde Configuración → Integraciones, eligiendo a qué eventos suscribirse. Un webhook recibe los eventos de toda la cuenta, los haya generado quien sea del equipo.
Requisitos de la URL
La URL se rechaza con 400 y code: "WEBHOOK_URL_INVALIDA" si no cumple todo esto:
- empieza con
https://; - usa el puerto estándar de HTTPS (443) y no indica otro;
- no incluye usuario ni contraseña (
https://usuario:clave@…); - apunta a un servidor público. Se rechazan
localhosty cualquier host que sea o resuelva a una dirección no pública: loopback (127.0.0.0/8,::1), redes privadas (10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7), link-local (169.254.0.0/16,fe80::/10), CGNAT (100.64.0.0/10),0.0.0.0/8, multicast (224.0.0.0/4,ff00::/8), reservadas y broadcast (240.0.0.0/4,255.255.255.255) y NAT64 (64:ff9b::/96,64:ff9b:1::/48). Si el host resuelve a varias IPs, todas tienen que ser públicas.
Además, tu servidor tiene que presentar un certificado TLS válido para ese nombre de host, emitido por una autoridad reconocida. Con uno autofirmado o vencido, el envío falla.
La dirección se controla al crear y al editar el webhook, y otra vez en cada envío, al momento de conectar. Si el host pasó a resolver a una dirección no pública, ese intento falla sin enviar nada.
Eventos
| Evento | Se dispara al… | data |
|---|---|---|
cliente.creado | crear un cliente en el CRM | { id, nombreMostrar, estado } |
proveedor.creado | crear un proveedor en el CRM | { id, nombreMostrar, categoria } |
evento.creado | crear un evento, desde Eventos o desde la ficha de un cliente | { id, nombre, tipoEvento, estado } |
tarea.creada | crear una tarea en un evento de tu cuenta, la cree alguien de tu equipo o de una cuenta que colabora en ese evento (las que agrega la pareja desde su portal no lo disparan) | { id, titulo, estado, eventoId } |
ping | usar el botón Probar (no se puede suscribir) | { mensaje, webhookId } |
Los valores posibles de estado, tipoEvento y categoria son los mismos de laAPI pública. Para el resto de los datos, consulta la API con el id.
Quién recibe cada evento
Los eventos de algo que pertenece a un evento (evento.creado, tarea.creada) le llegan siempre a la cuenta dueña del evento, sin importar desde qué cuenta se hizo el cambio. Si tu cuenta colabora en un evento de otra cuenta, las tareas que crees ahí le llegan a esa otra cuenta, no a la tuya. Así, todoeventoId que recibas aparece en tu GET /eventos.
cliente.creado y proveedor.creado le llegan a la cuenta que da de alta el cliente o el proveedor, que es su dueña.
El envío
Un POST con Content-Type: application/json y este cuerpo:
{
"id": "0b6e3c1e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"evento": "cliente.creado",
"creadoEn": "2026-11-07T12:00:00.000Z",
"data": {
"id": "6650f1a2b3c4d5e6f7a8b9c2",
"nombreMostrar": "Ana y Juan",
"estado": "LEAD"
}
}Y estos headers:
| Header | Contenido |
|---|---|
X-Altar-Event | El evento (cliente.creado, …). |
X-Altar-Delivery | El id del cuerpo: identifica la entrega. |
X-Altar-Timestamp | Momento del intento, en segundos desde epoch (UTC). |
X-Altar-Signature | sha256=<firma> (ver abajo). |
User-Agent | Altar-Webhooks/1 |
El id y el cuerpo son los mismos en todos los reintentos de una entrega: úsalos para no procesar dos veces lo mismo. El timestamp y la firma cambian en cada intento.
Verificar la firma
Cada webhook tiene un secret (whsec_…) que Altar muestra completo una sola vez: al crear el webhook y cada vez que lo rotas. Después se ve solo enmascarado.
La firma es el HMAC-SHA256, en hexadecimal, de este texto:
<X-Altar-Timestamp>.<cuerpo crudo del request>Para verificarla:
- Toma el cuerpo tal como llegó, sin parsearlo ni volver a serializarlo. Con otro orden de claves o espacios, la firma no coincide.
- Calcula
HMAC-SHA256(secret, timestamp + "." + cuerpo). - Compárala con lo que viene después de
sha256=usando una comparación de tiempo constante. - Rechaza timestamps viejos (por ejemplo, de más de 5 minutos) para que un envío capturado no se pueda reenviar.
Ejemplo en Node.js con Express:
import express from 'express';
import crypto from 'node:crypto';
const app = express();
const SECRET = process.env.ALTAR_WEBHOOK_SECRET;
// express.raw: el cuerpo llega como Buffer, sin parsear.
app.post('/altar', express.raw({ type: 'application/json' }), (req, res) => {
const timestamp = req.get('X-Altar-Timestamp') || '';
const recibida = (req.get('X-Altar-Signature') || '').replace(/^sha256=/, '');
const esperada = crypto
.createHmac('sha256', SECRET)
.update(`${timestamp}.${req.body.toString('utf8')}`)
.digest('hex');
const firmaOk = recibida.length === esperada.length
&& crypto.timingSafeEqual(Buffer.from(recibida), Buffer.from(esperada));
const reciente = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
if (!firmaOk || !reciente) return res.sendStatus(401);
res.sendStatus(200); // responde rápido…
const envio = JSON.parse(req.body.toString('utf8'));
// …y procesa después. Usa envio.id para ignorar duplicados.
});Reintentos y desactivación
- Una entrega es exitosa si tu servidor responde 2xx dentro de los 10 segundos. Cualquier otra cosa es un fallo:
3xx,4xx,5xx, timeout, error de conexión o de certificado, o un destino que pasó a resolver a una dirección no pública. - Los redirects no se siguen. Un
301o302cuenta como fallo. - Cada entrega tiene hasta 3 intentos: el primero enseguida, el segundo 1 segundo después del primer fallo y el tercero 3 segundos después del segundo.
- Si los 3 intentos fallan, la entrega cuenta como un evento fallido. Al llegar a 15 eventos fallidos seguidos, el webhook se desactiva solo y deja de recibir envíos. Una entrega exitosa vuelve el contador a cero.
- Probar no suma ni resta al contador: si pruebas varias veces un destino caído mientras lo arreglas, el webhook no se desactiva por eso.
- Para reactivarlo, el dueño lo vuelve a activar desde la app; eso también pone el contador en cero. Los eventos ocurridos mientras estuvo desactivado no se reenvían.
- La entrega es de mejor esfuerzo: no hay cola persistente, así que ante un reinicio del servidor de Altar en medio de los reintentos, la entrega puede perderse. Si necesitas no perder nada, usa la API pública para conciliar.
Probar y ver el log
- Probar envía un
pingy muestra si tu servidor respondió y con qué código HTTP. Por seguridad, no muestra el detalle de un error de conexión. - Ver log muestra las últimas 20 entregas: evento, intento, si salió bien y el código HTTP.
Gestión
Todo se hace desde la app, con la sesión del dueño de la cuenta (no con una API key). Como referencia:
| Acción | Plan |
|---|---|
| Ver la lista de webhooks y eliminar uno | Cualquiera |
| Ver los eventos a los que se puede suscribir un webhook | Cualquiera |
| Crear, editar (nombre, URL, eventos, activo), rotar el secret, probar y ver el log | Enterprise |
| Ver la lista de keys y revocar una | Cualquiera |
| Ver los scopes que se pueden asignar a una key | Cualquiera |
| Crear una key | Enterprise |
Errores
Todas las respuestas de error son JSON con un message legible y, cuando corresponde, uncode estable. Programa contra el code y el status, no contra el texto.
{ "message": "La API y los webhooks están disponibles solo con el plan Enterprise.", "code": "ENTERPRISE_REQUIRED" }API pública
| Status | code | Cuándo |
|---|---|---|
401 | — | Falta el header x-api-key, la key es inválida o fue revocada (API key inválida o revocada), o venció (API key expirada). |
403 | ENTERPRISE_REQUIRED | La cuenta no tiene Enterprise con el pago al día. |
403 | — | La key no tiene el scope del endpoint. El mensaje dice cuál falta. |
404 | — | La ruta no existe. |
429 | RATE_LIMIT_API_KEY | La key pasó los 120 requests por minuto. |
429 | API_KEY_BLOQUEADA | La IP acumuló 100 autenticaciones fallidas en 15 minutos. |
5xx | — | Error de Altar. Reintenta más tarde. |
Gestión desde la app
| Status | code | Cuándo |
|---|---|---|
400 | WEBHOOK_URL_INVALIDA | La URL del webhook no cumple los requisitos. |
400 | — | Faltan datos o no son válidos: nombre vacío, scope inexistente (incluido finanzas:read), vencimiento pasado o inválido, evento inexistente o ninguno elegido. |
403 | SOLO_OWNER | Quien hace el pedido no es el dueño de la cuenta. |
403 | ENTERPRISE_REQUIRED | La acción requiere Enterprise (ver Gestión). |
404 | — | La key o el webhook no existen o son de otra cuenta (API key no encontrada,Webhook no encontrado). |
Para empezar
- En Configuración → Integraciones, crea una API key con los scopes que necesites y guárdala.
- Prueba la conexión con
GET https://app.altarsoftware.com/api/v1/me. - Si quieres avisos, crea un webhook apuntando a tu servidor, guarda el secret y verifica la firma de cada envío.
- Usa Probar para confirmar que tu servidor responde
2xx.