{"id":36399475,"url":"https://github.com/phpcfdi/finkok","last_synced_at":"2026-02-06T04:00:47.121Z","repository":{"id":35097469,"uuid":"178476370","full_name":"phpcfdi/finkok","owner":"phpcfdi","description":"Librería para conectar con la API de servicios de FINKOK","archived":false,"fork":false,"pushed_at":"2026-02-04T19:07:25.000Z","size":990,"stargazers_count":20,"open_issues_count":0,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-02-05T07:14:06.000Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phpcfdi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-03-29T21:15:03.000Z","updated_at":"2026-02-04T19:07:32.000Z","dependencies_parsed_at":"2024-04-13T05:48:53.300Z","dependency_job_id":null,"html_url":"https://github.com/phpcfdi/finkok","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/phpcfdi/finkok","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpcfdi%2Ffinkok","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpcfdi%2Ffinkok/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpcfdi%2Ffinkok/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpcfdi%2Ffinkok/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phpcfdi","download_url":"https://codeload.github.com/phpcfdi/finkok/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpcfdi%2Ffinkok/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29149577,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T02:39:25.012Z","status":"ssl_error","status_checked_at":"2026-02-06T02:37:22.784Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-11T16:02:20.364Z","updated_at":"2026-02-06T04:00:47.074Z","avatar_url":"https://github.com/phpcfdi.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# phpcfdi/finkok\n\n[![Source Code][badge-source]][source]\n[![Packagist PHP Version Support][badge-php-version]][php-version]\n[![Discord][badge-discord]][discord]\n[![Latest Version][badge-release]][release]\n[![Software License][badge-license]][license]\n[![Build Status][badge-build]][build]\n[![Reliability][badge-reliability]][reliability]\n[![Maintainability][badge-maintainability]][maintainability]\n[![Code Coverage][badge-coverage]][coverage]\n[![Violations][badge-violations]][violations]\n[![Total Downloads][badge-downloads]][downloads]\n\n\u003e Librería para conectar con la API de servicios de FINKOK (México)\n\n:us: The documentation of this project is in spanish as this is the natural language for intended audience.\n\n## Acerca de phpcfdi/finkok\n\nEsta librería es un esfuerzo de la comunidad de \u003chttps://www.phpcfdi.com/\u003e para tener un cliente que explote\nlas funcionalidades ofrecidas por el integrador \u003chttps://www.finkok.com/\u003e.\n\nNo está relacionado con Finkok y Finkok es una marca registrada de FINKOK, SAPI DE CV.\n\n## Instalación\n\nUsa [composer](https://getcomposer.org/)\n\n```shell\ncomposer require phpcfdi/finkok\n```\n\n## Ejemplo básico de uso\n\n```php\nuse PhpCfdi\\Finkok\\FinkokEnvironment;\nuse PhpCfdi\\Finkok\\FinkokSettings;\nuse PhpCfdi\\Finkok\\QuickFinkok;\n\n$settings = new FinkokSettings('user@host.com', 'secret', FinkokEnvironment::makeProduction());\n$finkok = new QuickFinkok($settings);\n\n// el PreCFDI a firmar, podría venir de CfdiUtils ;) $creator-\u003easXml()\n$precfdi = file_get_contents('precfdi-to-sign.xml');\n\n$stampResult = $finkok-\u003estamp($precfdi); // \u003c- aquí contactamos a Finkok\n\nif ($stampResult-\u003ehasAlerts()) { // stamp es un objeto con propiedades nombradas\n    foreach ($stampResult-\u003ealerts() as $alert) {\n        echo $alert-\u003eid() . ' - ' . $alert-\u003emessage() . PHP_EOL;\n    }\n} else {\n    file_put_contents($stampResult-\u003euuid() . '.xml', $stampResult-\u003exml()); // CFDI firmado\n}\n```\n\nY también hay otros ejemplos explicados:\n\n- [Timbrado](docs/Ejemplos/Timbrado.md)\n- [Cancelación firmada de un UUID](docs/Ejemplos/CancelacionFirmada.md)\n\nY todos los test de integración, donde se prueba la comunicación y respuestas contra la plataforma de pruebas.\n\nSe recomienda utilizar la clase `PhpCfdi\\Finkok\\QuickFinkok` para un uso rápido de los comandos de finkok,\nsin embargo, se pueden utilizar un modo totalmente explícito y granular por *comando*, *servicio* y *resultado*.\n\n## Métodos implementados\n\nLa librería utiliza un modelo basado en comando, servicio y resultado.\nEl *comando* es la definición de la acción que queremos realizar, contiene todos los parámetros necesarios.\nEl *servicio* es el encargado de usar ese comando como entrada, ejecutarlo en Finkok (vía SOAP) y\nconstruir un resultado a partir de la respuesta.\nEl *resultado* son los datos que representa la respuesta. \n\nNo hemos implementado intencionalmente los comandos que requieren transmitir la llave privada de un\nCSD (Certificado de Sello Digital) o de la eFirma/FIEL (Firma electrónica).\nNo creemos que vayamos a implementarlos porque a) No es necesario y b) Es inseguro.\n\n### Servicios de estampado\n\nFinkok tiene dos métodos de firmado: `stamp` y `quickstamp`.\n\n* `stamp(Stamping\\StampingCommand $command): Stamping\\StampingResult`\n* `quickstamp(Stamping\\StampingCommand $command): Stamping\\StampingResult`\n\nEl servicio `stamped` para revisar si previamente se generó un cfdi:\n\n* `stamped(Stamping\\StampingCommand $command): Stamping\\StampingResult`\n\nEl servicio `stampQueryPending` por si estás usando `pending buffer` (que te recomiendo no hacerlo):\n\n* `stampQueryPending(Stamping\\QueryPendingCommand $command): Stamping\\QueryPendingResult`\n\n### Servicios de cancelación\n\nSolo se pueden cancelar cfdi con esta librería usando `cancelSignature` porque es el único\ndonde no tienes que transmitir información confidencial.\n\n* `cancelSignature(Cancel\\CancelSignatureCommand $command): Cancel\\CancelSignatureResult`\n\nPuedes consultar el estado de un CFDI usando `getSatStatus` (antes o después de cancelarlo)\n\n* `getSatStatus(Cancel\\GetSatStatusCommand $command): Cancel\\GetSatStatusResult`\n\nY obtener el último acuse de recibo del SAT a una solicitud de cancelación con `getCancelReceipt`.\nAunque recuerda que tener un acuse no significa que se haya cancelado, el acuse lo único que\ncontiene es la respuesta de cancelación presentada al SAT. \n\n* `getCancelReceipt(Cancel\\GetReceiptResult $command): Cancel\\GetReceiptResult`\n\nGracias a `getPendingToCancel` se puede obtener el listado de CFDI pendientes por cancelar por\nparte de un receptor.\n\n* `getPendingToCancel(Cancel\\GetPendingCommand $command): Cancel\\GetPendingResult`\n\nSe pueden obtener los UUID relacionados hijos (que el UUID consultado relaciona)\ny padres (que relacionan al UUID consultado) usando `getRelatedSignature`.\nTal como el método `cancelSignature` este método requiere de un mensaje firmado.\n\n* `getRelatedSignature(Cancel\\GetRelatedSignatureCommand $command): Cancel\\GetRelatedSignatureResult`\n\nA su vez, se puede aceptar o rechazar una solicitud de cancelación usando `acceptRejectSignature`.\nEste método puede trabajar con varios UUID, pero Finkok recomienda que solo se realice uno a la vez.\nTal como el método `cancelSignature` este método requiere de un mensaje firmado.\n\n* `acceptRejectSignature(Cancel\\AcceptRejectSignatureCommand $command): Cancel\\AcceptRejectSignatureResult`\n\n### Utilerías y manejo de clientes\n\nObtener la hora de Finkok (por si estás teniendo problemas de CFDI fuera de tiempo):\n\n* `datetime(): Utilities\\DatetimeResult`\n\nObtener un CFDI firmado con Finkok en los últimos 3 meses:\n\n* `downloadXml(Utilities\\DownloadXmlCommand $command): Utilities\\DownloadXmlResult`\n\nObtener reportes de consumo de crédito y manejo de clientes:\n\n* `reportCredit(Utilities\\ReportCreditCommand $command): Utilities\\ReportCreditResult`\n* `reportTotal(Utilities\\ReportTotalCommand $command): Utilities\\ReportTotalResult`\n* `reportUuid(Utilities\\ReportUuidCommand $command): Utilities\\ReportUuidResult`\n* `registrationAdd(Registration\\AddCommand $command): Registration\\AddResult`\n* `registrationAssign(Registration\\AssignCommand $command): Registration\\AssignResult`\n* `registrationEdit(Registration\\EditCommand $command): Registration\\EditResult`\n* `registrationSwitch(Registration\\SwitchCommand $command): Registration\\SwitchResult`\n* `registrationObtain(Registration\\ObtainCommand $command): Registration\\ObtainResult`\n* `registrationCustomers(Registration\\ObtainCustomersCommand $command): Registration\\ObtainCustomersResult`\n\n### Manifiestos y contrato\n\nPara obtener los contratos y enviar las firmas están `getContracts` y `signContracts`\nrespectivamente. \n\n* `getContracts(Manifest\\GetContractsCommand $command): Manifest\\GetContractsResult`\n* `signContracts(Manifest\\SignContractsCommand $command): Manifest\\SignContractsResult`\n\n### Retenciones\n\nLos CFDI de Retenciones e información de pagos (RET) siguen un estándar más parecido a CFDI 3.2.\nSu cancelación es inmediata (al contrario de la solicitud de cancelación actual).\n\n* `stamp(Retentions\\StampCommand $command): Retentions\\StampResult`\n* `stamped(Retentions\\StampedCommand $command): Retentions\\StampedResult`\n* `cancelSignature(Retentions\\CancelSignatureCommand $command): Retentions\\StampedResult`\n\nPara descargar una retención debe usar el servicio `Utilerias`, método `get_xml` que está implementado previamente.\nIgualmente, se ha creado el método `QuickFinkok::retentionDownload($uuid, $rfc)` para simplificar su implementación.\n\n### Ayuda para firmado XML para SAT y Finkok\n\nEsta librería implementa el firmado CSD de los mensajes con el SAT para Cancelar, Obtener UUID relacionados\ny Aceptación o rechazo de solicitud de cancelación.\nToda la lógica involucrada en la creación de los XML firmados se encuentra en la librería\n[`phpcfdi/xml-cancelacion`](https://github.com/phpcfdi/xml-cancelacion).\n\nTambién implementa el firmado con FIEL de *manifiestos* con Finkok.\n\nPara estas tareas se han creado los siguientes objetos que permiten realizar el firmado de la información:\n\n- `Helpers\\CancelSigner`: Ayuda a firmar una solicitud de cancelación.\n- `Helpers\\GetRelatedSigner`: Ayuda a firmar una solicitud de información de UUID relacionados.\n- `Helpers\\AcceptRejectSigner`: Ayuda a firmar una respuesta de cancelación de 1 UUID.\n- `Helpers\\DocumentSigner`: Ayuda a firmar los documentos de *manifiesto* de Finkok.\n\nA su vez, estos métodos utilizan la librería [`phpcfdi/credentials`](https://github.com/phpcfdi/credentials)\npara poder crear las firmas y la información requerida por el SAT o Finkok.\n\nLa clase `QuickFinkok` ahorra el proceso de firmar peticiones y lo hace de forma automática, sin embargo,\nse muestra el siguiente ejemplo de cancelación firmada de 1 UUID con certificado y llave privada en archivos.\n\n```php\nuse PhpCfdi\\Credentials\\Credential;\nuse PhpCfdi\\Finkok\\Helpers\\CancelSigner;\nuse PhpCfdi\\Finkok\\Services\\Cancel\\CancelSignatureCommand;\n\n// el objeto con el que se van a firmar las solicitudes\n$credential = Credential::openFiles('certificate.cer', 'privateKey.pem', 'password');\n\n// el firmador de datos\n$signer = new CancelSigner(['11111111-2222-3333-4444-000000000001']);\n$signedXml = $signer-\u003esign($credential);\n\n// el comando a pasar al método Finkok::cancelSignature o al comando CancelSignatureService\n$cancelCommand = new CancelSignatureCommand($signedXml);\n```\n\n## Notas de implementación\n\nDurante el proceso de implementación he creado diversas notas y documentos:\n\n- [Cancelación](docs/Cancelación.md): Información del proceso de cancelación, métodos, acuses, pending buffer, etc.\n\n- [Servicios](docs/Servicios.md): Documentación básica de servicios.\n\n- [Listado de servicios](docs/ListadoDeServicios.md): Listado de todos los servicios disponibles de Finkok y si están\n  o no implementados, así como un listado de los servicios que no se implementarán.\n\n- [Registro de clientes](docs/RegistroDeClientes.md): Si vas a trabajar con la capacidad de Finkok de *sub-distribuidor*\n  y así poder administrar los datos de clientes.\n\n- [Pruebas de integración](docs/PruebasDeIntegracion.md): Documentación de cómo funciona y como configurar\n  el entorno de pruebas de integración.\n\n- Problemas encontrados:\n    - [X] [Cancelación de un CFDI recién creado](docs/issues/CancelSignatureServiceCancelarRecienCreado.md)\n    - [X] [Consumir `queryPending` con un CFDI recién creado](docs/issues/QueryPendingServiceUuidNoExistente.md)\n    - [X] [Consumir `stamp` para generar un doble estampado no devuelve los datos](docs/issues/StampServiceDobleEstampado.md)\n    - [X] Falta servicio que no requiera CSD/FIEL para aceptar o rechazar una solicitud de cancelación\n    - [X] Falta servicio que no requiera CSD/FIEL para obtener los CFDI relacionados\n    - [X] [El acuse de cancelación entregado al cancelar y al solicitar el acuse no coinciden](docs/issues/AcuseCancelacionNoCoincidente.md)\n    - [X] [Error de cancelación de retenciones 1308 - Certificado revocado o caduco](docs/issues/CancelacionRetencionesError1308.md)\n    - [X] [El valor `CodEstatus` está ausente en la cancelación de CFDI de Retenciones](docs/issues/CancelacionRetencionesCodEstatus.md)\n    - [X] [El método `Registration#Get` con `taxpayer_id` vacío no devuelve el listado de clientes](docs/issues/RegistrationGetNoList.md)\n    - [X] [Al timbrar con un texto `\u0026amp;` devuelve `705 - XML Estructura inválida`](docs/issues/StampAmpersand.md)\n\n## Capturar conversación HTTP\n\nAlgunas veces, al reportar a Finkok un problema, nos solicitan la conversación HTTP (*Request* y *Response*)\npara poder revisar el problema sobre la información enviada.\n\nEsta librería genera mensajes utilizando *PSR-3: Logger Interface*, y se utiliza dentro del objeto `SoapFactory`\npara crear un `SoapCaller`. Este objeto envía dos tipos de mensajes: `LogLevel::ERROR` cuando ocurre un error al\nmomento de establecer comunicación con los servicios, y `LogLevel::DEBUG` cuando se ejecutó una llamada SOAP.\nAmbos mensajes están representados como una cadena en formato JSON, por lo que, para leerla fácilmente\nes importante decodificarla.\n\nEl formato JSON es mejor dado que permite analizar el texto y encontrar caracteres especiales,\nmientras que, al convertirlo a un texto más entendible para el humano, estos caracteres especiales\nse pueden esconder o interpretar de forma errónea.\n\nSe ofrece la clase `PhpCfdi\\Finkok\\Helpers\\FileLogger` como una utilería de `LoggerInterface`\nque manda los mensajes recibidos a la salida estándar o a un archivo.\n\nTambién se ofrece la clase `PhpCfdi\\Finkok\\Helpers\\JsonDecoderLogger` como una utilería de `LoggerInterface`\nque decodifica el mensaje JSON y luego lo convierte a cadena de caracteres usando la función `print_r()`,\npara después mandarlo a otro objeto `LoggerInterface`.\n\nEn el siguiente ejemplo se muestra la forma recomendada para establecer el objeto `Logger`,\ntambién se muestra el uso de `JsonDecoderLogger` para realizar la conversión de JSON a texto plano y\n`FileLogger` para enviar el mensaje a un archivo específico.\n\nLa clase `JsonDecoderLogger` puede generar pérdida de información, pero los mensajes son más entendibles,\nsi deseas también incluir el mensaje JSON puedes usar `JsonDecoderLogger::setAlsoLogJsonMessage(true)`.\n\n```php\nuse PhpCfdi\\Finkok\\FinkokEnvironment;\nuse PhpCfdi\\Finkok\\FinkokSettings;\nuse PhpCfdi\\Finkok\\Helpers\\FileLogger;\nuse PhpCfdi\\Finkok\\Helpers\\JsonDecoderLogger;\n\n$logger = new JsonDecoderLogger(new FileLogger('/tmp/finkok.log'));\n$logger-\u003esetAlsoLogJsonMessage(true); // enviar en texto simple y también en formato JSON\n\n$settings = new FinkokSettings('user@host.com', 'secret', FinkokEnvironment::makeProduction());\n$settings-\u003esoapFactory()-\u003esetLogger($logger);\n```\n\nSi estás usando Laravel, ya cuentas con una implementación de `LoggerInterface`, por lo que te recomiendo usar:\n\n```php\n/** @var \\Psr\\Log\\LoggerInterface $logger */\n$logger = app(\\Psr\\Log\\LoggerInterface::class);\n\n// Encapsular el logger en el decodificador JSON:\n$logger = new \\PhpCfdi\\Finkok\\Helpers\\JsonDecoderLogger($logger);\n```\n\n## Compatibilidad\n\nEsta librería se mantendrá compatible con al menos la versión con\n[soporte activo de PHP](https://www.php.net/supported-versions.php) más reciente.\n\nTambién utilizamos [Versionado Semántico 2.0.0](docs/SEMVER.md) por lo que puedes usar esta librería\nsin temor a romper tu aplicación.\n\n| Versión de la librería | Versión de PHP                | Fecha de lanzamiento |\n|------------------------|-------------------------------|----------------------|\n| 0.1.0                  | 7.2, 7.3 y 7.4                | 2019-03-29           |\n| 0.3.0                  | 7.3, 7.4, 8.0, 8.1, 8.2 y 8.3 | 2021-03-18           |\n| 0.6.0                  | 8.1, 8.2, 8.3 y 8.4           | 2025-11-08           |\n\n## Contribuciones\n\nLas contribuciones con bienvenidas. Por favor lee [CONTRIBUTING][] para más detalles\ny recuerda revisar el archivo de tareas pendientes [TODO][] y el archivo [CHANGELOG][].\n\n## Copyright and License\n\nThe phpcfdi/finkok library is copyright © [PhpCfdi](https://www.phpcfdi.com)\nand licensed for use under the MIT License (MIT). Please see [LICENSE][] for more information.\n\n[contributing]: https://github.com/phpcfdi/finkok/blob/main/CONTRIBUTING.md\n[changelog]: https://github.com/phpcfdi/finkok/blob/main/docs/CHANGELOG.md\n[todo]: https://github.com/phpcfdi/finkok/blob/main/docs/TODO.md\n\n[source]: https://github.com/phpcfdi/finkok\n[php-version]: https://packagist.org/packages/phpcfdi/finkok\n[discord]: https://discord.gg/aFGYXvX\n[release]: https://github.com/phpcfdi/finkok/releases\n[license]: https://github.com/phpcfdi/finkok/blob/main/LICENSE\n[build]: https://github.com/phpcfdi/finkok/actions/workflows/build.yml?query=branch:main\n[reliability]:https://sonarcloud.io/component_measures?id=phpcfdi_finkok\u0026metric=Reliability\n[maintainability]: https://sonarcloud.io/component_measures?id=phpcfdi_finkok\u0026metric=Maintainability\n[coverage]: https://sonarcloud.io/component_measures?id=phpcfdi_finkok\u0026metric=Coverage\n[violations]: https://sonarcloud.io/project/issues?id=phpcfdi_finkok\u0026resolved=false\n[downloads]: https://packagist.org/packages/phpcfdi/finkok\n\n[badge-source]: https://img.shields.io/badge/source-phpcfdi/finkok-blue?logo=github\n[badge-discord]: https://img.shields.io/discord/459860554090283019?logo=discord\n[badge-php-version]: https://img.shields.io/packagist/php-v/phpcfdi/finkok?logo=php\n[badge-release]: https://img.shields.io/github/release/phpcfdi/finkok?logo=git\n[badge-license]: https://img.shields.io/github/license/phpcfdi/finkok?logo=open-source-initiative\n[badge-build]: https://img.shields.io/github/actions/workflow/status/phpcfdi/finkok/build.yml?branch=main\u0026logo=github-actions\n[badge-reliability]: https://sonarcloud.io/api/project_badges/measure?project=phpcfdi_finkok\u0026metric=reliability_rating\n[badge-maintainability]: https://sonarcloud.io/api/project_badges/measure?project=phpcfdi_finkok\u0026metric=sqale_rating\n[badge-coverage]: https://img.shields.io/sonar/coverage/phpcfdi_finkok/main?logo=sonarqubecloud\u0026server=https%3A%2F%2Fsonarcloud.io\n[badge-violations]: https://img.shields.io/sonar/violations/phpcfdi_finkok/main?format=long\u0026logo=sonarqubecloud\u0026server=https%3A%2F%2Fsonarcloud.io\n[badge-downloads]: https://img.shields.io/packagist/dt/phpcfdi/finkok?logo=packagist\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphpcfdi%2Ffinkok","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphpcfdi%2Ffinkok","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphpcfdi%2Ffinkok/lists"}