Skip to content

Commit 861dbbc

Browse files
SantiagoFiolSantiagoFiol
committed
Se ha separado el README.md en varias partes. El Readme ahora se ubica en la carpeta docs y para su uso debe ser generado usando una secuencia de instrucciones con phpdocumentor.
1 parent a7550ad commit 861dbbc

11 files changed

Lines changed: 333 additions & 37 deletions

File tree

‎.gitignore‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1-
vendor
2-
docs
1+
vendor/
32
tests/test.env
3+
4+
var/
5+
tools/
6+
build/
7+
8+
prueba-ejemplo.php

‎README.md‎

Lines changed: 0 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -7,41 +7,6 @@ LibreDTE: Cliente de API en PHP
77

88
Cliente para realizar la integración con los servicios web de [LibreDTE](https://www.libredte.cl) desde PHP.
99

10-
Instalación
11-
-----------
12-
13-
Ejecutar en la terminal:
14-
15-
```shell
16-
composer require libredte/libredte-api-client
17-
```
18-
19-
Documentación (dev)
20-
-------------------
21-
22-
Para crear la documentación se necesita tener instaladas las dependencias
23-
de composer, GraphViz en el sistema operativo y luego ejecutar:
24-
25-
```shell
26-
./vendor/bin/phpdoc -d ./src -t ./docs
27-
```
28-
29-
Pruebas unitarias (dev)
30-
-----------------------
31-
32-
Para ejecutar las pruebas unitarias se necesita tener instaladas las
33-
dependencias de composer y luego ejecutar:
34-
35-
```shell
36-
./vendor/bin/phpunit
37-
```
38-
39-
También es posible ejecutar una pruebas específica indicando el test. Ejemplo:
40-
41-
```shell
42-
./vendor/bin/phpunit --filter test_dte_facturar
43-
```
44-
4510
Licencia
4611
--------
4712

‎docs/dev/index.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Desarrollo
2+
==========
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
7+
unit-test

‎docs/dev/unit-test.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Pruebas unitarias
2+
=================
3+
4+
.. important::
5+
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.
6+
7+
Antes de empezar, debes configurar las siguientes variables de entorno:
8+
9+
.. code-block:: shell
10+
LIBREDTE_URL="https://libredte.cl"
11+
LIBREDTE_HASH="hash-libredte"
12+
LIBREDTE_RUT="66666666-6"
13+
14+
Para ejecutar las pruebas unitarias se necesita tener instaladas las dependencias de composer, y para hacer todas las pruebas, ejecutar lo siguiente:
15+
16+
.. code-block:: shell
17+
./vendor/bin/phpunit
18+
19+
También es posible ejecutar una pruebas específica indicando el test. Ejemplo:
20+
21+
.. code-block:: shell
22+
./vendor/bin/phpunit --filter test_dte_buscar_documento_emitido

‎docs/getting-started/example.rst‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
Ejemplo
2+
=======
3+
4+
El siguiente es un ejemplo básico de cómo obtener un documento DTE emitido usando el cliente de API de LibreDTE:
5+
6+
.. code-block:: php
7+
<?php
8+
9+
# Definición de directorio autoload. Necesario si se usa la versión de GitHub.
10+
require_once __DIR__ . '/vendor/autoload.php';
11+
12+
# Importación de biblioteca de LibreDTE
13+
use libredte\api_client\ApiClient;
14+
15+
# Instanciación de cliente de API
16+
$client = new ApiClient();
17+
18+
# RUT del emisor sin Dígito Verificador.
19+
$emisor_rut = 12345678;
20+
# Filtros a aplicar en la búsqueda de DTEs.
21+
$filtros = [
22+
'fecha_desde' => '2024-10-25',
23+
'fecha_hasta' => date('Y-m-d'),
24+
];
25+
26+
# Recurso a consumir.
27+
$resource = sprintf('/dte/dte_tmps/buscar/%d', $emisor_rut);
28+
29+
# Se efectua la solicitud HTTP y se guarda la respuesta. En esta variable están el estado, cuerpo, etc.
30+
$response = $client->post($resource, $filtros);
31+
32+
echo "Status: ".$response['status']['code']."\n";
33+
34+
if ($response['status']['code'] != 200) {
35+
echo $response['body']."\n";
36+
} else {
37+
$documentos = $response['body'];
38+
$dte_id = 'T'.$documentos[0]['dte'].'F'.$documentos[0]['folio'];
39+
echo "\n",'test_dte_buscar_documento_emitido() n_documentos ',count($documentos),"\n";
40+
echo "\n",'test_dte_buscar_documento_emitido() dte_id ',$dte_id,"\n";
41+
echo "\n",'test_dte_buscar_documento_emitido() dte_fecha ',$documentos[0]['fecha'],"\n";
42+
}
43+
44+
Desgloce de ejemplo
45+
-------------------
46+
47+
Antes de probar, integrar y/o utilizar el cliente de API, necesitas haber definido previamente las variables de entorno.
48+
49+
.. seealso::
50+
Para más información sobre este paso, referirse al la guía en Configuración.
51+
52+
Se empieza por importar e instanciar el cliente de API.
53+
54+
.. code-block:: php
55+
# Definición de directorio autoload. Necesario si se usa la versión de GitHub.
56+
require_once __DIR__ . '/vendor/autoload.php';
57+
58+
# Importación de biblioteca de LibreDTE
59+
use libredte\api_client\ApiClient;
60+
61+
# Instanciación de cliente de API
62+
$client = new ApiClient();
63+
64+
Luego, se definen las variables a utilizar.
65+
66+
.. code-block:: php
67+
# RUT del emisor sin Dígito Verificador.
68+
$emisor_rut = 12345678;
69+
# Filtros a aplicar en la búsqueda de DTEs.
70+
$filtros = [
71+
'fecha_desde' => '2015-01-01',
72+
'fecha_hasta' => date('Y-m-d'),
73+
];
74+
75+
Más adelante, se arma el recurso a utilizar, se consume, y se obtiene su respuesta HTTP.
76+
77+
.. code-block:: php
78+
# Recurso a consumir.
79+
$resource = sprintf('/dte/dte_tmps/buscar/%d', $emisor_rut);
80+
81+
# Se efectua la solicitud HTTP y se guarda la respuesta.
82+
$response = $client->post($resource, $filtros);
83+
84+
``$response`` contiene toda la información de la respuesta HTTP, desde el cuerpo hasta el código de estado.
85+
86+
Por último, se despliega en consola el resultado. Si el código de la respuesta HTTP no es 200, se mostrará el mensaje de error. Si es 200, se desplegarán los documentos consultados.
87+
88+
.. code-block:: php
89+
echo "Status: ".$response['status']['code']."\n";
90+
91+
if ($response['status']['code'] != 200) {
92+
echo $response['body']."\n";
93+
} else {
94+
$documentos = $response['body'];
95+
$dte_id = 'T'.$documentos[0]['dte'].'F'.$documentos[0]['folio'];
96+
97+
echo "\nDTEs Temporales: \n";
98+
echo "\n",'N DOCUMENTOS: ',count($documentos),"\n";
99+
echo "\n",'DTE ID: ',$dte_id,"\n";
100+
echo "\n",'DTE FECHA: ',$documentos[0]['fecha'],"\n";
101+
}
102+
103+
.. important::
104+
Este ejemplo solo funciona con DTEs temporales.
105+
106+
107+
.. seealso::
108+
Para saber más sobre los parámetros posibles y el cómo consumir las API, referirse a la `documentación de LibreDTE. <https://developers.libredte.cl/>`_

‎docs/getting-started/index.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Empezando
2+
=========
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
7+
legal
8+
install
9+
setup
10+
example

‎docs/getting-started/install.rst‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Instalación
2+
===========
3+
4+
Desde Composer:
5+
6+
Para obtener el cliente de la API, debe tener composer instalado, y ejecutar el siguiente comando en consola para instalar el cliente de API en PHP:
7+
8+
.. code-block:: shell
9+
composer require libredte/libredte-api-client
10+
11+
Desde GitHub:
12+
13+
Si estás utilizando la versión de GitHub, deberás instalar los paquetes necesarios para su funcionamiento. Para ello debes ejecutar lo siguiente en su lugar desde la carpeta del proyecto:
14+
15+
.. code-block:: shell
16+
composer install
17+
18+
.. important::
19+
Si el segundo paso no funciona, remueve composer.lock y vuelve a ejecutar composer install.
20+
21+
Requerimientos
22+
--------------
23+
24+
- PHP 7.3 o superior.
25+
26+
- Extensiones de PHP:
27+
- curl.
28+
- ext-curl.
29+
- guzzlehttp.
30+
- phpdotenv.
31+
- phpdocumentor.

‎docs/getting-started/legal.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Términos y Condiciones de Uso
2+
=============================
3+
4+
Este programa es software libre: usted puede redistribuirlo y/o modificarlo
5+
bajo los términos de la GNU Lesser General Public License (LGPL) publicada
6+
por la Fundación para el Software Libre, ya sea la versión 3 de la Licencia,
7+
o (a su elección) cualquier versión posterior de la misma.
8+
9+
Este programa se distribuye con la esperanza de que sea útil, pero SIN
10+
GARANTÍA ALGUNA; ni siquiera la garantía implícita MERCANTIL o de APTITUD
11+
PARA UN PROPÓSITO DETERMINADO. Consulte los detalles de la GNU Lesser General
12+
Public License (LGPL) para obtener una información más detallada.
13+
14+
Debería haber recibido una copia de la GNU Lesser General Public License
15+
(LGPL) junto a este programa. En caso contrario, consulte
16+
`GNU Lesser General Public License <https://raw.githubusercontent.com/libredte/libredte-api-client-php/master/COPYING>`_.
17+
18+
.. important::
19+
20+
Para utilizar el cliente de API de LibreDTE, necesitará una cuenta de LibreDTE. Al usar dicha cuenta, es obligatorio leer y aceptar por completo los `términos y condiciones de uso <https://www.libredte.cl/legal>`_.

‎docs/getting-started/setup.rst‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
Configuración
2+
=============
3+
4+
Para utilizar el cliente de API de LibreDTE, se debe tener un token de usuario, generado y obtenido desde la cuenta de LibreDTE.
5+
6+
.. important::
7+
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).
8+
9+
En Linux o MacOS:
10+
-----------------
11+
12+
El token se almacena en una variable de entorno. Para almacenar en una variable de entorno, se debe escribir lo siguiente en consola.
13+
14+
15+
.. code-block:: shell
16+
export LIBREDTE_URL="https://libredte.cl"
17+
export LIBREDTE_HASH="aqui-tu-hash-de-libredte"
18+
export LIBREDTE_RUT="66666666-6"
19+
20+
- ``LIBREDTE_HASH`` es una cadena de varios caracteres. Almacena ese token en un lugar seguro y no lo compartas con nadie.
21+
- ``LIBREDTE_RUT`` contiene tu RUT asociado a la cuenta de LibreDTE, con Dígito Verificador.
22+
23+
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.
24+
25+
- Si se usa Linux, se deben añadir al archivo ``~/.bashrc`` los comandos previamente definidos.
26+
- Si se usa MacOS, se deben añadir al archivo ``~/.zshrc``.
27+
28+
El paso siguiente sólo se hace para usuarios de MacOS. Por último, ejecutar el comando en cuestión para efectuar los cambios.
29+
30+
.. code-block:: shell
31+
source ~/.zshrc
32+
33+
En Windows:
34+
-----------
35+
36+
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:
37+
38+
.. code-block:: shell
39+
setx LIBREDTE_URL "https://libredte.cl"
40+
setx LIBREDTE_HASH "aqui-tu-hash-de-libredte"
41+
setx LIBREDTE_RUT "66666666-6"
42+
43+
También se pueden definir utilizando Windows PowerShell, de una manera similar. Ejecuta en el buscador de Windows "PowerShell", y ejecuta los siguientes comandos:
44+
45+
.. code-block:: shell
46+
$Env:LIBREDTE_URL="https://libredte.cl"
47+
$Env:LIBREDTE_HASH="aqui-tu-hash-de-libredte"
48+
$Env:LIBREDTE_RUT="66666666-6"
49+
50+
51+
Como alternativa para almacenar las variables de manera persistente, debes seguir los siguientes pasos:
52+
53+
1. Abre el Panel de Control > Sistema > Configuración avanzada del sistema.
54+
2. En la pestaña Opciones avanzadas, selecciona Variables de entorno.
55+
3. Añade o modifica las variables en la sección de "Variables de usuario" o "Variables del sistema".

