Provisionar clientes

Antes de que un cliente pueda conectar WhatsApp o enviar campañas, necesita un espacio de trabajo del lado de Auphere. Lo creas con una sola llamada idempotente desde tu backend, normalmente donde tu producto crea el registro del cliente.

Tu blueprint de partner

En el alta, el equipo de Auphere configura un blueprint para tu cuenta de partner: qué vertical de agente reciben tus clientes (por ejemplo, un asistente de cobranza), qué connector conecta el agente con tu API, y si los clientes se activan solos al conectar WhatsApp. Provisionar clona ese blueprint para cada cliente nuevo — así todos arrancan con un agente probado, personalizado con los placeholders que tú controlas.

Crear o actualizar un cliente

POST /v1/partners/clients es idempotente por external_client_ref: llámalo tantas veces como quieras con la misma referencia. Requiere el scope provision.

POST https://api.auphere.com/v1/partners/clients
Authorization: Bearer ak_live_…
Content-Type: application/json

{
  "external_client_ref": "3f6c1a2e-9d41-4b7f-8f2a-0c5d9e1b7a44",
  "name": "Bodegón El Ávila",
  "timezone": "America/Caracas",
  "agent": {
    "placeholders": {
      "agent.name": "Sofía",
      "policies.admin_access.admin_phones": ["+584241234567"]
    }
  },
  "connector": {
    "credentials": { "entity_id": "<uuid>", "token": "<bearer>" },
    "meta": { "business_uuid": "<id del negocio en TU api>" }
  }
}

{
  "external_client_ref": "3f6c1a2e-9d41-4b7f-8f2a-0c5d9e1b7a44",
  "status": "provisioned",
  "whatsapp": { "status": "not_connected", "display_phone_number": null },
  "agent": { "status": "provisioned" },
  "connector_connected": true
}

external_client_refstringRequerido

Tu propio id estable del cliente. Lo usarás en todas las demás llamadas. No cambia nunca — usa el id que ya tiene tu base de datos.

namestringRequerido

Nombre del negocio del cliente. El agente lo usa cuando habla.

timezonestring

Zona horaria IANA, ej. America/Caracas. Se usa para horarios y agendas.

agent.placeholdersobject

Valores para los placeholders del blueprint. Las claves disponibles dependen de tu vertical — te pasamos la lista exacta en el alta.

connector.credentialsobject

Credenciales con las que el agente lee datos de tu API, guardadas cifradas. Re-provisionar las rota.

connector.metaobject

Datos de ruteo no secretos del connector, típicamente el id del cliente dentro de tu propio sistema.

Qué hace una llamada repetida

• Nunca re-crea el agente. Se conservan las personalizaciones posteriores (nueva versión del prompt, admins cambiados).
• Sí rota las credenciales del connector. Así es como envías un token nuevo para un cliente.
• Devuelve el mismo espacio de trabajo. Misma referencia, mismo cliente, siempre.

Por qué podrías recibir un 422

Un agente solo se promueve si puede trabajar desde el día uno, así que la provisión rechaza dos situaciones que si no fallarían en silencio delante de un usuario real.

Datos del negocio sin rellenar

Si un placeholder se queda sin valor, el agente le dictaría nuestro texto de relleno a un usuario real como si fuera su cuenta bancaria. El error nombra cada clave que falta.

{
  "detail": "Faltan datos del negocio para armar el agente. Envíalos en agent.placeholders. Pendientes: transferencia banco, transferencia número de cuenta"
}

Whitelist de administradores vacía

En verticales admin-only el agente responde solo a los teléfonos autorizados. Sin ninguno, el número recién conectado del cliente quedaría mudo para siempre — y nada en los logs parecería roto. Envía al menos un teléfono en E.164 con 7+ dígitos.