node-acumatica

A comprehensive Node.js client for interacting with the Acumatica REST API. This client offers a robust interface for handling authentication, session management, and operations such as creating, updating, querying, and managing files.

Features

• 🔐 Session-based authentication and automatic cookie management.
• 💾 CRUD operations for managing entities.
• 📊 Support for Generic Inquiry and OData queries.
• 📁 File retrieval from entity attachments.
• ⚡ Promise-based (async/await) API for modern Node.js applications.

Installation

Install the package via npm:

npm install node-acumatica

Quick Start

Below is an example that demonstrates how to use the client:

const AcumaticaAPI = require('node-acumatica');

const api = new AcumaticaAPI({
  baseUrl: 'https://your-instance.example.com',
  username: 'admin',
  password: 'password',
  tenant: 'MyCompany',
  branch: 'MAIN'
});

(async () => {
  try {
    // Log in to Acumatica
    await api.login();

    // Create a new Customer entity
    const newCustomer = await api.createEntity({
      CustomerID: { value: 'CUST001' },
      CustomerName: { value: 'New Customer' }
    }, 'Customer');
    console.log('Customer created:', newCustomer);

    // Fetch customer details by ID
    const customer = await api.fetchEntityByID('Customer', 'CUST001', {
      $expand: 'Details,Contacts'
    });
    console.log('Customer details:', customer);

    // Perform additional operations (update, query, file retrieval, etc.)
    
  } catch (error) {
    console.error('Error:', error.message);
  } finally {
    // Log out to clear the session
    await api.logout();
  }
})();

API Reference

Constructor

Creates an instance of the AcumaticaAPI client.

const api = new AcumaticaAPI({
  baseUrl,    // Acumatica instance URL
  username,   // Username for authentication
  password,   // Password for authentication
  tenant,     // Tenant name
  branch      // Branch name
});

Authentication Methods

login()

Authenticates with the Acumatica instance and establishes a session.

await api.login();

logout()

Signs out from Acumatica and clears session cookies.

await api.logout();

Entity Operations

createEntity(data, entityType, [endpointName], [endpointVersion])

Creates a new entity in Acumatica.

const newCustomer = await api.createEntity({
  CustomerID: { value: 'CUST001' },
  CustomerName: { value: 'New Customer' }
}, 'Customer');

updateEntity(entityId, data, entityType, entityIdField, [idType], [parameters])

Updates an existing entity in Acumatica.

const updatedCustomer = await api.updateEntity(
  'CUST001',
  { CustomerName: { value: 'Updated Name' } },
  'Customer',
  'CustomerID',
  'string'
);

fetchEntity(entityType, [parameters])

Fetches multiple entities of a specific type.

const customers = await api.fetchEntity('Customer', {
  $filter: "Status eq 'Active'",
  $top: 10
});

fetchEntityByID(entityType, entityID, [parameters])

Fetches a single entity by its identifier.

const customer = await api.fetchEntityByID('Customer', 'CUST001', {
  $expand: 'Details,Contacts'
});

Generic Inquiry Operations

fetchGenericInquiry(screenId, viewName, [parameters])

Retrieves data using a Generic Inquiry screen.

const results = await api.fetchGenericInquiry('GI000123', 'MyView', {
  $filter: "Status eq 'Active'"
});

fetchGenericInquiryFromOData(inquiryName, [parameters])

Retrieves data from Acumatica via the OData endpoint.

const results = await api.fetchGenericInquiryFromOData('MyInquiry', {
  $filter: "Status eq 'Active'",
  $top: 10
});

Entity Actions

invokeEntityAction(entityType, action, [data])

Invokes a specific action on an entity.

const result = await api.invokeEntityAction(
  'SalesOrder',
  'Release',
  { orderNbr: '000123' }
);

File Operations

getFileByFilename(entityType, entityID, filename)

Retrieves a file attached to an entity based on its filename.

const file = await api.getFileByFilename('Customer', 'CUST001', 'contract.pdf');

Error Handling

Wrap your API calls in try/catch blocks to handle errors gracefully:

try {
  await api.login();
  const customer = await api.fetchEntityByID('Customer', 'CUST001');
} catch (error) {
  console.error('Operation failed:', error.message);
} finally {
  await api.logout();
}

Best Practices

• Always ensure you are logged in before performing entity operations.
• Handle errors with try/catch blocks to manage API failures.
• Log out to clear session cookies after operations.
• Secure your credentials by not hardcoding them in your source code.
• Adjust query parameters (e.g., $filter, $expand, $top) as needed to optimize data retrieval.

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new branch with your feature or bug fix.
3. Update the code and documentation as needed.
4. Submit a pull request.

Support

If you encounter any issues, please open an issue on our GitHub repository.