Quickstart

Prerequisites

Before you begin, ensure you have the following installed and configured:

.NET 9.0 SDK

Download from dotnet.microsoft.com

SQL Server

Required for business database connections (optional for basic testing)

INFOR EAM Access

Valid credentials for INFOR EAM Web Services

Code Editor

Visual Studio 2022, VS Code, or JetBrains Rider

The SQLite cache database is created automatically on first run - no manual database setup required!

Installation

Clone the Repository

Clone the project to your local machine:

git clone <repository-url>
cd hgt-eam-web-services

Restore Dependencies

Restore all NuGet packages:

dotnet restore

This will download all required packages including:

ASP.NET Core 9.0
Entity Framework Core 9.0
Mediator.SourceGenerator
Scalar.AspNetCore 2.11.0
AspNetCore.Authentication.Basic

Verify Build

Ensure the project builds successfully:

dotnet build

You should see a successful build message with no errors.

Configuration

Configure the application by editing appsettings.json in the HGT.EAM.WebServices project:

EAM Connection
Grid Configuration
Cache Settings
Authentication

Configure your INFOR EAM connection settings:

appsettings.json

{
  "EAMBaseUrl": "https://your-eam-server.com/axis/services",
  "EAMCredentials": [
    {
      "Username": "your-eam-username",
      "Password": "your-eam-password",
      "Organization": "your-organization-code"
    }
  ]
}

Never commit real credentials to version control. Use environment variables or Azure Key Vault for production.

Configure EAM grid settings for each grid you want to expose:

appsettings.json

{
  "EAMGrids": [
    {
      "GridName": "PurchaseOrders",
      "UserFunction": "SSPPOR",
      "GridId": 123,
      "DataSpyIds": {
        "PreviousDay": 1001,
        "PreviousMonth": 1002,
        "CurrentMonth": 1003,
        "LastYear": 1004,
        "Custom": 1005,
        "AllRecords": 1006
      },
      "NumberRecordsFirstReturned": 1000,
      "CursorPosition": 0,
      "HGTGridType": 1,
      "HGTGridName": 1,
      "FilterField": "CREATED_DATE"
    }
  ],
  "EAMDefaultRecords": 100
}

Grid IDs and DataSpy IDs are specific to your INFOR EAM configuration. Contact your EAM administrator for correct values.

Configure the SQLite cache behavior:

appsettings.json

{
  "ConnectionStrings": {
    "GridCache": "Data Source=gridcache.db"
  },
  "GridCache": {
    "Enabled": true,
    "ExpirationMinutes": 60
  }
}

Enabled: Set to false to disable caching (not recommended)
ExpirationMinutes: How long cached data remains valid (default: 60 minutes)

Enable or disable Basic Authentication:

appsettings.json

{
  "EnableAuthScheme": true,
  "ApiTitle": "HGT - Grid API",
  "ApiDescription": "API REST para acceder a las grillas de EAM de HGT"
}

Set EnableAuthScheme to true in production environments to protect your API endpoints.

Running the Application

Start the Application

Run the project using the .NET CLI:

dotnet run --project HGT.EAM.WebServices/HGT.EAM.WebServices.csproj

Or if you’re already in the project directory:

cd HGT.EAM.WebServices
dotnet run

The application will start and display the listening URLs (typically https://localhost:5001).

Verify Startup

Check the console output for successful startup messages:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

The SQLite cache database will be created automatically on first run.

Access API Documentation

Open your browser and navigate to the Scalar documentation interface:

https://localhost:5001/scalar/v1

You’ll see an interactive API reference with all available endpoints, organized by category:

Abastecimiento (Provision)
Contabilidad (Accounting)
Cuentas por Pagar (Accounts Payable)
Control de Gestión (Management)

Making Your First API Call

Let’s make a request to fetch accounting transactions:

curl -X GET "https://localhost:5001/api/accounting/transactions?TypeFilter=3&Page=1&PagSize=10" \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Accept: application/json"

Understanding the Parameters

The API uses common query parameters across most endpoints:

TypeFilter

integer

required

Filter type for data retrieval:

1 = Previous day
2 = Previous month
3 = Current month
4 = Last year
5 = Custom month/year (requires Month and Year parameters)

Page

integer

default:"1"

Page number for pagination (starts at 1)

PagSize

integer

Number of records per page (if not specified, uses EAMDefaultRecords from config)

Month

integer

Specific month (1-12) - required when TypeFilter is 5

Year

integer

Specific year - required when TypeFilter is 5

Example Response

Successful requests return a standardized response structure:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "grid": {
      "fields": [
        {
          "name": "TRANSACTION_ID",
          "label": "Transaction ID",
          "type": "string"
        },
        {
          "name": "AMOUNT",
          "label": "Amount",
          "type": "number"
        }
      ],
      "rows": [
        {
          "TRANSACTION_ID": "TRX-001",
          "AMOUNT": 1500.00
        },
        {
          "TRANSACTION_ID": "TRX-002",
          "AMOUNT": 2300.50
        }
      ]
    },
    "pagination": {
      "currentPage": 1,
      "pageSize": 10,
      "totalRecords": 156,
      "totalPages": 16
    }
  }
}

