npm package: @spacesign/n8n-nodes-spacesign
Description: n8n nodes for the SpaceSign eSignature platform
Author: SpaceSign
Latest version: 0.1.1

# n8n-nodes-spacesign

Community nodes that connect [SpaceSign](https://space-sign.ai) with [n8n](https://n8n.io) so you can automate end-to-end signature workflows: create documents, generate from templates, manage recipients/fields, and capture webhook events.

## Installation

Follow the [n8n community nodes installation guide](https://docs.n8n.io/integrations/community-nodes/installation/).

### via Community Nodes UI (recommended)

1. Open **Settings → Community Nodes** inside n8n.
2. Click **Install** and enter `@spacesign/n8n-nodes-spacesign`.
3. Accept the community node risks warning.
4. Confirm to install.

### via npm

Run in the root of your self-hosted n8n instance:

```bash
npm install @spacesign/n8n-nodes-spacesign
```

### via Docker

Add the package to the `N8N_COMMUNITY_PACKAGES` env var:

```yaml
services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    environment:
      - N8N_COMMUNITY_PACKAGES=@spacesign/n8n-nodes-spacesign
```

## Credentials

The SpaceSign nodes use API-key authentication:

- **API Key** – created in SpaceSign **Settings → API Tokens** (format `api_XXXX`).
- **Base URL** – defaults to `https://space-sign.ai/api/v1` but can point at any self-hosted/staging tenant.
- **Additional Headers** – optional name/value pairs for custom reverse proxies.

Credential test performs `GET /documents?page=1&perPage=1` to validate the token.

## Nodes

### SpaceSign (action node)

Resources and operations:

- **Document** – list/get/create/upload/send/resend/delete documents.
- **Template** – list/get/delete templates and generate documents from templates with recipient overrides, metadata, prefill fields, and auth options.
- **Recipient** – add/update/delete recipients on an existing document.
- **Field** – add/update/delete fields with advanced metadata.

The create + generate flows support JSON overrides for metadata, auth options, PDF form values, and prefill field payloads so you can map dynamic data from upstream nodes.

### SpaceSign Trigger

- Accepts SpaceSign webhook payloads for events such as document created/sent/opened/signed/completed/rejected/cancelled.
- Optional secret validation against the `X-Space-E-Sign-Secret` header.
- Reminder notice to register the webhook URL manually inside SpaceSign **Settings → Webhooks**.

## Usage examples

### Create a document with recipients

1. Create n8n credentials named **SpaceSign API** with your API key and (optionally) a custom base URL.
2. Drop a **SpaceSign** node into your workflow, set **Resource** to `Document`, **Operation** to `Create Document`, and wire upstream data into the `title`, `recipients`, and optional JSON fields.
3. Example node configuration exported from n8n for quick reference:

```json
{
  "name": "SpaceSign - Create",
  "parameters": {
    "resource": "document",
    "operation": "createDocument",
    "title": "{{ $json.projectName }} Contract",
    "recipients": {
      "recipient": [
        {
          "name": "{{ $json.client.name }}",
          "email": "{{ $json.client.email }}",
          "role": "SIGNER",
          "signingOrder": 1
        },
        {
          "name": "Success Team",
          "email": "success@example.com",
          "role": "CC",
          "signingOrder": 2
        }
      ]
    },
    "additionalFields": {
      "externalId": "{{ $json.contractId }}",
      "metaJson": "{{ $json.metadata }}"
    }
  },
  "credentials": [{ "name": "spaceSignApi", "id": "SpaceSign API" }]
}
```

This snippet shows how to map incoming JSON data (for example from a Webhook or CRM node) directly into the SpaceSign node fields.

### Listen for SpaceSign events

1. Add a **SpaceSign Trigger** node and pick the events you want (e.g., Document Completed).
2. Copy the webhook URL shown in n8n and register it inside SpaceSign **Settings → Webhooks**.
3. (Optional) Set a secret in both SpaceSign and the trigger node so unsolicited requests fail with 401.
4. Use the trigger output (document status, recipient info, timestamps) to branch the rest of your workflow.

## Development

Requirements:

- Node.js `>=22.0.0`
- npm `>=10.7.0`

Useful scripts:

```bash
npm run dev     # TypeScript watch mode
npm run lint    # ESLint checks
npm run build   # Compile TypeScript + copy icons
npm run test    # Lint + type-check without emitting
```

Build output lands in `dist/` and is referenced inside `package.json` → `n8n` block for publishing.