npm package: @pokash/n8n-nodes-gus
Description: n8n node to integrate with Polish GUS (Główny Urząd Statystyczny) API using REGON database
Author: POKASH
Latest version: 1.0.52

## 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
```json
{
  "nodes": [
    {
      "name": "Get Company Data",
      "type": "n8n-nodes-gus.gus",
      "parameters": {
        "resource": "company", 
        "operation": "getByNip",
        "nipNumber": "5213017228"
      }
```

### Get Full Company Report
```json
{
  "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
```json
{
  "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
```json
{
  "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