Changelog
15/10/2026 · Clientes: nueva ruta /api/v4/customer

Clientes: nueva ruta /api/v4/customer

15/10/2026

La API de clientes tiene ya su versión en v4, con las mismas operaciones que documentábamos:

GET    https://api.saltra.es/api/v4/customer
POST   https://api.saltra.es/api/v4/customer
DELETE https://api.saltra.es/api/v4/customer/{customerID}
PUT    https://api.saltra.es/api/v4/customer/{customerID}/activate

Hasta hoy la documentación apuntaba a /api/web/v3/customer, que es la ruta que usa la propia plataforma Saltra. Su validación sigue al formulario de la web y, por eso, al crear un cliente exigía profile.codigo_postal y profile.parameters aunque la documentación los daba como opcionales. La v4 tiene validación propia de la API:

  • Obligatorios: name, access.email, profile.dni, profile.razon_social y al menos una cuenta en profile.account (regimen, cuenta y alias).
  • Opcionales: profile.codigo_postal, profile.parameters, access.password (si la envías, con password_confirmation), profile.direccion, profile.external_id, not_notify.
  • Representante legal: los cuatro campos de profile.parameters.representativeData (doc, name, surname, job_position) solo son obligatorios si envías representativeData.

Las respuestas tienen el mismo formato (success, message, data, status) y los errores de validación devuelven 422 con el detalle por campo en errors. Las herramientas MCP clients_* usan ya la v4.

Qué revisar en tu integración:

  • Cambia la URL base a https://api.saltra.es/api/v4/customer. El cuerpo de las peticiones no cambia.
  • /api/web/v3/customer sigue funcionando, pero es interna de la plataforma: su validación puede cambiar sin aviso cuando cambie la web. No construyas sobre ella.
  • perPage en el listado admite como máximo 50; si pides más, se devuelven 50.