GUS Company Lookup

GUS Company Lookup is a WordPress shortcode plugin for querying Poland's GUS BIR company register by NIP, KRS, or REGON. It can also request full company and PKD reports for returned REGON records.

The plugin keeps the GUS API key on the server. It does not expose credentials to browser JavaScript, store lookup results, or include the key found in the original prototype scripts.

Features

• [gus_company_lookup] search form for NIP, KRS, and REGON
• Full company and PKD report actions
• WordPress HTTP API transport with fixed HTTPS destinations
• Server-side identifier validation and AJAX nonce checks
• Text-only DOM rendering of remote values to prevent markup injection
• Logged-in access by default
• Per-visitor limit of 30 API requests per five minutes
• API key configuration through a protected setting, constant, or filter
• No storage of queried identifiers or returned company data

Requirements

• WordPress 6.0 or newer
• PHP 7.4 or newer with SimpleXML
• A GUS BIR API key

Installation

1. Download gus-scripts-1.0.0.zip from the latest GitHub release.
2. In WordPress, open Plugins > Add New > Upload Plugin.
3. Select the ZIP, install it, and activate GUS Company Lookup.
4. Open Settings > GUS Company Lookup and save a GUS BIR API key.
5. Add [gus_company_lookup] to a page.

You can also clone this repository into wp-content/plugins/gus-scripts.

Credential configuration

The Settings page stores the key in the WordPress options table and never redisplays it. For deployment-managed credentials, define the constant in wp-config.php instead:

define( 'CODED_LETTER_GUS_API_KEY', 'your-key' );

The constant overrides the saved setting. Advanced deployments can use the coded_letter_gus_api_key filter.

Public access

Only signed-in WordPress users can query GUS by default. This protects the configured credential from becoming an unrestricted public proxy.

To intentionally allow guest requests, add:

add_filter( 'coded_letter_gus_allow_public_requests', '__return_true' );

Guest and authenticated requests are still nonce-checked and rate-limited. Consider adding an edge rate limit or bot challenge on public forms.

Data and privacy

Identifiers and GUS responses are used only for the current HTTP request. The plugin does not write searches or results to WordPress, logs, analytics, or browser storage. The visitor's identifier is sent to the official GUS service.

Development

The production source is maintained in the coded-letter-monorepo and released to this public repository. The plugin has no build step.

Validate PHP changes with:

php -l gus-scripts.php
php -l includes/class-coded-letter-gus-bir-client.php
php -l includes/superfunky-release-client.php
php -l includes/superfunky-update-client.php
php -l uninstall.php

Validate JavaScript syntax with:

node --check assets/gus-company-lookup.js

License

GUS Company Lookup is free software licensed under the GNU General Public License v2.0 or later.