Download the PHP package phpcfdi/sat-ws-descarga-masiva without Composer

On this page you can find all versions of the php package phpcfdi/sat-ws-descarga-masiva. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package sat-ws-descarga-masiva

phpcfdi/sat-ws-descarga-masiva

Source Code Packagist PHP Version Support Discord Latest Version Software License Build Status Reliability Maintainability Code Coverage Violations Total Downloads

Librería para usar el servicio web del SAT de Descarga Masiva

:us: The documentation of this project is in spanish as this is the natural language for intented audience.

:mexico: La documentación del proyecto está en español porque ese es el lenguaje principal de los usuarios. También te esperamos en el canal #phpcfdi de discord

Esta librería contiene un cliente (consumidor) del servicio del SAT de Servicio Web de Descarga Masiva de CFDI y Retenciones.

Instalación

Utiliza composer, instala de la siguiente forma:

Ejemplos de uso

Todos los objetos de entrada y salida se pueden exportar como JSON para su fácil depuración.

Creación el servicio

Ejemplo creando el servicio usando una FIEL disponible localmente.

Cliente para consumir los servicios de CFDI de Retenciones

Existen dos tipos de Comprobantes Fiscales Digitales, los regulares (ingresos, egresos, traslados, nóminas y pagos), y los CFDI de retenciones e información de pagos (retenciones).

Puede utilizar esta librería para consumir los CFDI de Retenciones. Para lograrlo construya el servicio con la especificación de ServiceEndpoints::retenciones().

Los constructores ServiceEndpoints::cfdi() y ServiceEndpoints::retenciones() agregan automáticamente la propiedad ServiceType al objeto. Esta propiedad será después utilizada el servicio para especificar el valor en la consulta antes de consumirla.

Aunque no es recomendado, también puedes construir el objeto ServiceEndpoints con direcciones URL del servicio personalizadas utilizando el constructor del objeto en lugar de los métodos estáticos.

Realizar una consulta

Una vez creado el servicio, se puede presentar la consulta, si se pudo presentar devolverá el identificador de la solicitud, y con este identificador se podrá continuar al servicio de verificación.

Parámetros de la consulta

Periodo (DateTimePeriod)

Fecha y hora de inicio y fin de la consulta. Si no se especifica crea un periodo del segundo exacto de la creación del objeto.

Tipo de descarga (DownloadType)

Especifica si la solicitud es de documentos emitidos DownloadType::issued() o recibidos DownloadType::received(). Si no se especifica utiliza el valor de emitidos.

Tipo de solicitud (RequestType)

Especifica si la solicitud es de Metadatos RequestType::metadata() o archivos XML RequestType::xml(). Si no se especifica utiliza el valor de Metadatos.

Tipo de comprobante (DocumentType)

Filtra la solicitud por tipo de comprobante. Si no se especifica utiliza no utiliza el filtro.

Tipo de complemento (ComplementoCfdi o ComplementoRetenciones)

Filtra la solicitud por la existencia de un tipo de complemento dentro del comprobante. Si no se especifica utiliza ComplementoUndefined::undefined() que excluye el filtro.

Hay dos tipos de objetos que satisfacen este parámetro, depende del tipo de comprobante que se está solicitando. Si se trata de comprobantes de CFDI Regulares entonces se usa la clase ComplementoCfdi. Si se trata de CFDI de retenciones e información de pagos entonces se usa la clase ComplementoRetenciones.

Estos objetos se pueden crear nombrados (ComplementoCfdi::leyendasFiscales10()), por constructor (new ComplementoCfdi('leyendasfisc')), o bien, por el método estático create (ComplementoCfdi::create('leyendasfisc')).

Además, se puede acceder al nombre del complemento utilizando el método label(), por ejemplo, echo ComplementoCfdi::leyendasFiscales10()->label(); // Leyendas Fiscales 1.0.

A su vez, este objeto ofrece un método estático getLabels(): array para obtener un arreglo con los datos, en donde la llave es el identificador del complemento y el valor es el nombre del complemento.

Estado del comprobante (DocumentStatus)

Filtra la solicitud por el estado de comprobante: Vigente (DocumentStatus::active()) y Cancelado (DocumentStatus::cancelled()). Si no se especifica utiliza DocumentStatus::undefined() que excluye el filtro.

UUID (Uuid)

