API

Documentación para desarrolladores

Ombudly es API-first: todo lo que hace el panel también lo puede hacer tu propio sistema. Conecta tu backend o tu frontend de atención al cliente para crear casos, seguir la conversación de cada ticket hasta que se cierre, y enterarte en tiempo real de cada cambio de estado.

Crear cuenta gratis Ver autenticación →

Autenticación

Una API key por integración

Desde tu panel, en Ajustes → API Keys, genera una key para tu backend. Enviala como header Authorization en cada request que requiera acceso administrativo — las mismas rutas que usa el panel.

curl https://<tu-dominio-de-api>/tenants/acme/cases \
  -H "Authorization: Bearer ombk_live_••••••••••••••••••••••"

Una key no caduca hasta que la revoques desde el panel — pensada para que tu backend quede conectado de forma permanente, sin depender de un login humano.

Casos

Reclamos, quejas y tickets

Crear un caso es público — así funciona el formulario embebible — pero leer la bandeja completa o moverlo de estado requiere tu API key.

POST/tenants/{tenantID}/casesPúblico

Crea un reclamo, queja o ticket. El campo type acepta reclamo, queja o ticket.

{
  "type": "reclamo",
  "country": "PE",
  "customer_name": "Ana Torres",
  "customer_email": "ana@correo.com",
  "body": "El pedido llegó incompleto"
}

→ 201 Created
{
  "id": "b3f2c6b0-...",
  "tenant_id": "acme",
  "type": "reclamo",
  "status": "open",
  "due_at": "2026-11-14T00:00:00Z",
  "created_at": "2026-10-15T00:00:00Z"
}

GET/tenants/{tenantID}/casesAPI key

Lista todos los casos del tenant — la bandeja que ve tu equipo en el panel.

→ 200 OK
[
  { "id": "b3f2c6b0-...", "status": "open", ... },
  { "id": "a1d8e4c2-...", "status": "resolved", ... }
]

GET/tenants/{tenantID}/cases/{caseID}Público

Obtiene un caso por ID. El UUID funciona como token de acceso — es lo que usa la página de seguimiento del cliente.

→ 200 OK
{
  "id": "b3f2c6b0-...",
  "type": "reclamo",
  "status": "open",
  "due_at": "2026-11-14T00:00:00Z",
  ...
}

PATCH/tenants/{tenantID}/cases/{caseID}API key

Cambia el estado del caso: open → in_review → resolved / closed.

{ "status": "in_review" }

→ 200 OK
{ "id": "b3f2c6b0-...", "status": "in_review", ... }

Conversación

Cada ticket abre un hilo

Un caso no es solo un registro: tiene una conversación con el cliente hasta que se resuelve. Tu backend puede leerla y responder en nombre de tu equipo.

GET/tenants/{tenantID}/cases/{caseID}/messagesPúblico

Devuelve el hilo completo del caso, en orden cronológico.

→ 200 OK
[
  { "author_kind": "client", "body": "¿Cuándo tienen respuesta?", ... },
  { "author_kind": "agent",  "body": "Estamos revisando tu caso", ... }
]

POST/tenants/{tenantID}/cases/{caseID}/messagesMixto

Publica un mensaje. author_kind: client es público (lo usa el cliente final); agent o system requieren tu API key — es la respuesta oficial que dispara el email al cliente.

{
  "author_kind": "agent",
  "author_name": "Soporte Acme",
  "body": "Ya identificamos el problema, lo resolvemos hoy"
}

→ 201 Created
{ "id": "f0c3...", "author_kind": "agent", ... }

Webhooks

Enterate en tiempo real

Registra una URL y Ombudly te avisa en el momento en que se crea un caso o cambia de estado — sin que tengas que estar consultando la API.

POST/tenants/{tenantID}/webhooksAPI key

Registra un webhook. events acepta case_created y case_statusChanged. Si definís secret, cada entrega llega firmada (HMAC-SHA256).

{
  "url": "https://tu-sistema.com/webhooks/ombudly",
  "secret": "tu-secreto",
  "events": ["case_created", "case_statusChanged"]
}

→ 201 Created
{ "id": "w1...", "url": "https://tu-sistema.com/...", "enabled": true, ... }

GET/tenants/{tenantID}/webhooksAPI key

Lista los webhooks configurados para el tenant.

→ 200 OK
[ { "id": "w1...", "url": "https://tu-sistema.com/...", ... } ]

DELETE/tenants/{tenantID}/webhooks/{webhookID}API key

Elimina un webhook.

→ 204 No Content

Tu propio frontend

Datos del tenant

Si vas a construir tu propio formulario de reclamos en vez de usar el nuestro embebible, este endpoint te da el logo, color de marca y mensaje de bienvenida que configuraste en el panel.

GET/tenants/{tenantID}Público

Información pública del tenant, incluyendo su personalización.

→ 200 OK
{
  "id": "acme",
  "name": "Acme S.A.C.",
  "logo_url": "https://.../logo.png",
  "primary_color": "#1a9c62",
  "welcome_message": "Cuéntanos qué pasó, te respondemos en 30 días calendario."
}

¿Necesitas algo que no está acá?

Si tu integración necesita algo puntual, escríbenos — estamos construyendo esto junto con las primeras empresas que lo usan.

Hablar con nosotros