Creating a Plugin

Getting Started

Installation

Download and Install Invoice Radar:
- Request Access to Invoice Radar
Download the Blank Plugin:
- Download the Blank Plugin to your local machine
- Rename the file to your-plugin-name.json
- Put it into a folder of your choice
Add the Plugin to Invoice Radar:
- Open Invoice Radar
- Navigate to Plugins tab inside settings
- Choose Choose Plugin Directory and select the folder where you saved the plugin
- Your plugin should now appear in the list of available plugins

Plugin Overview

Plugins for Invoice Radar are written in JSON and follow a specific structure with these main sections:

Metadata: Basic information (name, description, homepage)
Configuration: Optional user-configurable options
Authentication: Steps to log in and verify login status
Document Extraction: Steps to find and download documents

For complete details on plugin structure and all available options, see the Plugin Reference.

Minimal Plugin Example

Here's a basic plugin structure to get you started:

{
  "$schema": "https://raw.githubusercontent.com/invoiceradar/plugins/main/schema.json",
  "id": "example",
  "name": "Example Platform",
  "description": "Short description of the service.",
  "homepage": "https://example.com",
  "checkAuth": [
    {
      "action": "navigate",
      "url": "https://example.com/dashboard"
    },
    {
      "action": "checkElementExists",
      "selector": "#logout-button"
    }
  ],
  "startAuth": [
    {
      "action": "navigate",
      "url": "https://example.com/login"
    },
    {
      "action": "waitForElement",
      "selector": "#account-summary",
      "timeout": 120000
    }
  ],
  "getDocuments": [
    {
      "action": "navigate",
      "url": "https://example.com/billing"
    },
    {
      "action": "extractAll",
      "selector": ".invoice-row",
      "variable": "invoice",
      "fields": {
        "id": {
          "selector": ".invoice-id"
        },
        "date": {
          "selector": ".invoice-date"
        },
        "total": {
          "selector": ".invoice-total"
        },
        "url": {
          "selector": ".invoice-download",
          "attribute": "href"
        }
      },
      "forEach": [
        {
          "action": "downloadPdf",
          "url": "{{invoice.url}}",
          "document": "{{invoice}}"
        }
      ]
    }
  ]
}

Writing Your First Plugin

Step 1: Define Basic Information

Start with the essential metadata for your plugin:

{
  "id": "example-service",
  "name": "Example Service",
  "description": "Short description of the Example Service",
  "homepage": "https://example.com"
}

The id should be unique and lowercase. The homepage URL is used to get the service favicon.

Step 2: Set Up Authentication

Define how to check if a user is logged in (checkAuth) and how to start the login process (startAuth):

"checkAuth": [
  {
    "action": "navigate",
    "url": "https://example.com/dashboard"
  },
  {
    "action": "checkElementExists",
    "selector": "#logout-button"
  }
],
"startAuth": [
  {
    "action": "navigate",
    "url": "https://example.com/login"
  },
  {
    "action": "waitForElement",
    "selector": "#account-summary",
    "timeout": 120000
  }
]

The browser will be visible during authentication, allowing users to interact with the login form.

For more authentication patterns and best practices, see the Useful Patterns guide.

Step 3: Extract Documents

Define how to find and download documents:

"getDocuments": [
  {
    "action": "navigate",
    "url": "https://example.com/billing"
  },
  {
    "action": "extractAll",
    "selector": ".invoice-row",
    "variable": "invoice",
    "fields": {
      "id": ".invoice-id",
      "date": ".invoice-date",
      "total": ".invoice-total",
      "url": ".invoice-download[href]"
    },
    "forEach": [
      {
        "action": "downloadPdf",
        "url": "{{invoice.url}}",
        "document": "{{invoice}}"
      }
    ]
  }
]

Step 4: Save and Test

Save your plugin file and add it to Invoice Radar. You can now test the plugin to fetch documents from your service.

Next Steps

Now that you've created your first plugin, explore these resources for advanced features:

Plugin Reference - Complete plugin structure, configuration options, and examples
Steps Reference - Detailed documentation for all available actions
Useful Patterns - Common patterns for authentication and data extraction
Autofill Configuration - Configure automatic credential filling

Creating a Plugin

On this page