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 existian

Listas, 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 rutaQué hacePermiso de la clave
GET/La empresa, su zona horaria y los permisos de esta clave.-
GET/propertiesLista de casas.properties:read
GET/properties/{id}Una casa con sus ambientes.properties:read
GET/properties/{id}/roomsAmbientes de una casa.properties:read
GET/properties/{id}/stockStock actual de cada suministro en una casa.supplies:read
GET/jobsLista 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/jobsCrear un trabajo, con las mismas reglas que la app.jobs:write
GET/ticketsLista de tickets de mantenimiento.tickets:read
GET/tickets/{id}Un ticket de mantenimiento.tickets:read
POST/ticketsCrear un ticket de mantenimiento.tickets:write
PATCH/tickets/{id}Cambiar el estado (y la prioridad) de un ticket.tickets:write
GET/inventory/itemsArtículos del inventario (muebles, equipos).inventory:read
GET/suppliesCatálogo de suministros.supplies:read
GET/supplies/movementsMovimientos de stock (reposiciones, consumos, ajustes).supplies:read
POST/supplies/movementsCargar una reposición o un consumo en una casa.supplies:write
GET/expensesGastos, con su moneda y la casa como centro de costo.expenses:read
GET/reservationsLista de reservas.reservations:read
GET/reservations/{id}Una reserva.reservations:read
POST/reservationsCrear una reserva o actualizarla si ya existe por source + external_id.reservations:write
GET/providersProveedores (datos básicos).providers:read
GET/ownersDueño de cada casa. El contacto, solo si quien creó la clave puede editar casas.owners:read
GET/team/hoursHoras trabajadas por persona y trabajo (hasta 93 días).hours:read
GET/rentals/paymentsPayments recorded for equipment rentals (recorded by the office: Keptmarks does not charge rentals).rentals:read
GET/linksVínculos entre ids de Keptmarks y de otros sistemas.links:read
POST/linksVincular un registro con su id en otro sistema.links:write
DELETE/links/{id}Quitar un vínculo.links:write
GET/assetsList 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}/fuelFuel 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/fuelFuel 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/incidentsList 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.