Eliminar y archivar contactos

Dar de baja un contacto significaba una sola cosa: DELETE /v1/contacts/{contact} lo archivaba, y el archivado se rechazaba con 422 en cuanto alguno de sus roles tenía detrás facturas, contratos u ofertas de proveedor. No había forma de hacer desaparecer un contacto, ni de apartar uno que se hubiera usado alguna vez.

Ahora existen las dos operaciones, las dos están siempre permitidas y ninguna destruye el histórico fiscal.

Dos bajas, dos rutas

Las cuatro requieren contacts:delete. PUT /v1/contacts/{contact}/restore solo desarchiva; no recupera un contacto eliminado.

Cambio que rompe: DELETE y bulk-delete ahora eliminan

Si tu integración llamaba a DELETE /v1/contacts/{contact} o a POST /v1/contacts/bulk-delete para archivar un contacto, ahora lo elimina y no podrás deshacerlo desde la API. Lleva esas llamadas a POST /v1/contacts/{contact}/archive y POST /v1/contacts/bulk/archive.

DELETE /v1/contacts/{contact} responde 200 con el acuse de la eliminación en lugar del contacto:

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
    "object": "contact",
    "deleted": true
  }
}

Qué hace una eliminación, y qué no:

• El contacto desaparece del listado, la búsqueda, las opciones y los selectores, las estadísticas, la exportación, las actividades, la deduplicación de importaciones y la resolución de alias legacy, y ya no se puede usar en documentos nuevos.
• Su fila, sus roles, los perfiles direccionales, las cuentas bancarias, los alias legacy y todas las facturas, presupuestos, albaranes o facturas de compra que lo referencian se conservan intactos, y esos documentos siguen mostrando sus datos de cliente o de proveedor.
• Su NIF y su external_id quedan liberados, así que la misma identidad se puede volver a dar de alta como un contacto distinto.
• Eliminar un id desconocido, de otra empresa o ya eliminado devuelve 404 contact_not_found.

Archivar ya no se bloquea nunca

El 422 business_rule_violation con subcode: contact_has_commercial_references se retira: ninguna operación lo emite ya. Un contacto con facturas de compra, contratos u ofertas de proveedor se puede archivar, y archivar uno ya archivado devuelve 200 y conserva el primer archived_at.

Evento nuevo: contact.deleted

Suscríbete a contact.deleted en POST /v1/webhook-endpoints para enterarte de que un contacto ha salido de la aplicación. A diferencia de contact.archived y contact.restored, no lleva snapshot: ya no queda nada que leer.

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
  "object": "contact",
  "deleted": true
}

contact.archived y contact.restored no cambian.

MCP

Las cinco requieren contacts:delete y son destructive; delete_contact y bulk_delete_contacts constan además como irreversibles, así que un asistente las confirma antes de ejecutarlas. Consulta el catálogo de tools MCP.

Migración

1. Toda llamada cuya intención era «aparta este contacto» pasa de DELETE /v1/contacts/{contact} a POST /v1/contacts/{contact}/archive, y de POST /v1/contacts/bulk-delete a POST /v1/contacts/bulk/archive.
2. Los reintentos o el tratamiento de errores que ramificaban por subcode: contact_has_commercial_references sobran: archivar ya no falla por ese motivo.
3. Si usabas PUT /v1/contacts/{contact}/restore para deshacer un DELETE, archiva en su lugar. Restaurar un contacto eliminado es una operación de soporte sobre la base de datos, no una llamada de la API.
4. Consultar un contacto que has eliminado devuelve 404: trata ese código como «ya no existe», no como un fallo pasajero.

Lee Contactos.