Filtra la solicitud por UUID. Para crear el objeto del filtro hay que usar Uuid::create('96623061-61fe-49de-b298-c7156476aa8b'). Si no se especifica utiliza Uuid::empty() que excluye el filtro.

Filtrado a cuenta de terceros (RfcOnBehalf)

Filtra la solicitud por el RFC utilizado a cuenta de terceros. Para crear el objeto del filtro hay que usar RfcOnBehalf::create('XXX01010199A'). Si no se especifica utiliza RfcOnBehalf::empty() que excluye el filtro.

Filtrado por RFC contraparte (RfcMatch/RfcMatches)

Filtra la solicitud por el RFC en contraparte, es decir, que si la consulta es de emitidos entonces filtrará donde el RFC especificado sea el receptor, si la consulta es de recibidos entonces filtrará donde el RFC especificado sea el emisor.

Para crear el objeto del filtro hay que usar RfcMatch::create('XXX01010199A'). Si no se especifica utiliza una lista vacía RfcMatches::create() que excluye el filtro.

El servicio del SAT permite especificar hasta 5 RFC Receptores, al menos así lo establecen en su documentación. Sin embargo, al tratarse de receptores, solo se puede utilizar en una consulta de documentos emitidos. En el caso de una consulta de documentos recibidos, solo se utilizará el primero de la lista.

Por lo regular utilizará solamente los métodos QueryParameter::getRfcMatch(): RfcMatch y QueryParameter::withRfcMatch(RfcMatch $rfcMatch).

Sin embargo, si fuera necesario especificar el listado de RFC, se puede realizar de la siguiente manera:

O bien, utilizar una lista de RFC como cadenas de texto:

Acerca de RfcMatches

Este objeto mantiene una lista de RfcMatches, pero con características especiales:

Tipo de servicio (ServiceType)

Esta es una propiedad que bien se podría considerar interna y no necesitas especificarla en la consulta. Por defecto está no definida y con el valor null. Se puede conocer si la propiedad ha sido definida con la propiedad hasServiceType(): bool y cambiar con withServiceType(ServiceType): self.

No se recomienda definir esta propiedad y dejar que el servicio establezca el valor correcto según a donde esté apuntando el servicio.

Cuando se ejecuta una consulta, el servicio (Service) automáticamente define esta propiedad si es que no está definida estableciéndole el mismo valor que está definido en el objeto ServiceEndpoints. Si esta propiedad ya estaba definida, y su valor no es el mismo que el definido en el objeto ServiceEndpoints entonces se genera una LogicException.

Ejemplo de especificación de parámetros

En el siguiente ejemplo, se crea una consulta sin parámetros y posteriormente se van modificando. Los métodos no cambian la propiedad del objeto (no son set*), lo que hacen es crear una nueva instancia de la consulta con los nuevos valores (son with*).

Puede que los cambios del ejemplo no sean lógicos, es solo para ilustrar cómo se establecen los valores:

Ejemplo de consulta por UUID

En este caso se especifica solamente el UUID a consultar, en el ejemplo es 96623061-61fe-49de-b298-c7156476aa8b.

Nota: Todos los demás argumentos de la consulta son ignorados.

Verificar una consulta

La verificación depende de que la consulta haya sido aceptada.

Descargar los paquetes de la consulta

La descarga de los paquetes depende de que la consulta haya sido correctamente verificada.

Una consulta genera un identificador de la solicitud, la verificación retorna uno o varios identificadores de paquetes. Necesitas descargar todos y cada uno de los paquetes para tener la información completa de la consulta.

Lectura de paquetes

Los paquetes de Metadata y CFDI se pueden leer con las clases MetadataPackageReader y CfdiPackageReader respectivamente. Para fabricar los objetos, se pueden usar sus métodos createFromFile para crearlo a partir de un archivo existente o createFromContents para crearlo a partir del contenido del archivo en memoria.

Cada paquete puede contener uno o más archivos internos. Cada paquete se lee individualmente.

Lectura de paquetes de tipo Metadata

Lectura de paquetes de tipo CFDI

Información técnica

Acerca de la interfaz RequestBuilderInterface

El Servicio Web del SAT de Descarga Masiva requiere comunicación SOAP especial, con autenticación y mensajes firmados. Generar estos mensajes requiere de gran detalle porque si el mensaje contiene errores será inmediatamente rechazado.

