ERP API

The ErpApi class is your primary interface for making authenticated HTTP requests to the VARIO ERP API. It extends the base Api class with automatic token management, so you don't need to handle access tokens manually.

Basic Usage

const ErpApi = require('@vario-software/vario-app-framework-backend/api/ErpApi');

GET Request

const result = await ErpApi.fetch('/erp/articles/123', {
  useInternalApi: true
});

const article = result.data;

POST Request

const result = await ErpApi.fetch('/erp/crm-activities', {
  method: 'POST',
  useInternalApi: true,
  body: JSON.stringify({
    comment: 'Created from shop app',
    type: { id: '1' }
  })
});

PUT / PATCH Request

await ErpApi.fetch(`/erp/articles/${articleId}`, {
  method: 'POST', // VARIO uses POST for updates
  useInternalApi: true,
  body: JSON.stringify(updatedData)
});

Key Options

Option	Type	Default	Description
method	string	'GET'	HTTP method
useInternalApi	boolean	false	Use internal API with offline token authentication
executeAsAppUser	boolean	false	Execute as the app user instead of the requesting user
body	string	—	Request body (JSON stringified)
headers	object	—	Additional HTTP headers
timeout	number	900000 (15 min)	Request timeout in milliseconds
stream	object	—	Stream configuration for file uploads/downloads

useInternalApi

When true, the request is authenticated using the offline token stored during installation. This is required for:

• Webhook handlers (no user session available)

• Background processing (queue processors)

• Any server-to-server communication

When false, the request uses the current user's access token from the request context.

executeAsAppUser

When true, the request is made with the app user's permissions instead of the current user's. This is useful when your app needs elevated permissions that a regular user might not have.

VQL Queries

The ErpApi.vql() static method provides a dedicated interface for VQL queries:

const { data } = await ErpApi.vql(
  `SELECT id, articleNumber FROM article.queryArticles WHERE active = true`,
  {},     // variables
  100,    // limit
  0       // offset
);

For detailed VQL documentation, see VQL Queries.

Gateway Requests

The ErpApi.gateway() method routes requests through the ERP gateway:

const user = await ErpApi.gateway('/me', {
  useInternalApi: true
});

Error Handling

HTTP Errors

ErpApi throws errors for non-2xx responses. Catch and handle them:

const { HttpError } = require('@vario-software/vario-app-framework-backend/utils/httpError');

try
{
  const result = await ErpApi.fetch('/erp/articles/nonexistent', {
    useInternalApi: true
  });
}
catch (error)
{
  if (error instanceof HttpError)
  {
    switch (error.statusCode)
    {
      case 404:
        // Entity not found
        break;
      case 429:
        // Rate limited — ErpApi retries this automatically
        break;
      case 401:
        // Token expired or invalid
        break;
      default:
        // Other error
        break;
    }
  }
}

Automatic Rate Limit Handling

The framework automatically handles HTTP 429 (Too Many Requests) responses with exponential backoff. You don't need to implement retry logic for rate limits — the Api base class handles this transparently.

Token Refresh

Access tokens are automatically refreshed when they expire. If a 401 error occurs, the framework deletes the cached token and re-authenticates on the next request.

Streaming

For large file transfers (e.g., importing product images), use the stream option:

const response = await ErpApi.fetch('/erp/media/download/123', {
  useInternalApi: true,
  stream: { output: true }
});

Request Context

Every ErpApi request includes context information automatically:

• Tenant — Derived from the access token

• Request ID — Unique identifier for tracing

• Authorization — Access token or offline token

You don't need to set these manually — the framework handles them through the context system.