Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/VisualGraphxLLC/API-HUB/llms.txt

Use this file to discover all available pages before exploring further.

API-HUB delegates every outbound integration to n8n. FastAPI handles the inbound supplier pipeline — fetching, normalizing, and storing catalog data — but the moment data needs to leave the hub toward an OnPrintShop (OPS) storefront, n8n takes over. This clean boundary means you can swap n8n host providers without touching any Python code, and it keeps GraphQL mutation logic out of your API layer.

​
How the two systems connect

n8n calls FastAPI over an internal network address set in API_BASE_URL. Every request from n8n to a FastAPI ingest or push endpoint carries an X-Ingest-Secret header whose value must match INGEST_SHARED_SECRET in the FastAPI environment. These two variables are the only handshake between the two systems.

​
Supported n8n hosting options

Self-hosted Docker

Run the bundled n8n.Dockerfile image. The OnPrintShop community node is baked in — no volume mounts or manual installs required.

ECS Fargate

Push the api-hub-n8n image to ECR and reference it in your task definition. Set API_BASE_URL and INGEST_SHARED_SECRET as task environment variables.

n8n.cloud Pro+

Install n8n-nodes-onprintshop manually via Settings → Community Nodes. Community nodes require the Pro tier or higher.

Render / Fly / Railway / Hetzner

Any host that can run a Docker image works. Build the n8n.Dockerfile image and push it to your registry of choice.
n8n.cloud Starter is not supported. Community nodes are blocked on the Starter tier. You must use Pro+ or self-host.

​
The custom n8n.Dockerfile

API-HUB ships a two-stage Dockerfile that compiles the TypeScript n8n-nodes-onprintshop package and bakes the built artifacts into the official n8nio/n8n:latest image:
n8n.Dockerfile
# Stage 1 — compile the community node
FROM node:20-alpine AS node-build
WORKDIR /build
COPY n8n-nodes-onprintshop/package.json n8n-nodes-onprintshop/package-lock.json ./
RUN npm ci
COPY n8n-nodes-onprintshop ./
RUN npm run build

# Stage 2 — install into n8n
FROM n8nio/n8n:latest
USER root
RUN mkdir -p /opt/custom-nodes/n8n-nodes-onprintshop \
 && chown -R node:node /opt/custom-nodes
COPY --from=node-build --chown=node:node /build/dist /opt/custom-nodes/n8n-nodes-onprintshop/dist
COPY --from=node-build --chown=node:node /build/package.json /opt/custom-nodes/n8n-nodes-onprintshop/package.json
USER node
ENV N8N_CUSTOM_EXTENSIONS=/opt/custom-nodes
The node lands at /opt/custom-nodes rather than inside the n8n data volume. This keeps it intact when the n8n_data volume is mounted at /home/node/.n8n, making the image fully portable across environments. To build the image from the repo root: 
docker build -f n8n.Dockerfile -t api-hub-n8n:latest .

​
Environment variables

Both n8n and FastAPI must agree on two values. Set them in your repo-root .env file; Docker Compose forwards them automatically to both containers.
VariableWhere it’s setWhat it does
API_BASE_URLn8n containerBase URL of the FastAPI service. In Docker Compose this is http://api:8000. In production, use your public or internal API hostname.
INGEST_SHARED_SECRETn8n and FastAPI containersShared secret sent as X-Ingest-Secret on every ingest and push request. Must be identical in both containers.
N8N_API_KEYFastAPI containern8n REST API key. FastAPI’s n8n proxy uses this to call /api/v1/workflows on your behalf.
N8N_API_BASE_URLFastAPI containerInternal URL n8n listens on (defaults to http://n8n:5678). Used by the proxy module.
After changing .env, restart n8n with docker compose up -d n8n so the new variables are picked up.

​
Quick start

1

Start the stack

From the repo root, start PostgreSQL, the FastAPI backend, and n8n together:
docker compose --profile dev up -d
n8n is available at http://localhost:5678.
2

Set environment variables

Copy .env.example to .env and fill in the two required values:
INGEST_SHARED_SECRET=<random-32-char-string>
API_BASE_URL=http://api:8000
Restart n8n after editing:
docker compose up -d n8n
3

Import workflow JSONs

In the n8n editor, go to Workflows → Import from File and select each .json file from the n8n-workflows/ directory. All workflows ship with "active": false — do not activate until credentials are configured.
4

Configure OnPrintShop credentials

In n8n, open Credentials → New → OnPrintShop API. Enter the Client ID, Client Secret, Base URL, and Token URL for each OPS storefront. See the OnPrintShop Node page for required fields.You can also configure credentials per customer through the API-HUB admin Customers UI.
5

Activate workflows

Open each workflow, confirm every OnPrintShop node shows the correct credential, then toggle the workflow to Active. Scheduled and webhook triggers will not fire until a workflow is active.

​
Triggering workflows from the admin UI

The FastAPI n8n proxy module exposes an endpoint that lets the Next.js admin UI trigger any active workflow without exposing the n8n API key to the browser. 
POST /api/n8n/workflows/{workflow_id}/trigger
This endpoint resolves the workflow’s first webhook node, then issues a POST to the n8n webhook URL, forwarding any query parameters as the POST body. If the workflow is inactive or has no webhook trigger, FastAPI returns a 409. The proxy also provides read-only endpoints used by the Workflows admin page:
MethodPathPurpose
GET/api/n8n/workflowsList all workflows (condensed: id, name, active, triggers, webhook_url)
GET/api/n8n/workflows/{id}Full workflow detail
GET/api/n8n/executionsRecent execution history (optional workflow_id filter)
The proxy falls back gracefully if n8n is unreachable during boot — it returns an empty list rather than a 503, keeping the admin dashboard stable while n8n initializes.

Build docs developers (and LLMs) love

Get started for freeTalk to us