README

Herramienta para obtener y generar un listado de las clasificaciones del catálogo de productos y servicios del SAT

🇺🇸 The documentation of this project is in Spanish, as this is the natural language for the intended audience.

Es posible que, lo único que buscas es el Listado de clasificaciones de productos y servicios del SAT, si es ese el caso, es mejor consumir el recurso phpcfdi/resources-pys, en donde el listado es actualizado automáticamente.

Acerca de phpcfdi/sat-pys-scraper

El SAT en el sitio de internet http://pys.sat.gob.mx/PyS/catPyS.aspx tiene publicada una clasificación de productos y servicios. Esta clasificación no pertenece oficialmente a los catálogos y no se encuentra publicada en ningún lugar.

Esta herramienta hace el scrap del sitio mencionado para obtener los 4 niveles de clasificación: Tipo, Segmento, Familia y Clase. Igualmente, la estructura se puede exportar como XML o como JSON.

Instalación usando composer

A diferencia de otras librerías o componentes, este proyecto es una herramienta, por lo que probablemente nunca tengas que instalar el proyecto como una dependencia. Sin embargo, se puede hacer para que realices la parte de obtener las clasificaciones del sitio del SAT, pero tú mismo te encargues de procesar la estructura y usarla para tus propios propósitos, como por ejemplo, almacenar en una base de datos.

composer require phpcfdi/sat-pys-scraper

Instalación usando Docker

Este proyecto provee un archivo Dockerfile para construir una imagen con todas sus dependencias. Se puede usar esta imagen para correr de forma local, para más información consulte el archivo README.Docker.md.

# clonado del proyecto
git clone https://github.com/phpcfdi/sat-pys-scraper.git

# construcción de la imagen de Docker
docker build -t sat-pys-scraper sat-pys-scraper/

# ejecución de la herramienta
docker run -it --rm sat-pys-scraper --help

Ayuda de sat-pys-scraper (script)

sat-pys-scraper - Crea un archivo con la clasificación de productos y servicios del SAT.

Sintaxis:
    sat-pys-scraper help|-h|--help
    sat-pys-scraper [--quiet|-q] [--json|-j JSON_FILE] [--xml|-x XML_FILE]

Argumentos:
    --xml|-x XML_FILE
        Establece el nombre de archivo, o "-" para la salida estándar, donde se envían
        los datos generados en formato XML.
    --json|-j JSON_FILE
        Establece el nombre de archivo, o "-" para la salida estándar, donde se envían
        los datos generados en formato JSON.
    --sort|-s SORT
        Establece el orden de elementos, default: key, se puede usar "key" o "name".
    --quiet|-q
        Modo de operación silencioso.

Notas:
    Debe especificar al menos un argumento "--xml" o "--json", o ambos.
    No se puede especificar "-" como salida de "--xml" y "--json" al mismo tiempo.

Acerca de:
    Este script pertenece al proyecto https://github.com/phpcfdi/sat-pys-scraper
    y mantiene la autoría y licencia de todo el proyecto.

Uso de la herramienta

Si usar el código de la herramienta, entonces es importante entender que la tarea trata de dos pasos:

1. Obtener del sitio del SAT el listado de tipos, segmentos, familias y clases.
2. Exportar el listado a un formato específico.

Para generar el listado de tipos, segmentos, familias y clases se usa el objeto Generator, que a su vez usa un objeto Scraper para realizar la descarga de información, que a su vez utiliza un objeto Client de GuzzleHttp.

En el siguiente ejemplo se muestra cómo generar la estructura e iterar sobre sus elementos.

• Al ejecutar Generator::generate() se devuelve un objeto de tipo Types.
• Se recorre la estructura con foreach.
• Se puede exportar usando XmlExporter::export().

<?php
use GuzzleHttp\Client;
use PhpCfdi\SatPysScraper\Generator;
use PhpCfdi\SatPysScraper\Scraper;
use PhpCfdi\SatPysScraper\XmlExporter;

$scraper = new Scraper(new Client());
$generator = new Generator($scraper);
$types = $generator->generate();
$types->sortByKey();

foreach ($types as $type) {
    printf("Tipo: %s - %s\n", $type->key, $type->name);
    foreach ($type as $segment) {
        printf("  Segmento: %s - %s\n", $segment->key, $segment->name);
        foreach ($segment as $family) {
            printf("    Familia: %s - %s\n", $family->key, $family->name);
            foreach ($family as $class) {
                printf("      Clase: %s - %s\n", $class->key, $class->name);
            }
        }
    }
}

$exporter = new XmlExporter();
$exporter->export('output.xml', $types);

Tipos de datos

Un objeto Types es una colección iterable de objetos de tipo Type. Un objeto Type contiene las propiedades key y name, y además es una colección iterable de objetos de tipo Segment. Un objeto Segment contiene las propiedades key y name, y además es una colección iterable de objetos de tipo Family. Un objeto Family contiene las propiedades key y name, y además es una colección iterable de objetos de tipo Classification. Un objeto Classification solamente contiene las propiedades key y name.

Todos los objetos de datos implementan JsonSerializable, por lo que puedes usar esta característica para exportar a formato JSON.

Excepciones

La clase Scraper y -por consecuencia- también la clase Generator generan excepciones. En el caso de una excepción de tipo HTTP se tira una excepción HttpException. En el caso de una excepción HTTP y tenga un código de error del servicio remoto se tira una excepción HttpServerException.

La jerarquía de excepciones es:

- PysException (interface)
    - HttpException (class)
        - HttpServerException (class)

Soporte

Puedes obtener soporte abriendo un ticket en Github.

Adicionalmente, esta librería pertenece a la comunidad PhpCfdi, así que puedes usar los canales oficiales de comunicación para obtener ayuda de la comunidad.

Compatibilidad

Esta librería se mantendrá compatible con al menos la versión con soporte activo de PHP más reciente.

También utilizamos Versionado Semántico 2.0.0 por lo que puedes usar esta librería sin temor a romper tu aplicación.

Contribuciones

Las contribuciones con bienvenidas. Por favor lee CONTRIBUTING para más detalles y recuerda revisar el archivo de tareas pendientes TODO y el archivo CHANGELOG.

Copyright and License

The phpcfdi/sat-pys-scraper tool is copyright © PhpCfdi and licensed for use under the MIT License (MIT). Please see LICENSE for more information.