Contactos unificados

Disponibilidad e identidad

Usa /v1/contacts para las integraciones nuevas. Un contacto puede ser cliente y proveedor sin duplicar su identidad fiscal. El acceso sigue limitado por la empresa autenticada y los scopes contacts:* de la clave; los roles no sustituyen los permisos de usuario.

Un contacto tiene una identidad fiscal y un UUID opaco en id. Sus roles acumulables son customer, supplier y lead, cada uno con estado active o inactive. El lead fiscal exige NIF válido o identificación fiscal alternativa; la captación prefiscal y las oportunidades CRM son funcionalidades futuras independientes. Asigna customer al contacto existente al convertirlo en cliente, sin duplicarlo. Los roles no conceden permisos de usuario.

Crear un contacto cliente o proveedor

Usa name, kind y un array explícito roles. Las escrituras reciben nombres de rol; las lecturas devuelven objetos de rol con estado y fechas. Reutiliza el mismo id para todos sus roles.

curl -X POST https://api.factuarea.com/v1/contacts \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Distribuciones Ejemplo SL","kind":"company","tax_id":"B12345674","roles":["customer","supplier"]}'

Consulta y filtros

Usa GET /v1/contacts con search para nombre, NIF, email, teléfono/móvil o referencia externa. Usa roles, role_match, role_status, kind, country_code, province, city, tags, has_email, has_phone y fechas de alta para filtros estructurados. La paginación usa limit y starting_after; consulta has_more antes de continuar.

Consulta GET /v1/contacts/options para obtener los valores disponibles. field=country devuelve el catálogo de países; country_code, province, city y tag devuelven valores presentes en los contactos de esa empresa. Los países usan códigos ISO alpha-2. Provincia y ciudad filtran por coincidencia exacta. Las etiquetas se normalizan y pertenecen a cada empresa.

Escritura sin perder configuración

Crea con POST /v1/contacts, incluyendo un array explícito de roles (puede estar vacío). Actualiza la identidad común por separado de las transiciones de rol, los perfiles de cliente/proveedor y las cuentas bancarias. Conserva ambos perfiles en contactos duales. La tarifa predeterminada está en customer_profile.default_price_list_uuid; los valores de compra pertenecen al perfil de proveedor. Usa UUID, nunca IDs numéricos internos.

Archivar no elimina el histórico fiscal. Desactivar conserva las asociaciones documentales e impide seleccionar ese rol para operaciones nuevas. No puedes retirar un rol con referencias; desactívalo. Respeta los requisitos de scope e idempotencia de cada operación en la referencia API.

Documentos, recurrentes y automatizaciones

Facturas de venta, presupuestos, albaranes y proformas resuelven la identidad de cliente. Facturas de compra, ofertas/productos del proveedor y contratos resuelven la identidad de proveedor. Conserva las asociaciones históricas al desactivar roles. Las programaciones recurrentes son independientes de las facturas emitidas: no son ingresos facturados, y las facturas generadas deben seguir vinculadas al contacto canónico. Las programaciones existentes y las asociaciones documentales históricas conservan su vínculo durante la migración.

La API pública expone únicamente /v1/contacts para las identidades de terceros. Guarda el UUID que devuelve esta API y conserva los snapshots documentales históricos. Suscríbete explícitamente a los eventos de contactos y deduplica las entregas por la identidad del evento.

SDKs, CLI y tools

El SDK expone el recurso contacts; la CLI, los comandos contacts. MCP expone las mismas operaciones con scopes contacts:read, contacts:write o contacts:delete. Comprueba que tu versión instalada los incluye antes de migrar. El asistente conversacional consulta contactos canónicos y abre su UI para escribir; no inventa un pipeline CRM.

Gestionar roles, perfiles, archivado y eliminación

Asigna roles con POST /v1/contacts/{contact}/roles/{role}. Cambia su estado con PUT /v1/contacts/{contact}/roles/{role}/status; incluye role y status en el body. Retira solo roles sin referencias con DELETE /v1/contacts/{contact}/roles/{role}.

Actualiza la identidad común con PUT /v1/contacts/{contact}. Modifica valores predeterminados mediante /customer-profile o /supplier-profile, y cuentas bancarias mediante /bank-accounts; son operaciones PUT. Los roles inactivos y los contactos archivados conservan su histórico.

POST /v1/contacts/{contact}/archive archiva el contacto y PUT /v1/contacts/{contact}/restore lo desarchiva; archivar está siempre permitido, incluso si el contacto tiene facturas, contratos u ofertas de proveedor. DELETE /v1/contacts/{contact} es otra operación: un borrado lógico que retira el contacto de todas las superficies de lectura y no se puede deshacer desde la API, mientras sus documentos permanecen intactos. Usa el is_archived devuelto para ofrecer la acción correcta; archivado y estado del rol son estados distintos. Lista los archivados con GET /v1/contacts?is_archived=1.

Identificadores en documentos

El contrato documental conserva los campos direccionales client_id y supplier_id. Envía el id del contacto canónico con rol customer o supplier activo, respectivamente. No renombres esos campos a contact_id. El servidor resuelve la proyección direccional dentro de la empresa autenticada.

Importación

Usa la previsualización de importación para revisar roles, conflictos de identidad y mapeos antes de importar. Usa POST /v1/contacts/census-verification para verificar un par español de nombre y NIF sin crear un contacto.