Un plan de CRM de QrX que incluya la API pública. La API pública forma parte de Business y Enterprise. Sin ella, una llamada cuya clave tiene los scopes de CRM se rechaza con 402, y una clave sin los scopes de CRM recibe primero 403 CRM_SCOPE_MISSING.

Una clave de API (clave de canal de venta) con los ámbitos de CRM marcados; consulta "Crea una clave de API con ámbitos" más abajo.

Los endpoints de tareas también necesitan la función Tareas, y los endpoints de negocios y embudos necesitan la función Negocios en tu plan.

crm.read: todas las llamadas GET (embudos, personas, empresas, negocios, tareas, actividades).

crm.write: todas las llamadas POST y PUT (crear y cambiar personas, empresas, negocios, tareas y notas, mover un negocio, completar una tarea). Un ámbito de escritura no incluye la lectura: marca ambos cuando necesites ambos.

Embudos: GET /pipelines (embudos con sus etapas: id, nombre, tipo y probabilidad).

Personas: GET /people, GET /people/{id}, POST /people, PUT /people/{id}.

Empresas: GET /companies, GET /companies/{id}, POST /companies, PUT /companies/{id}.

Negocios: GET /deals, GET /deals/{id}, POST /deals, PUT /deals/{id}, POST /deals/{id}/move.

Tareas: GET /tasks, GET /tasks/{id}, POST /tasks, PUT /tasks/{id}, POST /tasks/{id}/complete.

Actividades: GET /activities?recordType=person&recordId={id}. recordType es person, company o deal.

Notas: POST /notes.

Personas: primero las de actividad más reciente. q busca en nombres, direcciones de correo electrónico y números de teléfono. La lista muestra solo el correo electrónico y el teléfono principales; GET /people/{id} devuelve todos los puntos de contacto, etiquetas y campos personalizados.

Empresas: primero las de actividad más reciente. q busca en nombres y dominios.

Negocios: primero los actualizados más recientemente. Filtros: pipelineId, stageId, status (open, won o lost) y q.

Tareas: primero las más nuevas. Filtros: state (open o done), assigneeUserId, personId, companyId y dealId.

Idempotency-Key: cada llamada de creación (POST de personas, empresas, negocios, tareas y notas) necesita la cabecera Idempotency-Key con 8 a 80 caracteres: letras, dígitos y . _ : -. Envía de nuevo la misma clave para reintentar y recibes el primer resultado en lugar de un segundo registro. Usa una clave nueva para cada registro nuevo. Sin una clave válida, la llamada responde 400 IDEMPOTENCY_KEY_REQUIRED.

version: cada registro lleva una version. Un PUT, un movimiento de negocio y una finalización de tarea deben enviar la versión que leíste. Si alguien cambió el registro mientras tanto, recibes 409 CRM_CONFLICT: lee el registro de nuevo y reintenta con la versión nueva.

Persona: los campos incluyen firstName, lastName, jobTitle, companyId, lifecycleStageId, ownerUserId, language, country, emails, phones, tagIds y customFields. Una persona cuya dirección de correo electrónico o número de teléfono ya existe responde 409. Crear personas cuenta para el límite de personas de tu plan.

Empresa: name, domains, vatNumber, chamberNumber, campos de dirección, industry, sizeBand, website, ownerUserId, lifecycleStageId, tagIds y customFields.

Negocio: title, pipelineId, stageId, value, currency, expectedCloseOn, probability, ownerUserId, primaryPersonId, personIds, companyId, source, tagIds y customFields. Sin embudo ni etapa, el negocio va al embudo predeterminado. Un PUT no puede cambiar la etapa: usa POST /deals/{id}/move con toStageId, version y, para una etapa de pérdida, lostReasonId (y opcionalmente lostNote) cuando el embudo tiene motivos de pérdida.

Nota: POST /notes con recordType (person, company o deal), recordId y text. El texto es texto sin formato y se guarda como un párrafo.

400 IDEMPOTENCY_KEY_REQUIRED: falta la cabecera Idempotency-Key o tiene un formato incorrecto.

401 UNAUTHORIZED: no hay un token de acceso válido.

402: tu plan no incluye la API pública o la función, o CRM_PLAN_LIMIT_REACHED: se alcanzó un límite del plan, como el número de personas. Mejora el plan en PortalX.

403 CRM_SCOPE_MISSING: la clave no tiene crm.read ni crm.write. Marca el ámbito y espera 30 segundos.

404 CRM_NOT_FOUND: el registro no existe en tu organización.

409 CRM_CONFLICT: la versión está desactualizada (record_changed) o la persona ya existe (duplicate). Lee el registro de nuevo.

422 VALIDATION_FAILED: un campo no es válido, por ejemplo una versión que falta, un cursor no válido o una tarea sin asignado. El detail indica cuál.

crm/person_created

crm/deal_created

crm/deal_moved

crm/deal_won

crm/deal_lost

crm/task_completed

crm/automation_triggered: lo envía la acción de automatización Enviar un evento webhook.

403 en cada llamada al CRM. La clave tiene acceso completo o le falta el ámbito. Restringe la clave y marca los ámbitos de CRM.

402 en cada llamada al CRM. Tu plan no incluye la API pública del CRM. Forma parte de Business y Enterprise.

409 al actualizar. Lee el registro de nuevo y envía su version actual.

Creación de tarea rechazada. Comprueba que assigneeUserId pertenezca a tu organización y que el usuario pueda usar el CRM.

Registros duplicados tras un reintento. Reutiliza la misma Idempotency-Key para reintentar el mismo registro.