Conectar un CRM con una plantilla

MonoPbx se conecta a un CRM sin código. Usted entrega al PBX una plantilla: una descripción breve en YAML o JSON de la API HTTP del CRM, con las credenciales que la plantilla nombra. El motor de plantillas la usa para cuatro cosas:

Qué	Cuándo ocurre
Búsqueda por número: encontrar el contacto de un número telefónico	Ventana emergente de pantalla y nombres de quien llama
Búsqueda: encontrar contactos por texto escrito	Búsqueda de contactos
Crear contacto: agregar un contacto al CRM	A petición de un usuario o de la API
Diario: registrar cada llamada terminada en el CRM	Automáticamente, para cada llamada externa terminada, con reintentos
Marcar con clic: convertir los números telefónicos del CRM en números marcables	Cuando un usuario marca un contacto

Este tutorial recorre una integración completa con un CRM de ejemplo llamado sample-crm. Reemplace los valores por los datos de su CRM.

Antes de empezar

Necesita:

• La dirección base de la API de su CRM. Debe ser https y pública, sin cadena de consulta ni credenciales en la dirección.
• Una clave de API o token del CRM, con permiso para leer y crear contactos y para escribir registros de llamadas.
• El permiso integrations:write en MonoPbx.

1. Entender la plantilla

Una plantilla tiene una estructura fija. Esta es una plantilla con búsqueda, diario y marcar con clic:

schema: mpbx.crm-template/v1          # required, exactly this value
id: sample-crm                        # lowercase letters, digits, - and _
name: Sample CRM
base_url: https://crm.example.com/api/v1
secrets: [api_token]                  # credentials the admin enters, write-only
operations:
  lookup:
    request:
      method: GET
      path: "/contacts/lookup?phone={{phone|digits}}"
      headers:
        Authorization: "Bearer {{secret.api_token}}"
    response:
      contacts: "$.data[*]"           # where the list of contacts is
      fields:
        id: "$.id"
        name: "$.full_name"           # required for lookup and search
        company: "$.account.name"
        email: "$.email"
        phones: "$.phones[*]"
        url: "$.web_url"
      not_found_status: [404]         # "no such contact", not an error
    timeout_ms: 3000
  journal:
    request:
      method: POST
      path: "/calls"
      headers:
        Authorization: "Bearer {{secret.api_token}}"
      body:
        json:
          direction: "{{direction}}"
          number: "{{number|digits}}"
          started_at: "{{started_at}}"
          duration_secs: "{{duration_secs|num}}"
          disposition: "{{disposition}}"
          note: "Call {{call_id}}"
  click_to_call:
    default_country_code: "+52"       # added to numbers written nationally
    national_prefix: "01"             # removed from numbers written nationally

Puntos a tener en cuenta:

