Download the PHP package raorsa/sage-middleware-client without Composer

Sage Middleware Client

Cliente PHP para consumir la API REST del middleware Laravel que hace de puente entre el ERP interno (SQL Server, tipo Sage) y aplicaciones externas (portal de cliente, apps de técnicos, etc.).

Este paquete no contiene lógica de negocio: cada clase es un wrapper fino sobre un grupo de endpoints del middleware — construye la URL, gestiona el login/token y el caché local, y decodifica la respuesta JSON. Toda la lógica real (filtros, cálculos, formateo de IDs) vive en el middleware.

• Requisitos: PHP >= 8.2
• Dependencias: symfony/http-client, raorsa/rw-file-cache, monolog/monolog
• Licencia: Apache-2.0

Instalación

Uso básico

Cada clase de negocio (Clients, Invoices, DeliveryNotesClients, DeliveryNotesProviders, OrdersClients, OrdersProviders, Jobs, Incentives, Articles, Apparatus, CustomClient) extiende Raorsa\SageMiddlewareClient\components\baseClient y se instancia con el método estático make():

make() crea una conexión (login/password/name) nueva; el login contra el middleware (POST /login) es perezoso: solo se dispara la primera vez que se necesita un token, y el token obtenido se cachea (ver "Caché y autenticación" más abajo).

Si ya tienes una connexion construida (por ejemplo, en tests, o para compartir conexión entre varias clases de negocio), usa mount():

Casi todos los métodos aceptan un último parámetro bool $cache = true para omitir el caché de esa llamada concreta ($clients->clients(false)).

Caché y autenticación

• El login se resuelve solo cuando hace falta un token: connexion::call() intenta primero con el token en memoria/caché; si el middleware responde 405, descarta el token y vuelve a autenticar.
• El token se guarda en el mismo caché de disco que las respuestas (wrappers\cache, basado en raorsa/rw-file-cache), con una vida de 6 días (baseClient::TOKEN_LIFE_TIME) — un margen intencionado por debajo de los 7 días de caducidad que el middleware aplica a los tokens Sanctum, para evitar reutilizar uno a punto de expirar.
• Las respuestas JSON de cada endpoint se cachean por su URL completa (cacheLife minutos, por defecto 10). Si una llamada al servidor falla pero hay una respuesta anterior en caché ("last"), baseClient::call() la devuelve igualmente como fallback.
• Los métodos callJson() devuelven false si la respuesta no es JSON válido o si la llamada falla (nunca lanzan excepción).

Clases disponibles

Cada tabla indica el método del cliente, el endpoint del middleware al que llama y qué devuelve. La semántica completa de cada endpoint (filtros de negocio, formato de identificadores compuestos, etc.) la define el middleware; aquí solo se documenta el contrato desde el punto de vista del cliente.

Clients — clientes del ERP

Invoices — facturas de cliente

DeliveryNotesClients / DeliveryNotesProviders — albaranes

Ambas clases comparten toda la lógica en la clase abstracta DeliveryNotes; solo cambia el prefijo de ruta (delivery para albaranes de cliente, delivery-provider para los de proveedor).

OrdersClients / OrdersProviders — pedidos

Ambas clases comparten toda la lógica en la clase abstracta Orders; solo cambia el prefijo de ruta (orders para pedidos de cliente, orders-provider para los de proveedor). A diferencia de los albaranes, un pedido todavía no se ha servido: no hay número de serie de aparato ni PDF asociado, por lo que no existen linesSN, emptyLines, download ni img.

Jobs — órdenes de trabajo (OT)

Incentives — incentivos SAT

Articles — artículos

Apparatus — aparatos

Estos endpoints no forman parte de la documentación de API compartida por el equipo de middleware; la tabla siguiente refleja únicamente el contrato tal como lo usa este cliente (rutas y parámetros), no las reglas de negocio del servidor.

CustomClient — llamadas ad-hoc

Para endpoints del middleware que aún no tienen wrapper dedicado, o para prototipar:

Testing

Los tests no llaman a un middleware real: usan Symfony\Component\HttpClient\MockHttpClient con respuestas fijas en tests/resources/{clase}/{test}.json (ver tests/Traits/baseTest.php). Al añadir un método nuevo a una clase de negocio, el patrón habitual es añadir un test que use Nombre::mount($this->createConnexion(__FUNCTION__), $this->log, $this->cache) y un fixture JSON correspondiente.

Licencia

Apache-2.0