Merge branch 'master' of github.com:apigatewaycl/apigateway-api-client-php

Author: estebandelaf

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
 
     strategy:
       matrix:
-        php-version: ['8.4', '8.5']
+        php-version: ['8.5']
 
     steps:
       - name: Check out repository code
@@ -33,6 +33,7 @@ jobs:
         env:
           APIGATEWAY_API_TOKEN: ${{ secrets.APIGATEWAY_API_TOKEN }}
           TEST_CONTRIBUYENTE_RUT: ${{ vars.TEST_CONTRIBUYENTE_RUT }}
+          ADD_SKIPPED: true
         run: |
           composer tests-readonly
 

README.md

@@ -33,3 +33,4 @@ Enlaces
 - [Sitio web API Gateway](https://www.apigateway.cl).
 - [Código fuente en GitHub](https://github.com/apigatewaycl/apigateway-api-client-php).
 - [Paquete en Packagist](https://packagist.org/packages/apigatewaycl/apigateway-api-client).
+- [Documentación](https://api-client-php.docs.apigateway.cl/).

composer.json

@@ -17,20 +17,23 @@
     },
     "autoload": {
         "psr-4": {
-            "apigatewaycl\\api_client\\": "src/"
+            "apigatewaycl\\api_client\\": "src/",
+            "Tests\\": "tests/"
         }
     },
     "require": {
-        "php": "^8.4",
+        "php": "^8.5",
         "guzzlehttp/guzzle": "^7.10"
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.94",
-        "phpstan/phpstan": "^1.12",
+        "phpstan/phpstan": "^2",
         "phpunit/phpunit": "^13.0",
-        "vlucas/phpdotenv": "^5.6"
+        "vlucas/phpdotenv": "^5.6",
+        "phpstan/phpstan-phpunit": "^2"
     },
     "scripts": {
+        "install-docs":   "curl -L https://www.phpdoc.org/phpDocumentor.phar -o phpdoc.phar; chmod +x phpdoc.phar",
         "docs": "php tools/phpdocumentor run --config=phpdoc.xml",
         "tests": "vendor/bin/phpunit --configuration=phpunit.xml --no-coverage",
         "tests-readonly": "XDEBUG_MODE=coverage vendor/bin/phpunit --configuration=phpunit.xml --filter 'testListarActividadesEconomicas|testObtenerSituacionTributariaTercero|testListarUfAnual|testListarUfMensual|testListarUfDiario'",

docs/dev/unit-test.rst

@@ -5,9 +5,22 @@ Pruebas unitarias
   Al ejecutar pruebas, deberás tener configuradas las variables de entorno necesarias en el archivo test.env. Favor de duplicar test.env-dist, cambiar su nombre a test.env y rellenar las variables necesarias.
 
 Antes de empezar, debes configurar las siguientes variables de entorno:
+
+Para utilizar v1:
+.. code-block:: shell
+    APIGATEWAY_API_URL="https://legacy.apigateway.cl"
+    APIGATEWAY_API_TOKEN="token-apigateway"
+    APIGATEWAY_API_VERSION="v1"
+    CONTRIBUYENTE_RUT="66666666-6"
+    CONTRIBUYENTE_CLAVE="clave-sii"
+    TEST_VERBOSE=true
+    TEST_PERIODO=202401
+
+Para utilizar v2:
 .. code-block:: shell
     APIGATEWAY_API_URL="https://legacy.apigateway.cl"
-    API_GATEWAY_API_TOKEN="token-apigateway"
+    APIGATEWAY_API_TOKEN="token-apigateway"
+    APIGATEWAY_API_VERSION="v1"
     CONTRIBUYENTE_RUT="66666666-6"
     CONTRIBUYENTE_CLAVE="clave-sii"
     TEST_VERBOSE=true

docs/getting-started/setup.rst

@@ -1,49 +1,106 @@
 Configuración
 =============
 
-Para utilizar el cliente de API de API Gateway, se debe tener un token de usuario, generado y obtenido desde la cuenta de API Gateway.
+Para utilizar el cliente de API de API Gateway, se debe tener un token de usuario generado desde la cuenta de API Gateway.
 
 .. important::
-    El archivo test.env sólo sirve para usar con los test. Por lo que se deberán definir las variables de entorno por los siguientes dos métodos: Directo por consola (temporal), o definirlas directamente en el entorno (persistente).
+   El archivo ``test.env`` sólo sirve para usar con los test.
 
-En Linux o MacOS:
------------------
+Versiones de API
+----------------
 
-El token se almacena en una variable de entorno. Para almacenar en una variable de entorno, se debe escribir lo siguiente en consola:
+El cliente permite utilizar dos versiones de la API mediante variables de entorno.
+
+**API v1 (legacy)**
+
+- URL: ``https://legacy.apigateway.cl``
+
+**API v2 (recomendada)**
+
+- URL: ``https://app.apigateway.cl``
+
+.. note::
+   Si no se define ``APIGATEWAY_API_VERSION`` el cliente utilizará automáticamente **v2**.
+
+Variables de entorno
+--------------------
+
+Las siguientes variables deben definirse en el sistema:
+
+- ``APIGATEWAY_API_URL``
+- ``APIGATEWAY_API_VERSION``
+- ``APIGATEWAY_API_TOKEN``
+
+``APIGATEWAY_API_TOKEN`` es una cadena extremadamente larga. Guárdala en un lugar seguro.
+
+Linux o MacOS
+-------------
+
+**Configuración para API v1**
 
 .. code-block:: shell
+
     export APIGATEWAY_API_URL="https://legacy.apigateway.cl"
+    export APIGATEWAY_API_VERSION="v1"
     export APIGATEWAY_API_TOKEN="aqui-su-token-de-apigateway"
 
-- ``APIGATEWAY_API_TOKEN`` es una cadena de caracteres extremadamente larga. Almacena ese token en un lugar seguro y no lo compartas con nadie.
+**Configuración para API v2**
+
+.. code-block:: shell
+
+    export APIGATEWAY_API_URL="https://app.apigateway.cl"
+    export APIGATEWAY_API_VERSION="v2"
+    export APIGATEWAY_API_TOKEN="aqui-su-token-de-apigateway"
 
-Introducir en consola las variables de entorno almacena temporalmente las variables, y alternativamente, se puede modificar el archivo de configuración de shell en Linux (que se explicará a continuación), y añadir al final del archivo los comandos previamente introducidos. Añadir variables de entorno de esta forma es más persistente y no se repite su definición.
+Para hacerlo persistente:
 
-- Si se usa Linux, se deben añadir al archivo ``~/.bashrc`` los comandos previamente definidos.
-- Si se usa MacOS, se deben añadir al archivo ``~/.zshrc``.
+- Linux: añadir al archivo ``~/.bashrc``
+- MacOS: añadir al archivo ``~/.zshrc``
 
-El paso siguiente sólo se hace para usuarios de MacOS. Por último, ejecutar el comando en cuestión para efectuar los cambios.
+Luego ejecutar:
 
 .. code-block:: shell
+
     source ~/.zshrc
 
-En Windows:
------------
+Windows
+-------
 
-Para almacenar en una variable de entorno en Windows, hay varias alternativas. La primera es utilizando cmd, y para almacenarlas utilizando cmd, ejecuta en el buscador de Windows "cmd", y ejecuta los siguientes comandos:
+**CMD – API v1**
 
 .. code-block:: shell
+
     setx APIGATEWAY_API_URL "https://legacy.apigateway.cl"
+    setx APIGATEWAY_API_VERSION "v1"
+    setx APIGATEWAY_API_TOKEN "aqui-su-token-de-apigateway"
+
+**CMD – API v2**
+
+.. code-block:: shell
+
+    setx APIGATEWAY_API_URL "https://app.apigateway.cl"
+    setx APIGATEWAY_API_VERSION "v2"
     setx APIGATEWAY_API_TOKEN "aqui-su-token-de-apigateway"
 
-También se pueden definir utilizando Windows PowerShell, de una manera similar. Ejecuta en el buscador de Windows "PowerShell", y ejecuta los siguientes comandos:
+**PowerShell – API v1**
 
 .. code-block:: shell
+
     $Env:APIGATEWAY_API_URL = "https://legacy.apigateway.cl"
+    $Env:APIGATEWAY_API_VERSION = "v1"
     $Env:APIGATEWAY_API_TOKEN = "aqui-su-token-de-apigateway"
 
-Como alternativa para almacenar las variables de manera persistente, debes seguir los siguientes pasos:
+**PowerShell – API v2**
+
+.. code-block:: shell
+
+    $Env:APIGATEWAY_API_URL = "https://app.apigateway.cl"
+    $Env:APIGATEWAY_API_VERSION = "v2"
+    $Env:APIGATEWAY_API_TOKEN = "aqui-su-token-de-apigateway"
+
+.. important::
+    Como alternativa para almacenar las variables de manera persistente, debes seguir los siguientes pasos:
 
-1.  Abre el Panel de Control > Sistema > Configuración avanzada del sistema.
-2.  En la pestaña Opciones avanzadas, selecciona Variables de entorno.
-3.  Añade o modifica las variables en la sección de "Variables de usuario" o "Variables del sistema".
+    1.  Abre el Panel de Control > Sistema > Configuración avanzada del sistema.
+    2.  En la pestaña Opciones avanzadas, selecciona Variables de entorno.
+    3.  Añade o modifica las variables en la sección de "Variables de usuario" o "Variables del sistema".

docs/index.rst

@@ -44,4 +44,4 @@ Enlaces
 - `Sitio web API Gateway <https://www.apigateway.cl>`_
 - `Código fuente en GitHub <https://github.com/apigatewaycl/apigateway-api-client-php>`_
 - `Paquete en Packagist <https://packagist.org/packages/apigatewaycl/apigateway-api-client>`_
-- `Documentación <https://developers.apigateway.cl/>`_
+- `Documentación <https://api-client-php.docs.apigateway.cl/>`_

phpdoc.phar

@@ -10,17 +10,17 @@
     beStrictAboutCoverageMetadata="true"
     beStrictAboutOutputDuringTests="false"
     beStrictAboutChangesToGlobalState="true"
-    stopOnError="true"
-    stopOnFailure="true"
-    stopOnWarning="true"
-    stopOnDeprecation="true"
-    stopOnNotice="true"
-    failOnEmptyTestSuite="true"
-    failOnWarning="true"
-    failOnRisky="true"
-    failOnDeprecation="true"
-    failOnPhpunitDeprecation="true"
-    failOnNotice="true"
+    stopOnError="false"
+    stopOnFailure="false"
+    stopOnWarning="false"
+    stopOnDeprecation="false"
+    stopOnNotice="false"
+    failOnEmptyTestSuite="false"
+    failOnWarning="false"
+    failOnRisky="false"
+    failOnDeprecation="false"
+    failOnPhpunitDeprecation="false"
+    failOnNotice="false"
 >
     <source>
         <include>

phpunit.xml

@@ -44,8 +44,8 @@ class ApiBase extends ApiClient
      */
     public function __construct(
         array $credenciales = [],
-        string $token = null,
-        string $url = null
+        ?string $token = null,
+        ?string $url = null
     ) {
         parent::__construct($token, $url);
         $this->setupAuth($credenciales);
@@ -62,7 +62,11 @@ public function __construct(
     private function setupAuth(array $credenciales): void
     {
         $tipo = key($credenciales); // Detecta si es 'pass' o 'cert'
-        $datos = $credenciales[$tipo] ?? [];
+        $datos = [];
+
+        if ($tipo !== null && isset($credenciales[$tipo])) {
+            $datos = $credenciales[$tipo];
+        }
 
         $identificador = $datos['rut'] ??
         $datos['cert-data'] ??
@@ -129,9 +133,9 @@ private function setupAuth(array $credenciales): void
      * @return bool true si el RUT tiene un formato válido,false en caso
      * contrario.
      */
-    private function isAuthPass(string $rut): bool
+    private function isAuthPass(?string $rut): bool
     {
-        if (is_null($rut)) {
+        if ($rut === null) {
             return false;
         }
         // Expresión regular para validar el formato del RUT chileno
@@ -146,9 +150,9 @@ private function isAuthPass(string $rut): bool
      * @return bool true si la cadena es válida en Base64, false en caso
      * contrario.
      */
-    private function isAuthFileData(string $firmaElectronicaBase64): bool
+    private function isAuthFileData(?string $firmaElectronicaBase64): bool
     {
-        if (is_null($firmaElectronicaBase64)) {
+        if ($firmaElectronicaBase64 === null) {
             return false;
         }
         // Asegúrate de que la longitud de la cadena sea múltiplo de 4
@@ -189,9 +193,9 @@ private function isAuthFileData(string $firmaElectronicaBase64): bool
      * @param string $pemStr La cadena a validar.
      * @return bool true si la cadena tiene formato PEM válido, false en caso contrario.
      */
-    private function isAuthCertData(string $pemStr): bool
+    private function isAuthCertData(?string $pemStr): bool
     {
-        if (is_null($pemStr)) {
+        if ($pemStr === null) {
             return false;
         }
         // Expresión regular para validar el formato PEM