• Una plantilla son datos, no código. Solo puede usar los marcadores {{name}} listados para cada operación, {{secret.<name>}} para una credencial que declara, y los filtros |digits y |num. No hay condiciones, bucles ni scripts.
• Entrecomille cada valor que contenga {{ en YAML; de lo contrario, YAML lo interpreta como un mapa.
• La dirección se queda en el host de la plantilla. Una solicitud generada que saldría del host indicado en base_url se rechaza.
• JSON también funciona. Un documento que empieza con { se lee como JSON.
• Las plantillas miden como máximo 64 KiB. Los anclajes, alias y etiquetas de YAML se rechazan.

Para los marcadores exactos de cada operación, lea GET /api/v1/integrations/crm/reference. Lista los límites, las variables de cada operación y una plantilla de ejemplo completa.

2. Validar la plantilla

La validación revisa toda la plantilla e informa cada problema con su ubicación en el documento, por ejemplo operations.lookup.request.path. No hace ninguna llamada de red, así que puede ejecutarla antes de tener credenciales.

Envíe la plantilla a POST /api/v1/integrations/crm/validate (permiso integrations:write). El cuerpo exacto de la solicitud está en el documento OpenAPI en /api/v1/openapi.json. Corrija cada problema reportado y valide de nuevo. Crear o actualizar una integración ejecuta las mismas revisiones.

3. Crear la integración con sus credenciales

Cree la integración con POST /api/v1/integrations/crm. Envíe la plantilla y los valores de credencial para cada nombre listado en secrets. Se necesita el permiso integrations:write.

• Las credenciales son solo de escritura. Se sellan con la clave de su empresa al guardar, ninguna ruta las devuelve, y nunca aparecen en los registros ni en el registro de auditoría. Las lecturas solo listan los nombres de las credenciales y si cada una está definida.
• Para cambiar credenciales después, envíe todas de nuevo con PUT /api/v1/integrations/crm/{id}/credentials.
• Si una edición mueve la plantilla a otra dirección (esquema, host o puerto de base_url), las credenciales guardadas se eliminan y la integración se apaga, para que los valores solo puedan enviarse a la dirección que aprobó su dueño.

Anote el id de la integración; lo necesitará en los pasos siguientes.

4. Usar la consola de pruebas

La consola de pruebas ejecuta una operación con las variables que usted indique y le muestra lo que ocurrió.

POST /api/v1/integrations/crm/{id}/test ejecuta una operación. Empiece con dry_run: true: construye la solicitud y la muestra, con las credenciales mostradas como <name>, pero no envía nada. Esta es la forma más segura de revisar los marcadores.

Después ejecute la operación de verdad, por ejemplo una búsqueda por un número telefónico conocido. La respuesta muestra la solicitud, el código de estado del CRM, la latencia y los contactos que leyó la plantilla.

:::caution La consola de pruebas llama al CRM real Una ejecución de create_contact crea un contacto, y una ejecución de journal escribe un registro. Use un contacto de prueba o una cuenta de prueba en el CRM. La consola permite como máximo 20 ejecuciones por empresa por minuto. :::

5. Encender la integración

Encienda la integración (PATCH /api/v1/integrations/crm/{id}). Una integración encendida se usa para búsquedas, búsquedas de texto y registro en el diario.

Revise su estado con GET /api/v1/integrations/crm. Cada integración muestra uno de estos estados:

Estado	Significado
disabled	Apagada.
needs_credentials	Una credencial que nombra la plantilla no tiene valor.
unknown	Encendida, pero todavía no se ha llamado.
healthy	La última llamada funcionó.
degraded	Una o dos llamadas seguidas fallaron.
failing	Tres o más llamadas seguidas fallaron.

Una llamada que nunca salió del PBX, como un problema de plantilla o de credencial faltante, no cuenta contra la salud del CRM.

6. Cómo se comporta el diario

Cada llamada externa terminada (entrante o saliente, con número telefónico) se convierte en un trabajo del diario para cada integración habilitada cuya plantilla tenga una operación journal. El PBX envía el trabajo en segundo plano:

• Un trabajo que falla por una razón temporal (problemas de red, tiempo de espera, respuesta 408, 425, 429 o 5xx) se reintenta después de 30 segundos, 2 minutos, 10 minutos, 1 hora y 4 horas. Después de seis intentos queda fallido.
• Un trabajo que el CRM rechaza (cualquier otro 4xx, una dirección bloqueada, una plantilla que no puede construir la solicitud, o credenciales faltantes) queda fallido de inmediato.
• Un trabajo fallido puede volver a intentarse con POST /api/v1/integrations/crm/jobs/{id}/retry. Los trabajos fallidos se guardan 30 días.
• Una integración apagada mantiene sus trabajos en espera hasta que se vuelva a encender.

Si la operación de diario usa contact_id, y la plantilla también tiene búsqueda, el PBX busca primero el número para obtener el id de contacto del CRM.

Use GET /api/v1/integrations/crm/{id}/log?filter=outcome:eq:error para el registro de errores. El registro guarda un código de error de máquina, el estado HTTP y la latencia, y el número o texto enmascarado a sus últimos cuatro caracteres. Nunca guarda un cuerpo de respuesta, una URL ni una credencial.

Permisos

Acción	Permiso
Ver integraciones, el registro y el estado	integrations:read
Crear, cambiar, probar, validar y reintentar	integrations:write
Buscar y consultar contactos	contacts:read

Lo que una plantilla todavía no puede hacer

• Flujos de actualización de OAuth. Una plantilla se autentica con las credenciales que nombra: claves de API, tokens de portador en un encabezado o en la cadena de consulta, o HTTP Basic. Para HTTP Basic, ingrese como credencial el user:password ya codificado en Base64 y escriba Authorization: "Basic {{secret.basic}}" en la plantilla.
• Conectores listos para CRM específicos están planeados sobre el mismo motor. Hasta entonces, escriba una plantilla para su CRM.