Saltar al contenido

Documentación

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.

MecanismoSentidoPara qué
API pública, con API keyTu sistema → AltarLeer los eventos, clientes, proveedores y tareas de tu cuenta.
WebhooksAltar → tu sistemaRecibir 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 403 concode: "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 403 con code: "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 /eventos van 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.

ScopeHabilita
eventos:readGET /eventos
clientes:readGET /clientes
proveedores:readGET /proveedores
tareas:readGET /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ámetroDefaultReglas
page1Entero desde 1. Un valor inválido o menor a 1 se toma como 1.
limit50Entre 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.

FiltroValores
estadoPLANIFICANDO, 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, CORPORATIVO u OTRO.
  • presupuesto.totalCentavos es un entero en centavos: la centésima parte de la unidad de la moneda, para toda moneda. 150000050 son 1.500.000,50 pesos. Para mostrarlo, divide por 100. Todos los montos de la API van así, en enteros y con el sufijo Centavos en el nombre, para que nunca viajen decimales. moneda es un código ISO 4217 (ARS, USD, …); los montos no se convierten entre monedas.
  • presupuesto.totalCentavos es 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.estimada es 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.

FiltroValores
estadoLEAD, 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.

FiltroValores
estadoACTIVO, INACTIVO
categoriaTexto 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.

FiltroValores
estadosin_iniciar, en_progreso, validando, completada
eventoIdEl 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ímiteAlcanceAl pasarlo
120 requests por minutoPor API key429 con code: "RATE_LIMIT_API_KEY"
100 autenticaciones fallidas cada 15 minutosPor IP429 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 localhost y 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

EventoSe dispara al…data
cliente.creadocrear un cliente en el CRM{ id, nombreMostrar, estado }
proveedor.creadocrear un proveedor en el CRM{ id, nombreMostrar, categoria }
evento.creadocrear un evento, desde Eventos o desde la ficha de un cliente{ id, nombre, tipoEvento, estado }
tarea.creadacrear 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 }
pingusar 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:

HeaderContenido
X-Altar-EventEl evento (cliente.creado, …).
X-Altar-DeliveryEl id del cuerpo: identifica la entrega.
X-Altar-TimestampMomento del intento, en segundos desde epoch (UTC).
X-Altar-Signaturesha256=<firma> (ver abajo).
User-AgentAltar-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:

  1. Toma el cuerpo tal como llegó, sin parsearlo ni volver a serializarlo. Con otro orden de claves o espacios, la firma no coincide.
  2. Calcula HMAC-SHA256(secret, timestamp + "." + cuerpo).
  3. Compárala con lo que viene después de sha256= usando una comparación de tiempo constante.
  4. 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 301 o 302 cuenta 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 ping y 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ónPlan
Ver la lista de webhooks y eliminar unoCualquiera
Ver los eventos a los que se puede suscribir un webhookCualquiera
Crear, editar (nombre, URL, eventos, activo), rotar el secret, probar y ver el logEnterprise
Ver la lista de keys y revocar unaCualquiera
Ver los scopes que se pueden asignar a una keyCualquiera
Crear una keyEnterprise

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

StatuscodeCuá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).
403ENTERPRISE_REQUIREDLa 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.
429RATE_LIMIT_API_KEYLa key pasó los 120 requests por minuto.
429API_KEY_BLOQUEADALa IP acumuló 100 autenticaciones fallidas en 15 minutos.
5xx—Error de Altar. Reintenta más tarde.

Gestión desde la app

StatuscodeCuándo
400WEBHOOK_URL_INVALIDALa 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.
403SOLO_OWNERQuien hace el pedido no es el dueño de la cuenta.
403ENTERPRISE_REQUIREDLa 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

  1. En Configuración → Integraciones, crea una API key con los scopes que necesites y guárdala.
  2. Prueba la conexión con GET https://app.altarsoftware.com/api/v1/me.
  3. Si quieres avisos, crea un webhook apuntando a tu servidor, guarda el secret y verifica la firma de cada envío.
  4. Usa Probar para confirmar que tu servidor responde 2xx.