External API Integration

External API Integration enables SmartReader to communicate with external systems for product verification, order management, and data publishing. This feature allows the reader to query external APIs for product information, search for orders, publish RFID data to external systems, and perform analysis operations.

Overview

External API Integration provides:

• Product Verification: Query external systems to verify product information by GTIN

• Order Management: Search and retrieve order information from external systems

• Data Publishing: Publish RFID tag data and order status updates to external APIs

• Analysis Operations: Submit analysis payloads for order processing and finalization

• Event Logging: Automatic logging of all external API calls for monitoring and auditing

Configuration

External API Integration must be enabled and configured before use. Configure the following settings:

Enable External API Integration

Set enableExternalApiVerification to "1" in your reader configuration to enable the feature.

Required Configuration Settings

Setting	Description	Example
externalApiVerificationSearchProductUrl	Base URL for product lookup by GTIN	https://api.example.com/products/
externalApiVerificationSearchOrderUrl	URL for order search operations	https://api.example.com/orders/search
externalApiVerificationPublishDataUrl	URL for publishing RFID data	https://api.example.com/events/publish
externalApiVerificationChangeOrderStatusUrl	URL for updating order status	https://api.example.com/orders/
externalApiVerificationHttpHeaderName	HTTP header name for authentication	ApiKey or Authorization
externalApiVerificationHttpHeaderValue	HTTP header value for authentication	Your API key or token

Optional Configuration Settings

Setting	Description
externalApiVerificationAuthLoginUrl	URL for OAuth/token authentication
externalApiAnalysisUrl	URL for analysis operations (ANALYZE/FINALIZE)
externalApiAnalysisKey	API key for analysis endpoint
networkProxy	Proxy server address (if required)
networkProxyPort	Proxy server port

Configuration via Reader Settings

1. Navigate to Reader Settings in the web interface

2. Locate the External API Integration section

3. Enable the feature by setting enableExternalApiVerification to "1"

4. Enter the required API URLs and authentication credentials

5. Click Apply Settings and reload the application

Configuration via API

You can also configure external API settings via the REST API:

curl -X POST \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Content-Type: application/json" \
  https://<reader-ip>:8443/api/settings \
  -d '{
    "enableExternalApiVerification": "1",
    "externalApiVerificationSearchProductUrl": "https://api.example.com/products/",
    "externalApiVerificationSearchOrderUrl": "https://api.example.com/orders/search",
    "externalApiVerificationPublishDataUrl": "https://api.example.com/events/publish",
    "externalApiVerificationHttpHeaderName": "ApiKey",
    "externalApiVerificationHttpHeaderValue": "your-api-key-here"
  }'

Features

Product Verification

Query external systems to retrieve product information by GTIN (Global Trade Item Number).

Use Cases:

• Verify product details when tags are read

• Retrieve product metadata for validation

• Enrich tag data with product information

Example Request:

curl -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  https://<reader-ip>:8443/api/external/query/product/00012345600012

Response: Returns product information in JSON format from the external API.

Order Management

Search and retrieve order information from external systems.

Search Orders (POST):

curl -X POST \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Content-Type: application/json" \
  https://<reader-ip>:8443/api/external/query/order \
  -d '{
    "facility": "PDX",
    "status": "Released",
    "updatedSince": "2024-10-01T00:00:00Z"
  }'

Get Order by Code:

curl -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  https://<reader-ip>:8443/api/external/query/order/ORD-1000456

Data Publishing

Publish RFID tag data and order status updates to external systems.

Publish Data (POST):

curl -X POST \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Content-Type: application/json" \
  https://<reader-ip>:8443/api/external/publish \
  -d '{
    "orderId": "ORD-1000456",
    "status": "Released",
    "lines": [
      { "lineId": "1", "gtin": "00012345600012", "quantity": 24 }
    ]
  }'

Update Order Status (PUT):

curl -X PUT \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Content-Type: application/json" \
  https://<reader-ip>:8443/api/external/publish \
  -d '{
    "orderId": "ORD-1000456",
    "status": "Completed",
    "completedAt": "2024-10-02T18:15:00Z"
  }'

Analysis Operations

Submit analysis payloads for order processing and finalization. The analysis endpoint supports both manual analysis (ANALYZE) and order finalization (FINALIZE) operations.

Analysis Request:

curl -X POST \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Content-Type: application/json" \
  https://<reader-ip>:8443/api/external/analyze \
  -d '{
    "transactionId": "TXN-12345",
    "action": "ANALYZE",
    "portalId": "PORTAL-001",
    "orderId": "ORD-1000456"
  }'

Response:

{
  "success": true,
  "message": "Analysis processed successfully",
  "analysisId": "550e8400-e29b-41d4-a716-446655440000",
  "requiresAction": "RESET"
}

The requiresAction field indicates what action should be taken:

• RESET: Returned for ANALYZE actions, indicating the system should reset

• NONE: Returned for FINALIZE actions, indicating no further action needed

Bearer Token Testing

Test OAuth/token authentication endpoints before configuring them.

curl -X POST \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Content-Type: application/json" \
  https://<reader-ip>:8443/api/test \
  -d '{
    "httpAuthenticationTokenApiUrl": "https://idp.example.com/connect/token",
    "httpAuthenticationTokenApiBody": "{\"username\":\"apiuser\",\"password\":\"secret\"}"
  }'

Returns the token string if authentication is successful.

Event Logging

All external API calls are automatically logged and queued for monitoring. Each call generates an ExternalApiCallEvent that includes:

• Reader name and MAC address

• Local endpoint called

• Payload sent/received

• Remote URL called

• HTTP method used

• Response content

These events can be consumed via MQTT or other output channels for monitoring and auditing purposes.

Error Handling

External API Integration handles errors gracefully:

• Disabled Integration: If enableExternalApiVerification is "0", endpoints return empty strings or "External Integration Disabled."

• API Errors: HTTP error status codes from external APIs are propagated to the caller

• Network Errors: Connection failures are logged and return appropriate error responses

• Invalid Configuration: Missing URLs or authentication credentials result in error responses

Security Considerations

1. Authentication: Always use secure authentication methods (API keys, OAuth tokens)

2. HTTPS: Configure external APIs to use HTTPS for secure communication

3. Certificate Validation: The feature disables certificate validation by default for compatibility; consider enabling it in production

4. Credential Storage: Store API keys securely in configuration files, not in source control

5. Network Proxy: If using a proxy, ensure it's properly configured and secured

Network Proxy Support

If your deployment requires a network proxy, configure it using:

• networkProxy: Proxy server address

• networkProxyPort: Proxy server port

The proxy is used for all external API calls when configured.

Best Practices

1. Enable Only When Needed: Keep enableExternalApiVerification set to "0" when not in use

2. Use Meaningful URLs: Configure clear, descriptive API endpoint URLs

3. Monitor API Calls: Review external API call logs regularly

4. Handle Errors Gracefully: Implement retry logic in your external systems

5. Test Before Production: Use the bearer token test endpoint to verify authentication

6. Rate Limiting: Be aware of rate limits on external APIs

7. Data Validation: Validate data before publishing to external systems

API Reference

For complete API documentation, including all endpoints, request/response formats, and error codes, see the REST API documentation.

Related Features

• Validation - Tag validation that can use external API product verification

• Tasks - Task management that can integrate with external order systems

• REST API - Complete API reference for external integration endpoints