Documentación Ocamia
Herramientas y guías para integrar tu sitio, catálogo o aplicación con Ocamia: captura de leads, sincronización de información, conversaciones por WhatsApp y eventos.
Esta documentación es pública. No incluye procesos internos, credenciales, arquitectura privada ni datos de clientes. Para acceder a endpoints protegidos debes solicitar credenciales de integración.
Casos de uso
¿Qué quieres integrar?
Capturar leads desde una web
Envía prospectos desde una landing, formulario externo o campaña hacia Ocamia para iniciar atención comercial.
Ver guía →Sincronizar catálogo
Comparte productos, servicios, imágenes, precios y disponibilidad para que el asistente pueda recomendar mejor.
Ver guía →Conectar conversaciones
Crea experiencias de WhatsApp con contexto del negocio, respuestas guiadas y handoff a humano.
Ver guía →Primeros pasos
Elige el tipo de integración
Integración por API
Para equipos técnicos que quieren conectar sistemas propios, catálogos, eventos o formularios.
Ver guía →Integración con sitio existente
Para negocios con web propia, e-commerce, CMS o frontend personalizado.
Ver guía →Carga asistida
Para clientes sin equipo técnico: Ocamia puede recibir información y estructurarla.
Ver guía →Leads
Enviar leads desde una landing o formulario
Usa el endpoint de leads cuando un usuario deje sus datos en una web, campaña, formulario externo o experiencia propia. Ocamia usará esa información para iniciar una atención contextual según la configuración del negocio.
- • Nombre del negocio o persona interesada.
- • WhatsApp o correo de contacto.
- • Fuente del lead: landing, campaña, referido, evento o integración.
- • Mensaje o necesidad inicial.
POST /v1/leads
Authorization: Bearer ocamia_sk_test_xxx
{
"business_id": "bus_123",
"name": "Mítico Joyería",
"contact_name": "Laura",
"whatsapp": "+573001112233",
"source": "landing",
"message": "Quiero conectar mi catálogo con WhatsApp"
}Catálogo
Sincronizar productos o servicios
Comparte información estructurada para que Ocamia pueda responder preguntas, recomendar productos, explicar servicios y guiar al comprador con mejor contexto.
PUT /v1/businesses/bus_123/catalog
{
"items": [
{
"external_id": "sku_001",
"name": "Anillo plata tejido",
"description": "Hecho a mano en plata 925",
"price": 180000,
"currency": "COP",
"available": true,
"images": ["https://example.com/anillo.jpg"]
}
]
}Conversaciones
Conectar WhatsApp con contexto
Ocamia puede iniciar o continuar conversaciones asociadas a un negocio, preservando la fuente, el contexto del usuario y los eventos relevantes.
Sitios existentes
Integrarse sin migrar tu plataforma
Si tu negocio ya tiene una web en Next.js, WordPress, WooCommerce, Shopify, Laravel u otra tecnología, puedes conectar Ocamia mediante API, formularios, feeds de catálogo o eventos del sitio.
Autenticación
API keys y entornos
Las integraciones usan API keys emitidas para cada organización y entorno. Nunca publiques claves secretas en el navegador. Usa llaves de servidor y limita permisos según el caso de uso.
Authorization: Bearer ocamia_sk_test_xxx Content-Type: application/json X-Ocamia-Idempotency-Key: lead_123_2026_09_10
API
Endpoints principales
/v1/leadsCrea un lead desde una landing, campaña, formulario externo o sistema aliado.
/v1/businesses/{business_id}Consulta información pública y operativa autorizada de un negocio.
/v1/businesses/{business_id}/catalogSincroniza productos, servicios, categorías y disponibilidad.
/v1/conversationsInicia o sincroniza una conversación asociada a un cliente o lead.
/v1/eventsRegistra eventos relevantes como formulario enviado, producto visto o pedido iniciado.
/v1/webhooksLista los webhooks configurados para tu integración.
Webhooks
Recibir eventos de Ocamia
Los webhooks permiten reaccionar a cambios de estado, nuevas conversaciones, solicitudes de handoff, sincronizaciones de catálogo y eventos comerciales.
{
"event": "lead.created",
"id": "evt_01H...",
"created_at": "2026-09-10T20:00:00Z",
"data": {
"business_id": "bus_123",
"lead_id": "lead_456",
"source": "landing"
}
}Pruebas
Ambiente de pruebas
Antes de producción, prueba creación de leads, actualización de catálogo, recepción de webhooks, reintentos, errores esperados e idempotencia. Las credenciales de prueba no deben usarse en producción.
Buenas prácticas
Recomendaciones de integración
Errores
Formato de errores
{
"error": {
"code": "invalid_request",
"message": "whatsapp is required",
"request_id": "req_01H..."
}
}Soporte
Soporte para integraciones
¿Quieres integrar Ocamia con tu producto?
Solicita acceso de desarrollador y cuéntanos qué quieres conectar: leads, catálogo, WhatsApp, eventos o webhooks.
Solicitar accesoVersionamiento
Changelog
2026-09-10
Primera versión pública de Ocamia Developers: leads, catálogo, WhatsApp, autenticación, endpoints, webhooks, sandbox y buenas prácticas.