Integración con CouchDB

Arquitectura de datos

Parrot CRM está construido sobre CouchDB, lo que significa que cada tenant tiene su propia base de datos CouchDB aislada. Esto brinda:

• Aislamiento total — tus datos no se mezclan con otros tenants
• Acceso directo — puedes consultar tus datos vía REST API
• Replicación — puedes replicar tus datos a otro servidor
• Portabilidad — puedes exportar y migrar tus datos fácilmente

Acceder a tu base de datos

Información de conexión

Tu base de datos se accede vía HTTP/JSON:

URL base: https://tu-empresa.cloud.parrot.software/main_tu-empresa

Credenciales

• Las credenciales se gestionan a través del token de sesión de Parrot CRM
• El token se almacena en localStorage bajo la clave dbt
• Cada request a la API incluye el header Authorization: Bearer <token>

REST API

Endpoints principales

Método	Endpoint	Descripción
GET	/_changes	Stream de cambios en tiempo real
GET	/{doc_id}	Obtener un documento por ID
PUT	/{doc_id}	Crear o actualizar un documento
DELETE	/{doc_id}?rev={rev}	Eliminar un documento
POST	/_bulk_docs	Crear/actualizar múltiples documentos
GET	/_find	Buscar documentos con selector
GET	/{design_doc}/_search/{index}	Búsqueda full-text
GET	/{design_doc}/_view/{view}	Consultar views

Ejemplos de API

Obtener un cliente

curl -H "Authorization: Bearer $TOKEN" \
  "https://tu-empresa.cloud.parrot.software/main_tu-empresa/client:client-ULID"

Crear un cliente

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "client:client-NEW-ULID",
    "type": "client",
    "name": "Nuevo Cliente",
    "email": "cliente@ejemplo.com",
    "phone": "+521234567890",
    "tags": ["vip"],
    "created": 1700000000000,
    "updated": 1700000000000
  }' \
  "https://tu-empresa.cloud.parrot.software/main_tu-empresa/"

Buscar clientes por email

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selector": {
      "type": "client",
      "email": "cliente@ejemplo.com"
    },
    "limit": 10
  }' \
  "https://tu-empresa.cloud.parrot.software/main_tu-empresa/_find"

Stream de cambios en tiempo real

curl -H "Authorization: Bearer $TOKEN" \
  "https://tu-empresa.cloud.parrot.software/main_tu-empresa/_changes?feed=continuous&since=now"

Tipos de documentos

Los documentos siguen el esquema descrito en Estructura de documentos.

Los IDs de documentos usan el formato tipo:ULID:

• client:client-ULID — cliente
• thread:thread-ULID — conversación
• msg:msg-ULID — mensaje
• sale:sale-ULID — venta
• invoice:invoice-ULID — factura
• macro:macro-ULID — macro
• prompt:prompt-ULID — prompt
• classifier:classifier-ULID — clasificador
• notification:notification-ULID — notificación
• log:log-ULID — log
• user:user-ULID — usuario

Views (vistas)

Parrot CRM crea vistas automáticas para consultas frecuentes:

View	Colección	Descripción
threads/byTag	threads	Por tag
threads/tags	threads	Tags únicos
clients/byInput	clients	Por canal de entrada
clients/byName	clients	Por nombre
timeline/clients	stream	Timeline por cliente
timeline/threads	stream	Timeline por thread
timeline/sales	stream	Timeline por ventas
search/sales	sales	Búsqueda de ventas
search/invoices	invoices	Búsqueda de facturas

Replicación

Puedes replicar tu base de datos CouchDB a otro servidor:

couchdb-push $COUCH_URL couchdb/$doc

Documentos que se pueden replicar:

• activities — actividades
• search — índice de búsqueda
• tags — etiquetas
• timeline — línea de tiempo
• threads — conversaciones
• stream — stream log
• clients — clientes
• assets — activos
• macros — macros
• invoices — facturas
• stats — estadísticas

Consideraciones importantes

Conflictos de escritura

• Múltiples usuarios pueden editar el mismo documento
• CouchDB maneja conflictos con _conflicts array
• Parrot CRM usa estrategias de resolución de conflictos

Versiones

• Cada documento tiene un _rev (revisión)
• Al actualizar, debes enviar el _rev actual
• Si el _rev no coincide, se devuelve un error 409

Performance

• Las búsquedas full-text usan índices de búsqueda
• Las queries por _id son las más rápidas
• Las queries con _find usan índices generados automáticamente

Seguridad

• Cada tenant tiene su propia base de datos
• Los datos están completamente aislados
• El acceso requiere un token válido