‎docs/index.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
Docs: libredte-api-client-php
2+
==============
3+
4+
.. image:: https://poser.pugx.org/libredte/libredte-api-client/license
5+
:target: https://packagist.org/packages/libredte/libredte-api-client
6+
7+
.. image:: https://poser.pugx.org/libredte/libredte-api-client/downloads
8+
:target: https://packagist.org/packages/libredte/libredte-api-client
9+
10+
.. image:: https://poser.pugx.org/libredte/libredte-api-client/d/monthly
11+
:target: https://packagist.org/packages/libredte/libredte-api-client
12+
13+
Bienvenido a la documentación del cliente de API de LibreDTE.
14+
15+
.. toctree::
16+
:titlesonly:
17+
18+
getting-started/index
19+
features/index
20+
dev/index
21+
22+
LibreDTE es un proyecto que tiene como objetivo emitir y manejar los Documentos Tributarios Electrónicos con mucha más facilidad.
23+
24+
Aquí podrás encontrar la biblioteca escrita en lenguaje PHP para llamar a las APIs de LibreDTE. Este cliente normalmente requiere una cuenta en el SII para poder manejar las DTE que necesites gestionar o emitir.
25+
26+
Enlaces
27+
-------
28+
29+
- `Sitio web LibreDTE <https://www.libredte.cl>`_
30+
- `Código fuente en GitHub <https://github.com/LibreDTE/libredte-api-client-php>`_
31+
- `Paquete en Packagist <https://packagist.org/packages/libredte/libredte-api-client>`_
32+
- `Documentación <https://developers.libredte.cl/>`_

0 commit comments

Comments
 (0)