Configuration

Prerequisites

GUS API Key: You need to obtain an API key from the Polish Statistical Office:

• For production: Register at https://api.stat.gov.pl/
• For testing: Use the sandbox environment (no key required for basic testing)

Credentials Setup

1. In n8n, create new GUS API credentials
2. Configure:
   • API Key: Your production API key from GUS
   • Environment: Choose between "Sandbox (Test)" or "Production"
   • Anti-Captcha API Key: (Optional) For automatic captcha solving

Usage

Operations

Get by NIP

Retrieve company information using Tax Identification Number (NIP).

Parameters:

• NIP Number: 10-digit tax identification number (e.g., "1234567890")

Get by REGON

Retrieve company information using Statistical Number (REGON).

Parameters:

• REGON Number: 9 or 14-digit statistical number (e.g., "123456789")

Get by KRS

Retrieve company information using National Court Register Number (KRS).

Parameters:

• KRS Number: 10-digit court register number (e.g., "0000123456")

Get Full Report

Retrieve comprehensive company report with detailed XML data automatically saved as binary attachment.

Parameters:

• REGON Number: 9 or 14-digit statistical number for the report
• Report Type: Type of report to retrieve:
  • BIR11OsPrawna - Legal Person (default)
  • BIR11OsFizyczna - Physical Person
  • BIR11JednLokal - Local Unit
  • PublDaneRaportPrawna - Public Legal Entity Report
  • PublDaneRaportFizyczna - Public Physical Person Report
• Silos ID: Optional Silos ID for specific data requirements

Binary Data: The complete XML report is automatically saved as gus_full_report binary attachment.

Search

Search for companies using various criteria.

Parameters:

• Company Name: Full or partial company name
• Province: Voivodeship name
• District: Powiat name
• Municipality: Gmina name
• City: City name
• Street: Street name

Additional Options

• Auto Login: Automatically authenticate with the API (default: true)
• BIR Version: Choose between API version 1.0 or 1.1 (default: 1.1)
• Auto Solve Captcha: Enable automatic captcha solving using anti-captcha.com
• Request Timeout: Set timeout for API requests (5-120 seconds, default: 30)
• Include Raw Response: Store original GUS API response as binary data

Example Workflows

Get Company Info by NIP

{
  "nodes": [
    {
      "name": "Get Company Data",
      "type": "n8n-nodes-gus.gus",
      "parameters": {
        "resource": "company", 
        "operation": "getByNip",
        "nipNumber": "5213017228"
      }

Get Full Company Report

{
  "nodes": [
    {
      "name": "Get Full Report with XML",
      "type": "n8n-nodes-gus.gus",
      "parameters": {
        "resource": "company",
        "operation": "getFullReport",
        "regonForReport": "146447092",
        "reportType": "BIR11OsPrawna",
        "silosId": ""
      },
      "credentials": {
        "gusApi": "GUS Production API"
      }
    }
  ]
}

Search Companies by Name

{
  "nodes": [
    {
      "name": "Search Companies",
      "type": "n8n-nodes-gus.gus", 
      "parameters": {
        "resource": "company",
        "operation": "search", 
        "searchCriteria": {
          "filters": {
            "nazwa": "Microsoft",
            "miejscowosc": "Warszawa"
          }
        }
      },
      "credentials": {
        "gusApi": "GUS Production API"
      }
    }
  ]
}

Get Company with Raw Response

{
  "nodes": [
    {
      "name": "Get Company with Raw Data",
      "type": "n8n-nodes-gus.gus",
      "parameters": {
        "resource": "company",
        "operation": "getByNip",
        "nipNumber": "5213017228",
        "additionalFields": {
          "includeRawResponse": true,
          "timeout": 60
        }
      },
      "credentials": {
        "gusApi": "GUS Production API"
      }
    }
  ]
}

Response Data

The node returns detailed company information including:

• Basic Information: Company name, legal form, registration status
• Identification Numbers: NIP, REGON, KRS numbers
• Address Information: Full address details
• Business Activity: PKD codes and descriptions
• Registration Details: Registration date, court information
• Contact Information: Phone, email, website (if available)

Binary Data

The node provides binary data in two scenarios:

1. Raw Response (Optional)

When "Include Raw Response" is enabled in Additional Options:

• Content: Complete unprocessed response from GUS API
• Format: JSON file named gus_response_{operation}_{timestamp}_{index}.json
• Mime Type: application/json

2. Full Report XML (Automatic)

When using "Get Full Report" operation:

• Content: Complete XML report from GUS with detailed company data
• Format: XML file named gus_full_report_{regon}_{reportType}_{timestamp}.xml
• Mime Type: application/xml
• Binary Property: gus_full_report

Use Cases:

• Debugging API responses and troubleshooting
• Accessing all fields not included in processed JSON
• Long-term archival and data retention
• Integration with external systems requiring original data
• Compliance, audit trails, and regulatory reporting
• Processing XML reports with custom parsers

Error Handling

The node handles various error scenarios:

• Invalid credentials: Returns authentication error
• Captcha required: Returns captcha information for manual solving
• Rate limiting: Handles API rate limits gracefully
• Invalid input: Validates NIP, REGON, and KRS number formats
• No results found: Returns appropriate "no data" response