API y webhooks para desarrolladores
Con la API, tu sistema lee y carga datos de tu empresa en Keptmarks: las casas, los trabajos con su avance, los tickets de mantenimiento, el stock, los gastos por casa y las reservas. Con los webhooks, Keptmarks le avisa a tu sistema cuando pasa algo. Está incluida en los planes Profesional y Empresa.
Especificación OpenAPI 3.1app.keptmarks.com/api/v1/openapi.json
Autenticación
Creá una clave en Configuración, Integraciones, Claves de API. La clave completa se muestra una sola vez; Keptmarks guarda solo una huella. Mandala en cada pedido en la cabecera Authorization.
Cada clave es de una empresa y actúa con los permisos de la persona que la creó, recortados a los permisos que elegiste (por ejemplo, solo leer casas). Si esa persona pierde un permiso o se desactiva, la clave tampoco puede. Podés limitarla a ciertas direcciones IP y ponerle vencimiento.
curl https://app.keptmarks.com/api/v1/properties \
-H "Authorization: Bearer km_live_xxxxxxxx"Crear y cambiar
Las escrituras pasan por las mismas reglas que la app: crear un trabajo usa la guía de esa casa y las personas fijas, igual que en la pantalla. Con la cabecera Idempotency-Key, repetir el mismo pedido (por un corte de red) no lo hace dos veces: devuelve la primera respuesta con Idempotent-Replayed: true. La clave de idempotencia se guarda 30 días.
curl -X POST https://app.keptmarks.com/api/v1/jobs \
-H "Authorization: Bearer km_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 2f1c7c1e-job-0042" \
-d '{"property_id":"<uuid>","type":"cleaning","scheduled_date":"2026-11-02","scheduled_time_start":"10:00"}'Sincronizar reservas desde tu PMS
Mandá cada reserva con source (tu sistema) y external_id (su id en tu sistema). Si ya existe, se actualiza; si no, se crea, con su limpieza de salida si la pedís. Así podés reenviar todo sin duplicar.
curl -X POST https://app.keptmarks.com/api/v1/reservations \
-H "Authorization: Bearer km_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"source":"my_pms","external_id":"R-1029","property_id":"<uuid>",
"guest_name":"Ana","check_in_date":"2026-12-20","check_out_date":"2026-12-27",
"create_checkout_cleaning":true}'
# 201 la primera vez, 200 cuando source + external_id ya existianListas, paginación y fechas
Las listas devuelven hasta 200 registros (limit, 50 por defecto) ordenados por la fecha del último cambio. Para seguir, pasá el next_cursor que vino. Con updated_since traés solo lo que cambió desde una fecha: es la forma de sincronizar.
Las fechas van en ISO 8601 (AAAA-MM-DD para días). Cada respuesta trae time_zone, la zona horaria de la empresa, para interpretar fechas y horas locales.
curl "https://app.keptmarks.com/api/v1/jobs?from=2026-11-01&to=2026-11-30&status=approved&limit=100" \
-H "Authorization: Bearer km_live_xxxxxxxx"
# -> { "data": [...], "has_more": true, "next_cursor": "eyJ2Ijo...", "time_zone": "America/Costa_Rica" }
curl "https://app.keptmarks.com/api/v1/jobs?from=2026-11-01&to=2026-11-30&status=approved&limit=100&cursor=eyJ2Ijo..." \
-H "Authorization: Bearer km_live_xxxxxxxx"Errores
Los errores tienen siempre la misma forma. El code es estable y es lo que tiene que leer tu programa; el message está en inglés, o en español con Accept-Language: es.
Códigos frecuentes: unauthorized (401), key_revoked y key_expired (401), plan_required (402), insufficient_scope, forbidden e ip_not_allowed (403), not_found (404, también si el registro es de otra empresa), conflict (409), validation_error (422) y rate_limited (429).
{
"error": {
"code": "insufficient_scope",
"message": "This key does not have the jobs:write scope.",
"request_id": "8c1d..."
}
}Límites
120 pedidos por minuto por clave. Cada respuesta trae X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; al pasarte, 429 con Retry-After en segundos.
Webhooks
En Configuración, Integraciones, Webhooks, agregá una dirección https pública y elegí qué avisos recibir. Keptmarks manda un POST con el aviso en JSON: ids y los datos clave del registro, nunca datos de contacto ni secretos.
Cada envío va firmado: la cabecera Keptmarks-Signature trae la hora (t) y un HMAC-SHA256 (v1) del texto "t.cuerpo" con el secreto del webhook, que se muestra una sola vez al crearlo. Rechazá firmas de más de 5 minutos. Respondé 2xx rápido; si no, se reintenta a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h. Tras 15 fallos seguidos el webhook se apaga y se avisa a la administración. El mismo aviso puede llegar dos veces: usá su id para ignorar repetidos.
Avisos: job.created, job.started, job.completed, job.approved, ticket.created, ticket.updated, expense.created, supply.low_stock, reservation.created, reservation.updated, document.signed, inventory.item_damaged, asset.maintenance_due e incident.created. El botón "Enviar prueba" manda un webhook.test.
POST https://tu-sistema.com/keptmarks
Keptmarks-Signature: t=1792411200,v1=5f2b...
Keptmarks-Event: job.completed
Keptmarks-Event-Id: 6a0e...
Keptmarks-Delivery: 91c2...
{
"id": "6a0e...",
"type": "job.completed",
"api_version": "2026-10-15",
"created_at": "2026-11-02T16:40:11.000Z",
"organization_id": "...",
"data": { "job_id": "...", "property_id": "...", "type": "check_out", "status": "ready_for_review", "operator_status": "completed" }
}
import crypto from 'node:crypto'
// rawBody: el cuerpo tal como llego (string), antes de parsear el JSON.
export function verificar(secreto, rawBody, cabecera) {
const partes = Object.fromEntries(cabecera.split(',').map((p) => p.split('=')))
const t = Number(partes.t)
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false // vieja: posible repeticion
const esperada = crypto.createHmac('sha256', secreto).update(`${t}.${rawBody}`).digest('hex')
const a = Buffer.from(esperada, 'hex')
const b = Buffer.from(partes.v1 || '', 'hex')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}Ids de otros sistemas
Con /links guardás qué es cada registro en otro sistema: esta casa es el centro de costo CC-104 en SAP, este proveedor es el vendor 57 en QuickBooks. Un id externo es único por empresa, sistema y tipo.
Zapier y Make
En Zapier o Make, usá el módulo de webhooks ("Catch Hook" o "Custom webhook") para recibir los avisos de Keptmarks, y el módulo HTTP con la cabecera Authorization: Bearer km_live_... para leer o crear datos con la API.
Versiones
La API es la v1 (/api/v1). Dentro de la v1 solo se agregan cosas: rutas, campos y avisos nuevos. Tu programa tiene que ignorar los campos que no conoce. Un cambio que rompa algo sale como v2, con aviso previo.
Rutas
Todas relativas a https://app.keptmarks.com/api/v1. El detalle de cada campo está en la especificación OpenAPI.
| Método y ruta | Qué hace | Permiso de la clave |
|---|---|---|
| GET/ | La empresa, su zona horaria y los permisos de esta clave. | - |
| GET/properties | Lista de casas. | properties:read |
| GET/properties/{id} | Una casa con sus ambientes. | properties:read |
| GET/properties/{id}/rooms | Ambientes de una casa. | properties:read |
| GET/properties/{id}/stock | Stock actual de cada suministro en una casa. | supplies:read |
| GET/jobs | Lista de trabajos (limpiezas, mantenimiento, inspecciones). | jobs:read |
| GET/jobs/{id} | Un trabajo con el avance de su lista y quién lo hace. | jobs:read |
| POST/jobs | Crear un trabajo, con las mismas reglas que la app. | jobs:write |
| GET/tickets | Lista de tickets de mantenimiento. | tickets:read |
| GET/tickets/{id} | Un ticket de mantenimiento. | tickets:read |
| POST/tickets | Crear un ticket de mantenimiento. | tickets:write |
| PATCH/tickets/{id} | Cambiar el estado (y la prioridad) de un ticket. | tickets:write |
| GET/inventory/items | Artículos del inventario (muebles, equipos). | inventory:read |
| GET/supplies | Catálogo de suministros. | supplies:read |
| GET/supplies/movements | Movimientos de stock (reposiciones, consumos, ajustes). | supplies:read |
| POST/supplies/movements | Cargar una reposición o un consumo en una casa. | supplies:write |
| GET/expenses | Gastos, con su moneda y la casa como centro de costo. | expenses:read |
| GET/reservations | Lista de reservas. | reservations:read |
| GET/reservations/{id} | Una reserva. | reservations:read |
| POST/reservations | Crear una reserva o actualizarla si ya existe por source + external_id. | reservations:write |
| GET/providers | Proveedores (datos básicos). | providers:read |
| GET/owners | Dueño de cada casa. El contacto, solo si quien creó la clave puede editar casas. | owners:read |
| GET/team/hours | Horas trabajadas por persona y trabajo (hasta 93 días). | hours:read |
| GET/rentals/payments | Payments recorded for equipment rentals (recorded by the office: Keptmarks does not charge rentals). | rentals:read |
| GET/links | Vínculos entre ids de Keptmarks y de otros sistemas. | links:read |
| POST/links | Vincular un registro con su id en otro sistema. | links:write |
| DELETE/links/{id} | Quitar un vínculo. | links:write |
| GET/assets | List assets and equipment (machines, vehicles, tools). Empty when the module is turned off. | assets:read |
| GET/assets/{id} | Get an asset. | assets:read |
| GET/assets/{id}/fuel | Fuel fill-ups of a vehicle, with the computed fuel economy (km/L, full tank to full tank) of each fill-up that closes a segment, and a summary for the last 30 and 90 days. Amounts only when the key creator can see fleet spending. | assets:read |
| GET/fleet/fuel | Fuel fill-ups of every vehicle (for accounting and BI), with the vehicle name, plate and property. Amounts only when the key creator can see fleet spending. Empty while fleet phase 2 is not enabled. | assets:read |
| GET/incidents | List incidents. Never the names of the people involved or witnesses; injury details only when the key creator can see them. | incidents:read |
| GET/incidents/{id} | Get an incident (same privacy rules as the list). | incidents:read |
Cambios
- 2026-10-15 · Primera versión pública de la API v1, los webhooks firmados y los ids de otros sistemas.