PHPackages phpcfdi/finkok - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. phpcfdi/finkok ActiveLibrary[API Development](/categories/api) phpcfdi/finkok ============== Librería para conectar con la API de servicios de FINKOK v0.6.1(3mo ago)2012.2k—2.9%10MITPHPPHP >=8.1CI passing Since Mar 29Pushed 3mo ago6 watchersCompare [ Source](https://github.com/phpcfdi/finkok)[ Packagist](https://packagist.org/packages/phpcfdi/finkok)[ Docs](https://github.com/phpcfdi/finkok)[ RSS](/packages/phpcfdi-finkok/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (12)Versions (27)Used By (0) phpcfdi/finkok ============== [](#phpcfdifinkok) [![Source Code](https://camo.githubusercontent.com/8a7c1a4ec2798fec1d14e94e0b5f3f7287ef75eb20be07770b5e5d81c7f42b3d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f736f757263652d706870636664692f66696e6b6f6b2d626c75653f6c6f676f3d676974687562)](https://github.com/phpcfdi/finkok)[![Packagist PHP Version Support](https://camo.githubusercontent.com/53018fd7e786e589269897623eca53d4c63e2476f7db58f6909de2183b39e48b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f706870636664692f66696e6b6f6b3f6c6f676f3d706870)](https://packagist.org/packages/phpcfdi/finkok)[![Discord](https://camo.githubusercontent.com/e7d280832b4bb781e0e83dc7b04440636ea6a67d076133da0938b79caab9d6dd/68747470733a2f2f696d672e736869656c64732e696f2f646973636f72642f3435393836303535343039303238333031393f6c6f676f3d646973636f7264)](https://discord.gg/aFGYXvX)[![Latest Version](https://camo.githubusercontent.com/398ab5db0efb6592b90f299f822029317a5f1a5de48c8014e497e1b0ea09614a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f706870636664692f66696e6b6f6b3f6c6f676f3d676974)](https://github.com/phpcfdi/finkok/releases)[![Software License](https://camo.githubusercontent.com/908194fb043cac4562cb333bb82d354a0bf35417e43ff0d6650ffa6bc336386c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f706870636664692f66696e6b6f6b3f6c6f676f3d6f70656e2d736f757263652d696e6974696174697665)](https://github.com/phpcfdi/finkok/blob/main/LICENSE)[![Build Status](https://camo.githubusercontent.com/0262ad6d010943eede37d091ebe9ac820dbb0e17070dfcd0155d5432dd9acbed/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f706870636664692f66696e6b6f6b2f6275696c642e796d6c3f6272616e63683d6d61696e266c6f676f3d6769746875622d616374696f6e73)](https://github.com/phpcfdi/finkok/actions/workflows/build.yml?query=branch:main)[![Reliability](https://camo.githubusercontent.com/503720e07c7d774d9e65038d724537bcde9c95cbda140ba475c53f8c3ef868fb/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d706870636664695f66696e6b6f6b266d65747269633d72656c696162696c6974795f726174696e67)](https://sonarcloud.io/component_measures?id=phpcfdi_finkok&metric=Reliability)[![Maintainability](https://camo.githubusercontent.com/0c8cea128f442dc60060995a7c95e307c79faa3b76761c91f31b92c2d09c3974/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d706870636664695f66696e6b6f6b266d65747269633d7371616c655f726174696e67)](https://sonarcloud.io/component_measures?id=phpcfdi_finkok&metric=Maintainability)[![Code Coverage](https://camo.githubusercontent.com/bcfddd79b8296f33d737be8d70c36a363918688f2b5319281b725bdad5d27be7/68747470733a2f2f696d672e736869656c64732e696f2f736f6e61722f636f7665726167652f706870636664695f66696e6b6f6b2f6d61696e3f6c6f676f3d736f6e617271756265636c6f7564267365727665723d6874747073253341253246253246736f6e6172636c6f75642e696f)](https://sonarcloud.io/component_measures?id=phpcfdi_finkok&metric=Coverage)[![Violations](https://camo.githubusercontent.com/ccd1e4b3c66aaeef6f917abd9e01b9b5123575543e50b689bcf0a97174a79bb9/68747470733a2f2f696d672e736869656c64732e696f2f736f6e61722f76696f6c6174696f6e732f706870636664695f66696e6b6f6b2f6d61696e3f666f726d61743d6c6f6e67266c6f676f3d736f6e617271756265636c6f7564267365727665723d6874747073253341253246253246736f6e6172636c6f75642e696f)](https://sonarcloud.io/project/issues?id=phpcfdi_finkok&resolved=false)[![Total Downloads](https://camo.githubusercontent.com/5ccba0b1cdaeec7f1b77aa4615cbc89b6f3dcc277b220176d5232eaf9706cc86/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f706870636664692f66696e6b6f6b3f6c6f676f3d7061636b6167697374)](https://packagist.org/packages/phpcfdi/finkok) > Librería para conectar con la API de servicios de FINKOK (México) 🇺🇸 The documentation of this project is in spanish as this is the natural language for intended audience. Acerca de phpcfdi/finkok ------------------------ [](#acerca-de-phpcfdifinkok) Esta librería es un esfuerzo de la comunidad de para tener un cliente que explote las funcionalidades ofrecidas por el integrador . No está relacionado con Finkok y Finkok es una marca registrada de FINKOK, SAPI DE CV. Instalación ----------- [](#instalación) Usa [composer](https://getcomposer.org/) ``` composer require phpcfdi/finkok ``` Ejemplo básico de uso --------------------- [](#ejemplo-básico-de-uso) ``` use PhpCfdi\Finkok\FinkokEnvironment; use PhpCfdi\Finkok\FinkokSettings; use PhpCfdi\Finkok\QuickFinkok; $settings = new FinkokSettings('user@host.com', 'secret', FinkokEnvironment::makeProduction()); $finkok = new QuickFinkok($settings); // el PreCFDI a firmar, podría venir de CfdiUtils ;) $creator->asXml() $precfdi = file_get_contents('precfdi-to-sign.xml'); $stampResult = $finkok->stamp($precfdi); // hasAlerts()) { // stamp es un objeto con propiedades nombradas foreach ($stampResult->alerts() as $alert) { echo $alert->id() . ' - ' . $alert->message() . PHP_EOL; } } else { file_put_contents($stampResult->uuid() . '.xml', $stampResult->xml()); // CFDI firmado } ``` Y también hay otros ejemplos explicados: - [Timbrado](docs/Ejemplos/Timbrado.md) - [Cancelación firmada de un UUID](docs/Ejemplos/CancelacionFirmada.md) Y todos los test de integración, donde se prueba la comunicación y respuestas contra la plataforma de pruebas. Se recomienda utilizar la clase `PhpCfdi\Finkok\QuickFinkok` para un uso rápido de los comandos de finkok, sin embargo, se pueden utilizar un modo totalmente explícito y granular por *comando*, *servicio* y *resultado*. Métodos implementados --------------------- [](#métodos-implementados) La librería utiliza un modelo basado en comando, servicio y resultado. El *comando* es la definición de la acción que queremos realizar, contiene todos los parámetros necesarios. El *servicio* es el encargado de usar ese comando como entrada, ejecutarlo en Finkok (vía SOAP) y construir un resultado a partir de la respuesta. El *resultado* son los datos que representa la respuesta. No hemos implementado intencionalmente los comandos que requieren transmitir la llave privada de un CSD (Certificado de Sello Digital) o de la eFirma/FIEL (Firma electrónica). No creemos que vayamos a implementarlos porque a) No es necesario y b) Es inseguro. ### Servicios de estampado [](#servicios-de-estampado) Finkok tiene dos métodos de firmado: `stamp` y `quickstamp`. - `stamp(Stamping\StampingCommand $command): Stamping\StampingResult` - `quickstamp(Stamping\StampingCommand $command): Stamping\StampingResult` El servicio `stamped` para revisar si previamente se generó un cfdi: - `stamped(Stamping\StampingCommand $command): Stamping\StampingResult` El servicio `stampQueryPending` por si estás usando `pending buffer` (que te recomiendo no hacerlo): - `stampQueryPending(Stamping\QueryPendingCommand $command): Stamping\QueryPendingResult` ### Servicios de cancelación [](#servicios-de-cancelación) Solo se pueden cancelar cfdi con esta librería usando `cancelSignature` porque es el único donde no tienes que transmitir información confidencial. - `cancelSignature(Cancel\CancelSignatureCommand $command): Cancel\CancelSignatureResult` Puedes consultar el estado de un CFDI usando `getSatStatus` (antes o después de cancelarlo) - `getSatStatus(Cancel\GetSatStatusCommand $command): Cancel\GetSatStatusResult` Y obtener el último acuse de recibo del SAT a una solicitud de cancelación con `getCancelReceipt`. Aunque recuerda que tener un acuse no significa que se haya cancelado, el acuse lo único que contiene es la respuesta de cancelación presentada al SAT. - `getCancelReceipt(Cancel\GetReceiptResult $command): Cancel\GetReceiptResult` Gracias a `getPendingToCancel` se puede obtener el listado de CFDI pendientes por cancelar por parte de un receptor. - `getPendingToCancel(Cancel\GetPendingCommand $command): Cancel\GetPendingResult` Se pueden obtener los UUID relacionados hijos (que el UUID consultado relaciona) y padres (que relacionan al UUID consultado) usando `getRelatedSignature`. Tal como el método `cancelSignature` este método requiere de un mensaje firmado. - `getRelatedSignature(Cancel\GetRelatedSignatureCommand $command): Cancel\GetRelatedSignatureResult` A su vez, se puede aceptar o rechazar una solicitud de cancelación usando `acceptRejectSignature`. Este método puede trabajar con varios UUID, pero Finkok recomienda que solo se realice uno a la vez. Tal como el método `cancelSignature` este método requiere de un mensaje firmado. - `acceptRejectSignature(Cancel\AcceptRejectSignatureCommand $command): Cancel\AcceptRejectSignatureResult` ### Utilerías y manejo de clientes [](#utilerías-y-manejo-de-clientes) Obtener la hora de Finkok (por si estás teniendo problemas de CFDI fuera de tiempo): - `datetime(): Utilities\DatetimeResult` Obtener un CFDI firmado con Finkok en los últimos 3 meses: - `downloadXml(Utilities\DownloadXmlCommand $command): Utilities\DownloadXmlResult` Obtener reportes de consumo de crédito y manejo de clientes: - `reportCredit(Utilities\ReportCreditCommand $command): Utilities\ReportCreditResult` - `reportTotal(Utilities\ReportTotalCommand $command): Utilities\ReportTotalResult` - `reportUuid(Utilities\ReportUuidCommand $command): Utilities\ReportUuidResult` - `registrationAdd(Registration\AddCommand $command): Registration\AddResult` - `registrationAssign(Registration\AssignCommand $command): Registration\AssignResult` - `registrationEdit(Registration\EditCommand $command): Registration\EditResult` - `registrationSwitch(Registration\SwitchCommand $command): Registration\SwitchResult` - `registrationObtain(Registration\ObtainCommand $command): Registration\ObtainResult` - `registrationCustomers(Registration\ObtainCustomersCommand $command): Registration\ObtainCustomersResult` ### Manifiestos y contrato [](#manifiestos-y-contrato) Para obtener los contratos y enviar las firmas están `getContracts` y `signContracts`respectivamente. - `getContracts(Manifest\GetContractsCommand $command): Manifest\GetContractsResult` - `signContracts(Manifest\SignContractsCommand $command): Manifest\SignContractsResult` ### Retenciones [](#retenciones) Los CFDI de Retenciones e información de pagos (RET) siguen un estándar más parecido a CFDI 3.2. Su cancelación es inmediata (al contrario de la solicitud de cancelación actual). - `stamp(Retentions\StampCommand $command): Retentions\StampResult` - `stamped(Retentions\StampedCommand $command): Retentions\StampedResult` - `cancelSignature(Retentions\CancelSignatureCommand $command): Retentions\StampedResult` Para descargar una retención debe usar el servicio `Utilerias`, método `get_xml` que está implementado previamente. Igualmente, se ha creado el método `QuickFinkok::retentionDownload($uuid, $rfc)` para simplificar su implementación. ### Ayuda para firmado XML para SAT y Finkok [](#ayuda-para-firmado-xml-para-sat-y-finkok) Esta librería implementa el firmado CSD de los mensajes con el SAT para Cancelar, Obtener UUID relacionados y Aceptación o rechazo de solicitud de cancelación. Toda la lógica involucrada en la creación de los XML firmados se encuentra en la librería [`phpcfdi/xml-cancelacion`](https://github.com/phpcfdi/xml-cancelacion). También implementa el firmado con FIEL de *manifiestos* con Finkok. Para estas tareas se han creado los siguientes objetos que permiten realizar el firmado de la información: - `Helpers\CancelSigner`: Ayuda a firmar una solicitud de cancelación. - `Helpers\GetRelatedSigner`: Ayuda a firmar una solicitud de información de UUID relacionados. - `Helpers\AcceptRejectSigner`: Ayuda a firmar una respuesta de cancelación de 1 UUID. - `Helpers\DocumentSigner`: Ayuda a firmar los documentos de *manifiesto* de Finkok. A su vez, estos métodos utilizan la librería [`phpcfdi/credentials`](https://github.com/phpcfdi/credentials)para poder crear las firmas y la información requerida por el SAT o Finkok. La clase `QuickFinkok` ahorra el proceso de firmar peticiones y lo hace de forma automática, sin embargo, se muestra el siguiente ejemplo de cancelación firmada de 1 UUID con certificado y llave privada en archivos. ``` use PhpCfdi\Credentials\Credential; use PhpCfdi\Finkok\Helpers\CancelSigner; use PhpCfdi\Finkok\Services\Cancel\CancelSignatureCommand; // el objeto con el que se van a firmar las solicitudes $credential = Credential::openFiles('certificate.cer', 'privateKey.pem', 'password'); // el firmador de datos $signer = new CancelSigner(['11111111-2222-3333-4444-000000000001']); $signedXml = $signer->sign($credential); // el comando a pasar al método Finkok::cancelSignature o al comando CancelSignatureService $cancelCommand = new CancelSignatureCommand($signedXml); ``` Notas de implementación ----------------------- [](#notas-de-implementación) Durante el proceso de implementación he creado diversas notas y documentos: - [Cancelación](docs/Cancelaci%C3%B3n.md): Información del proceso de cancelación, métodos, acuses, pending buffer, etc. - [Servicios](docs/Servicios.md): Documentación básica de servicios. - [Listado de servicios](docs/ListadoDeServicios.md): Listado de todos los servicios disponibles de Finkok y si están o no implementados, así como un listado de los servicios que no se implementarán. - [Registro de clientes](docs/RegistroDeClientes.md): Si vas a trabajar con la capacidad de Finkok de *sub-distribuidor*y así poder administrar los datos de clientes. - [Pruebas de integración](docs/PruebasDeIntegracion.md): Documentación de cómo funciona y como configurar el entorno de pruebas de integración. - Problemas encontrados: - [Cancelación de un CFDI recién creado](docs/issues/CancelSignatureServiceCancelarRecienCreado.md) - [Consumir `queryPending` con un CFDI recién creado](docs/issues/QueryPendingServiceUuidNoExistente.md) - [Consumir `stamp` para generar un doble estampado no devuelve los datos](docs/issues/StampServiceDobleEstampado.md) - Falta servicio que no requiera CSD/FIEL para aceptar o rechazar una solicitud de cancelación - Falta servicio que no requiera CSD/FIEL para obtener los CFDI relacionados - [El acuse de cancelación entregado al cancelar y al solicitar el acuse no coinciden](docs/issues/AcuseCancelacionNoCoincidente.md) - [Error de cancelación de retenciones 1308 - Certificado revocado o caduco](docs/issues/CancelacionRetencionesError1308.md) - [El valor `CodEstatus` está ausente en la cancelación de CFDI de Retenciones](docs/issues/CancelacionRetencionesCodEstatus.md) - [El método `Registration#Get` con `taxpayer_id` vacío no devuelve el listado de clientes](docs/issues/RegistrationGetNoList.md) - [Al timbrar con un texto `&` devuelve `705 - XML Estructura inválida`](docs/issues/StampAmpersand.md) Capturar conversación HTTP -------------------------- [](#capturar-conversación-http) Algunas veces, al reportar a Finkok un problema, nos solicitan la conversación HTTP (*Request* y *Response*) para poder revisar el problema sobre la información enviada. Esta librería genera mensajes utilizando *PSR-3: Logger Interface*, y se utiliza dentro del objeto `SoapFactory`para crear un `SoapCaller`. Este objeto envía dos tipos de mensajes: `LogLevel::ERROR` cuando ocurre un error al momento de establecer comunicación con los servicios, y `LogLevel::DEBUG` cuando se ejecutó una llamada SOAP. Ambos mensajes están representados como una cadena en formato JSON, por lo que, para leerla fácilmente es importante decodificarla. El formato JSON es mejor dado que permite analizar el texto y encontrar caracteres especiales, mientras que, al convertirlo a un texto más entendible para el humano, estos caracteres especiales se pueden esconder o interpretar de forma errónea. Se ofrece la clase `PhpCfdi\Finkok\Helpers\FileLogger` como una utilería de `LoggerInterface`que manda los mensajes recibidos a la salida estándar o a un archivo. También se ofrece la clase `PhpCfdi\Finkok\Helpers\JsonDecoderLogger` como una utilería de `LoggerInterface`que decodifica el mensaje JSON y luego lo convierte a cadena de caracteres usando la función `print_r()`, para después mandarlo a otro objeto `LoggerInterface`. En el siguiente ejemplo se muestra la forma recomendada para establecer el objeto `Logger`, también se muestra el uso de `JsonDecoderLogger` para realizar la conversión de JSON a texto plano y `FileLogger` para enviar el mensaje a un archivo específico. La clase `JsonDecoderLogger` puede generar pérdida de información, pero los mensajes son más entendibles, si deseas también incluir el mensaje JSON puedes usar `JsonDecoderLogger::setAlsoLogJsonMessage(true)`. ``` use PhpCfdi\Finkok\FinkokEnvironment; use PhpCfdi\Finkok\FinkokSettings; use PhpCfdi\Finkok\Helpers\FileLogger; use PhpCfdi\Finkok\Helpers\JsonDecoderLogger; $logger = new JsonDecoderLogger(new FileLogger('/tmp/finkok.log')); $logger->setAlsoLogJsonMessage(true); // enviar en texto simple y también en formato JSON $settings = new FinkokSettings('user@host.com', 'secret', FinkokEnvironment::makeProduction()); $settings->soapFactory()->setLogger($logger); ``` Si estás usando Laravel, ya cuentas con una implementación de `LoggerInterface`, por lo que te recomiendo usar: ``` /** @var \Psr\Log\LoggerInterface $logger */ $logger = app(\Psr\Log\LoggerInterface::class); // Encapsular el logger en el decodificador JSON: $logger = new \PhpCfdi\Finkok\Helpers\JsonDecoderLogger($logger); ``` Compatibilidad -------------- [](#compatibilidad) Esta librería se mantendrá compatible con al menos la versión con [soporte activo de PHP](https://www.php.net/supported-versions.php) más reciente. También utilizamos [Versionado Semántico 2.0.0](docs/SEMVER.md) por lo que puedes usar esta librería sin temor a romper tu aplicación. Versión de la libreríaVersión de PHPFecha de lanzamiento0.1.07.2, 7.3 y 7.42019-03-290.3.07.3, 7.4, 8.0, 8.1, 8.2 y 8.32021-03-180.6.08.1, 8.2, 8.3 y 8.42025-11-08Contribuciones -------------- [](#contribuciones) Las contribuciones con bienvenidas. Por favor lee [CONTRIBUTING](https://github.com/phpcfdi/finkok/blob/main/CONTRIBUTING.md) para más detalles y recuerda revisar el archivo de tareas pendientes [TODO](https://github.com/phpcfdi/finkok/blob/main/docs/TODO.md) y el archivo [CHANGELOG](https://github.com/phpcfdi/finkok/blob/main/docs/CHANGELOG.md). Copyright and License --------------------- [](#copyright-and-license) The phpcfdi/finkok library is copyright © [PhpCfdi](https://www.phpcfdi.com)and licensed for use under the MIT License (MIT). Please see [LICENSE](https://github.com/phpcfdi/finkok/blob/main/LICENSE) for more information. ### Health Score 54 — FairBetter than 97% of packages Maintenance80 Actively maintained with recent releases Popularity37 Limited adoption so far Community17 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 99.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~100 days Recently: every ~243 days Total 26 Last Release 103d ago PHP version history (3 changes)v0.1.0PHP >=7.2 v0.3.0PHP >=7.3 v0.6.0PHP >=8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/66964609?v=4)[eclipxe](/maintainers/eclipxe)[@Eclipxe](https://github.com/Eclipxe) --- Top Contributors [![eclipxe13](https://avatars.githubusercontent.com/u/1266852?v=4)](https://github.com/eclipxe13 "eclipxe13 (602 commits)")[![AndreyPootMay](https://avatars.githubusercontent.com/u/28898216?v=4)](https://github.com/AndreyPootMay "AndreyPootMay (2 commits)")[![aarongmx](https://avatars.githubusercontent.com/u/43938927?v=4)](https://github.com/aarongmx "aarongmx (1 commits)")[![ircsasw](https://avatars.githubusercontent.com/u/919978?v=4)](https://github.com/ircsasw "ircsasw (1 commits)") --- Tags satcfdiphpcfdifinkok ### Code Quality TestsPHPUnit Static AnalysisRector ### Embed Badge ![Health badge](/badges/phpcfdi-finkok/health.svg) ``` [![Health](https://phpackages.com/badges/phpcfdi-finkok/health.svg)](https://phpackages.com/packages/phpcfdi-finkok) ``` ### Alternatives [phpcfdi/sat-ws-descarga-masiva Librería para usar el servicio web del SAT de Descarga Masiva 16663.6k3](/packages/phpcfdi-sat-ws-descarga-masiva)[algolia/algoliasearch-client-php API powering the features of Algolia. 69433.0M114](/packages/algolia-algoliasearch-client-php)[phpcfdi/cfdi-sat-scraper Web Scraping para extraer facturas electrónicas desde la página del SAT 9018.0k](/packages/phpcfdi-cfdi-sat-scraper)[phpcfdi/xml-cancelacion Genera documentos de cancelación de CFDI firmados (XMLSEC) 1149.5k4](/packages/phpcfdi-xml-cancelacion)[phpcfdi/credentials Library to use eFirma (fiel) and CSD (sellos) from SAT 83152.0k7](/packages/phpcfdi-credentials)[facturapi/facturapi-php Facturapi's PHP client library 1543.5k](/packages/facturapi-facturapi-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)