Testing Different Endpoints

Try these common endpoints to explore the API:

Provision
Accounting

Purchase Orders

GET /api/provisions/view/purchase/order?TypeFilter=3&Page=1

Contracts

GET /api/provisions/contracts?TypeFilter=2&Page=1

Purchase Order Audit

GET /api/provisions/purchase/order/audit?TypeFilter=3&Page=1

Transactions

GET /api/accounting/transactions?TypeFilter=3&Page=1&PagSize=20

Kardex Report

GET /api/accounting/kardex?TypeFilter=3&Page=1

All endpoints support response caching with a 15-minute (900 seconds) cache duration. Subsequent identical requests will return cached results for faster response times.

Rate Limiting

The API implements rate limiting to prevent abuse:

Limit: 60 requests per minute
Per: Authenticated user or IP address (for anonymous requests)
Response: HTTP 429 (Too Many Requests) when limit exceeded

Rate Limit Response

{
  "statusCode": 429,
  "message": "Too many requests",
  "retryAfterSeconds": 30
}

When you receive a 429 response, check the Retry-After header or retryAfterSeconds field to know when you can retry.

Troubleshooting

401 Unauthorized

Problem: Authentication failedSolutions:

Verify your Basic Auth credentials are correct
Ensure the Authorization header is properly formatted: Basic base64(username:password)
Check if EnableAuthScheme is set to true in appsettings.json

Cache Not Working

Problem: Data is not being cached or cache is staleSolutions:

Delete the SQLite cache database: rm gridcache.db
Check GridCache.Enabled is set to true in configuration
Verify the cache directory has write permissions
Check logs for Entity Framework errors

Cannot Connect to INFOR EAM

Problem: API cannot reach INFOR EAM servicesSolutions:

Verify EAMBaseUrl is correct and accessible from your network
Check EAM credentials are valid
Ensure firewall allows outbound SOAP connections
Test EAM endpoint directly using a SOAP client

Empty or Invalid Grid Data

Problem: API returns empty results or errorsSolutions:

Verify GridId and DataSpyIds are correct for your EAM configuration
Check that the user has permissions to access the grid in EAM
Review Serilog logs for detailed error messages
Confirm the UserFunction matches the EAM grid’s function code

Next Steps

API Reference

Explore detailed documentation for all endpoints

Configuration Guide

Learn about advanced configuration options

Architecture

Understand the project structure and design patterns

Setup Guide

Learn about deployment and production setup

Congratulations! You’ve successfully set up HGT EAM WebServices and made your first API call.

Get Started

Core Concepts

Guides

Prerequisites

.NET 9.0 SDK

SQL Server

INFOR EAM Access

Code Editor

Installation

Configuration

Running the Application

Making Your First API Call

Understanding the Parameters

Example Response

Testing Different Endpoints

Rate Limiting

Troubleshooting

Next Steps

API Reference

Configuration Guide

Architecture

Setup Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Prerequisites

.NET 9.0 SDK

SQL Server

INFOR EAM Access

Code Editor

​Installation

​Configuration

​Running the Application

​Making Your First API Call

​Understanding the Parameters

​Example Response

​Testing Different Endpoints

​Rate Limiting

​Troubleshooting

​Next Steps

API Reference

Configuration Guide

Architecture

Setup Guide

Build docs developers (and LLMs) love

Prerequisites

Installation

Configuration

Running the Application

Making Your First API Call

Understanding the Parameters

Example Response

Testing Different Endpoints

Rate Limiting

Troubleshooting

Next Steps