La firma de estos mensajes es con la FIEL, así que se puede utilizar la clase FielRequestBuilder que junto con la clase Fiel y la librería phpcfdi/credentials hacen la combinación adecuada para firmar los mensajes.

Sin embargo, existen escenarios distribuidos donde lo mejor sería contar con la creación de estos mensajes firmados en un lugar externo, de esta forma la FIEL (la llave privada y contraseña) no se necesita exponer al exterior. Para estos (u otros) escenarios, es posible crear una implementación de RequestBuilderInterface que contenga la lógica adecuada y entregue los mensajes firmados necesarios para la comunicación.

Acerca de la interfaz WebClientInterface

Para hacer esta librería compatible con diferentes formas de comunicación se utiliza una interfaz de cliente HTTP. Tú puedes crear tu implementación para poderla utilizar.

Si lo prefieres -como en el ejemplo de uso- podrías instalar Guzzle composer require guzzlehttp/guzzle y usar la clase GuzzleWebClient.

Recomendación de fábrica del servicio

Te recomendamos configurar el framework de tu aplicación (Dependency Injection Container) o crear una clase que fabrique los objetos Service, RequestBuilder y WebClient, usando tus propias configuraciones de Fiel en caso de que tengas disponible el certificado, llave privada y contraseña.

Manejo de excepciones

Al trabajar con el lector de paquetes (PackageReader) o con la comunicación HTTP con el servidor web set SAT (WebClient), la librería puede lanzar excepciones que puedes atrapar y analizar, ya sea en el momento de implementación o para personalizar los mensajes de error.

Acerca del Servicio Web de Descarga Masiva de CFDI y Retenciones

El servicio se compone de 4 partes:

  1. Autenticación: Esto se hace con tu FIEL y la librería oculta la lógica de obtener y usar el Token.
  2. Solicitud: Presentar una solicitud incluyendo la fecha de inicio, fecha de fin, tipo de solicitud emitidas/recibidas y tipo de información solicitada (cfdi o metadata).
  3. Verificación: pregunta al SAT si ya tiene disponible la solicitud.
  4. Descargar los paquetes emitidos por la solicitud.

Una forma burda de entenderlo es: imagina que el servicio del SAT se compone de tres ventanillas con tres personas diferentes atendiendo cada una de estas ventanillas.

Información oficial

Notas importantes del web service:

Notas de uso

Se ha encontrado que la regla relacionada con las descargas de tipo CFDI no se aplica en la forma como está redactada. Sin embargo, se ha encontrado que la regla que sí aplica es: no solicitar en más de 2 ocasiones el mismo periodo. Cuando esto ocurre, el proceso de solicitud devuelve el mensaje "5002: Se han agotado las solicitudes de por vida".

Recuerda que, si se cambia la fecha inicial o final en al menos un segundo ya se trata de otro periodo, por lo que si te encuentras en este problema podrías solucionarlo de esta forma.

En consultas del tipo Metadata no se aplica la limitante mencionada anteriormente, por ello es recomendable hacer las pruebas de implementación con este tipo de consulta.

No se ha podido encontrar una constante para suponer el tiempo que puede tardar una consulta en regresar un estado de verificación exitosa y que los paquetes estén listos para descargarse.

En nuestra experiencia, entre más grande el periodo y más consultas se presenten más lenta es la respuesta, y puede ser desde minutos a horas. Por lo general es raro que excedan 24 horas. Sin embargo, varios usuarios han experimentado casos raros (posiblemente por problemas en el SAT) en donde las solicitudes han llegado a tardar hasta 72 horas para ser completadas.

Problemas conocidos

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.

Actualizaciones

Contribuciones

Las contribuciones son 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-ws-descarga-masiva library is copyright © PhpCfdi and licensed for use under the MIT License (MIT). Please see LICENSE for more information.


All versions of sat-ws-descarga-masiva with dependencies

PHP Build Version
Package Version
Requires php Version >=7.3
ext-openssl Version *
ext-dom Version *
ext-json Version *
ext-zip Version *
ext-mbstring Version *
ext-libxml Version *
phpcfdi/credentials Version ^1.1
phpcfdi/rfc Version ^1.1
eclipxe/enum Version ^0.2.0
eclipxe/micro-catalog Version ^0.1.2
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package phpcfdi/sat-ws-descarga-masiva contains the following files

Loading the files please wait ....