Turnstile Integration

Technical specifications for integrating NFCtron ticketing with external turnstile systems

:::warning Confidentiality Notice Proprietary information of NFCtron. Provided for integration purposes only. Not for distribution or disclosure without written permission. :::

This documentation provides technical specifications for integrating NFCtron's ticketing system with external turnstile and access control systems. The integration enables real-time validation and processing of NFCtron tickets at venue entry points.

Overview

The NFCtron Turnstile Integration allows external turnstile systems to validate tickets and process entries through a RESTful API. The system supports both online and offline validation modes, ensuring reliable access control even when network connectivity is limited.

Ticket Specifications

NFCtron tickets are encoded as QR codes or Aztec codes with the following specifications:

Integration Flows

Online Integration Flow

The online integration flow provides real-time ticket validation through direct API communication.

Step 1: Customer Arrival

• Customer presents ticket at turnstile
• Ticket displayed as PDF or in NFCtron mobile app
• Turnstile scanner reads the QR/Aztec code

Step 2: Validation Process

• Turnstile system sends API request to NFCtron
• Request includes the 20-character ticket code
• Each request authenticated with turnstile-specific API key

Step 3: Validation Response

• ✅ Valid Ticket (HTTP 200 OK) → Turnstile should grant access
• ❌ Invalid Ticket (HTTP 400 Bad Request) → Turnstile should deny access

Step 4: Entry Confirmation

• After successful entry, turnstile system sends confirmation to NFCtron API
• Confirmation includes entry timestamp (in UTC format)
• Confirmation should be sent instantly after the entry

Offline Integration Flow

The offline integration flow allows turnstiles to operate without constant network connectivity by caching valid tickets locally.

Step 1: Tickets Retrieval

• Turnstile periodically calls the API to fetch all valid and active tickets and saves them to memory
• The API must be called at least every 5 minutes
• If a previously saved QR code is no longer present in the API response, it is considered deactivated and must be removed from the turnstile's memory
• Each request must be authenticated using a turnstile-specific API key

Step 2: Customer Arrival

• The customer presents their ticket at the turnstile
• Ticket may be shown as a PDF or in the NFCtron mobile app
• The turnstile's scanner reads the QR/Aztec code

Step 3: Validation Process

• The turnstile checks whether the scanned QR code exists in its local memory
• If the QR code is not found, the turnstile should switch to online validation mode and verify the ticket through an API request to NFCtron

Step 4: Validation Response

• ✅ Valid Ticket (HTTP 200 OK) → Turnstile should grant access
• ❌ Invalid Ticket (HTTP 400 Bad Request) → Turnstile should deny access

Step 5: Entry Confirmation

• After successful entry, turnstile system sends confirmation to NFCtron API
• Confirmation includes entry timestamp (in UTC format)
• Confirmation should be sent instantly after the entry

API Reference

Base URLs

Authentication

All API requests require authentication using a turnstile-specific API key pair.

Required Headers:

x-api-key: {your_api_key}
x-api-secret: {your_api_secret}

Important Notes:

• Keys are unique per turnstile and should not be shared
• Invalid or expired keys return 401 Unauthorized
• Contact NFCtron support to obtain API credentials

Request Format

All requests and responses use the following format:

• Content-Type: application/json
• Character encoding: UTF-8

Endpoints

Validate Ticket

Verify if a ticket is valid for entry without marking it as used.

Endpoint: GET /api/turnstile/validate

Query Parameters:

Example Request:

GET https://api.nfctron.com/api/turnstile/validate?qrCode=ABC123XYZ456DEF789GH
Headers:
  x-api-key: {your_api_key}
  x-api-secret: {your_api_secret}
  Content-Type: application/json

Success Response (200 OK):

{
	"valid": true,
	"qrCode": "ABC123XYZ456DEF789GH",
	"status": "active"
}

Error Response (400 Bad Request):

{
	"valid": false,
	"error": "Ticket not found or expired"
}

Redeem Ticket

Mark a ticket as used after successful entry.

Endpoint: POST /api/turnstile/redeem

Request Body:

Example Request:

POST https://api.nfctron.com/api/turnstile/redeem
Headers:
  x-api-key: {your_api_key}
  x-api-secret: {your_api_secret}
  Content-Type: application/json
Body:
{
  "qrCode": "ABC123XYZ456DEF789GH",
  "redeemed": "2025-03-13T10:15:30Z"
}

Success Response (200 OK):

{
	"success": true,
	"qrCode": "ABC123XYZ456DEF789GH",
	"redeemedAt": "2025-03-13T10:15:30Z"
}

Error Response (400 Bad Request):

{
	"success": false,
	"error": "Ticket already redeemed or invalid"
}

Offline Tickets

Retrieve all valid tickets for offline validation.

Endpoint: GET /api/turnstile/offline/tickets

Example Request:

GET https://api.nfctron.com/api/turnstile/offline/tickets
Headers:
  x-api-key: {your_api_key}
  x-api-secret: {your_api_secret}
  Content-Type: application/json

Success Response (200 OK):

{
	"tickets": ["ABC123XYZ456DEF789GH", "XYZ789ABC123DEF456IJ", "DEF456GHI789JKL012MN"],
	"lastUpdated": "2025-03-13T10:00:00Z"
}

Important: This endpoint should be called at least every 5 minutes when operating in offline mode.

Integration Architecture

Direct Integration (Recommended)

Recommended approach for most implementations.

• Turnstile system communicates directly with NFCtron API
• Lowest latency and highest reliability
• Simplest troubleshooting process
• No additional infrastructure required

Middleware Integration

• Communication via intermediary server (like N-tree)
• Additional configuration required
• May introduce additional latency
• Useful for legacy systems that cannot directly integrate

Error Handling

HTTP Status Codes

Error Response Format

All error responses follow this format:

{
	"error": "Error message describing what went wrong"
}

Best Practices

1. Always validate before redeeming: Use the validate endpoint first to check ticket status before granting access
2. Send confirmations immediately: Entry confirmations should be sent instantly after successful entry
3. Handle network failures gracefully: Implement retry logic with exponential backoff for failed requests
4. Monitor API health: Regularly check API availability and response times
5. Keep offline cache updated: When using offline mode, ensure tickets are refreshed at least every 5 minutes

Support

Technical Support

For integration assistance or technical questions:

Lead Backend Developer: Dominik Žabčík
📧 zabcik@nfctron.com

Chief Executive Officer: Filip Ditrich
📧 ditrich@nfctron.com