API Reference

The EIS Bridge Vendor API lets POS/ERP vendors send standardized sales data for BIR EIS mapping, signing, and transmission. All paths are relative to the base URL.

Base URLs

Environment	Base URL
Sandbox	`https://sandbox.eisbridge.com/v1`
Production	`https://api.eisbridge.com/v1`

Sandbox access is provisioned on request during vendor onboarding. For local development, run the Laravel API with EIS_SANDBOX_MODE=true.

Content-Type: application/json · Encoding: UTF-8

Authentication

Each vendor receives a unique API key. Include it in every request:

Authorization: Bearer VENDOR_API_KEY_123
Content-Type: application/json

If the API key is missing or invalid:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

HTTP Code	Meaning
`401`	Unauthorized — invalid or missing API key

Endpoints

POST /transactions

Description: Submit a single sale or invoice to EIS Bridge for EIS processing.

Request URL

POST {BASE_URL}/transactions

Headers

Header	Value	Required
`Authorization`	`Bearer {VENDOR_API_KEY}`	Yes
`Content-Type`	`application/json`	Yes

Request body schema

{
  "transaction": { /* Standard Sale Object — see Data Model */ }
}

Sample request

POST /v1/transactions HTTP/1.1
Host: api.eisbridge.com
Authorization: Bearer VENDOR_API_KEY_123
Content-Type: application/json

{
  "transaction": {
    "transaction_id": "POS-123456",
    "transaction_datetime": "2026-06-07T14:23:55+08:00",
    "merchant_code": "MRC123",
    "branch_code": "BR001",
    "pos_device_id": "POS01",
    "invoice_type": "OR",
    "items": [
      {
        "sku": "SKU001",
        "description": "Product A",
        "qty": 1,
        "unit_price": 100
      }
    ],
    "totals": { "gross": 100, "net": 100 },
    "payment": { "method": "CASH", "amount": 100 }
  }
}

Sample response — success

{
  "status": "accepted",
  "transaction_id": "POS-123456",
  "bridge_transaction_id": "EB-20260607-000001",
  "merchant_code": "MRC123",
  "branch_code": "BR001",
  "pos_device_id": "POS01",
  "processing_status": "queued",
  "message": "Transaction accepted for EIS processing."
}

Sample response — validation error

{
  "status": "rejected",
  "error": "validation_error",
  "message": "Missing required field: totals.net",
  "fields": ["totals.net"]
}

Error codes

HTTP	Error	Description
`201`	—	Transaction accepted for processing
`400`	`validation_error`	Missing or invalid fields
`401`	`unauthorized`	Invalid or missing API key
`403`	—	No access to merchant/branch
`409`	`transaction_conflict`	Duplicate `transaction_id` with different data
`409`	`duplicate`	Identical resubmission — returns existing `bridge_transaction_id`
`500`	—	Internal server error

POST /transactions/batch

Description: Submit multiple transactions in a single API call.

Request URL

POST {BASE_URL}/transactions/batch

Headers

Header	Value	Required
`Authorization`	`Bearer {VENDOR_API_KEY}`	Yes
`Content-Type`	`application/json`	Yes

Request body schema

{
  "batch_id": "string",
  "transactions": [ /* Standard Sale Object[] */ ]
}

Sample request

{
  "batch_id": "BATCH-20260607-001",
  "transactions": [
    {
      "transaction_id": "POS-123456",
      "transaction_datetime": "2026-06-07T14:23:55+08:00",
      "merchant_code": "MRC123",
      "branch_code": "BR001",
      "pos_device_id": "POS01",
      "invoice_type": "OR",
      "items": [{ "sku": "SKU001", "description": "Product A", "qty": 1, "unit_price": 100 }],
      "totals": { "gross": 100, "net": 100 },
      "payment": { "method": "CASH", "amount": 100 }
    },
    {
      "transaction_id": "POS-123457",
      "transaction_datetime": "2026-06-07T14:24:10+08:00",
      "merchant_code": "MRC123",
      "branch_code": "BR001",
      "pos_device_id": "POS01",
      "invoice_type": "OR",
      "items": [{ "sku": "SKU002", "description": "Product B", "qty": 2, "unit_price": 50 }],
      "totals": { "gross": 100, "net": 100 },
      "payment": { "method": "CASH", "amount": 100 }
    }
  ]
}

Sample response

{
  "status": "accepted",
  "batch_id": "BATCH-20260607-001",
  "summary": {
    "total": 2,
    "accepted": 2,
    "rejected": 0
  },
  "results": [
    {
      "transaction_id": "POS-123456",
      "bridge_transaction_id": "EB-20260607-000001",
      "processing_status": "queued"
    },
    {
      "transaction_id": "POS-123457",
      "bridge_transaction_id": "EB-20260607-000002",
      "processing_status": "queued"
    }
  ]
}

Error codes

HTTP	Error	Description
`201`	—	Batch accepted; check `summary` and per-item `results`
`400`	`validation_error`	Invalid batch structure
`401`	`unauthorized`	Invalid or missing API key
`500`	—	Internal server error

Individual transactions within a batch may be rejected while others are accepted. Inspect each entry in results.

GET /transactions/{bridge_transaction_id}

Description: Retrieve EIS Bridge and BIR EIS processing status for a submitted transaction.

Request URL

GET {BASE_URL}/transactions/{bridge_transaction_id}

Headers

Header	Value	Required
`Authorization`	`Bearer {VENDOR_API_KEY}`	Yes

Request body schema

None.

Sample request

GET /v1/transactions/EB-20260607-000001 HTTP/1.1
Authorization: Bearer VENDOR_API_KEY_123

Sample response

{
  "bridge_transaction_id": "EB-20260607-000001",
  "transaction_id": "POS-123456",
  "merchant_code": "MRC123",
  "branch_code": "BR001",
  "pos_device_id": "POS01",
  "processing_status": "sent",
  "eis_status": "acknowledged",
  "eis_reference_no": "EIS-INV-20260607-123456",
  "last_update": "2026-06-07T14:25:10+08:00",
  "logs": [
    { "timestamp": "2026-06-07T14:24:00+08:00", "event": "queued" },
    { "timestamp": "2026-06-07T14:24:30+08:00", "event": "sent_to_eis" },
    { "timestamp": "2026-06-07T14:25:10+08:00", "event": "eis_acknowledged" }
  ]
}

Error codes

HTTP	Error	Description
`200`	—	Status retrieved successfully
`401`	`unauthorized`	Invalid or missing API key
`404`	—	Transaction not found

GET /transactions

Description: List transactions filtered by date, merchant, branch, and status.

Request URL

GET {BASE_URL}/transactions?{query_params}

Headers

Header	Value	Required
`Authorization`	`Bearer {VENDOR_API_KEY}`	Yes

Query parameters

Parameter	Required	Description
`merchant_code`	Optional	Filter by merchant
`branch_code`	Optional	Filter by branch
`from`	Optional	Start of date range (ISO datetime)
`to`	Optional	End of date range (ISO datetime)
`status`	Optional	`queued` \| `sent` \| `acknowledged` \| `rejected`
`page`	Optional	Page number (default `1`)
`page_size`	Optional	Results per page (default `50`)

Sample request

GET /v1/transactions?merchant_code=MRC123&from=2026-06-07T00:00:00+08:00&to=2026-06-07T23:59:59+08:00&page=1&page_size=50
Authorization: Bearer VENDOR_API_KEY_123

Sample response

{
  "page": 1,
  "page_size": 50,
  "total": 1,
  "transactions": [
    {
      "bridge_transaction_id": "EB-20260607-000001",
      "transaction_id": "POS-123456",
      "merchant_code": "MRC123",
      "branch_code": "BR001",
      "processing_status": "sent",
      "eis_status": "acknowledged"
    }
  ]
}

Error codes

HTTP	Error	Description
`200`	—	List returned successfully
`400`	`validation_error`	Invalid query parameters
`401`	`unauthorized`	Invalid or missing API key

POST /vendors/webhook

Description: Configure a webhook URL to receive push notifications when BIR EIS responds. Webhooks are optional but recommended.

Request URL

POST {BASE_URL}/vendors/webhook

Headers

Header	Value	Required
`Authorization`	`Bearer {VENDOR_API_KEY}`	Yes
`Content-Type`	`application/json`	Yes

Request body schema

{
  "webhook_url": "string (HTTPS URL)",
  "secret": "string (shared secret for HMAC verification)"
}

Sample request

{
  "webhook_url": "https://posvendor.com/eisbridge/webhook",
  "secret": "your_webhook_secret"
}

Sample response

{
  "status": "configured",
  "webhook_url": "https://posvendor.com/eisbridge/webhook",
  "message": "Webhook URL and secret saved successfully."
}

Webhook payload (outbound to your endpoint)

{
  "event": "transaction.eis_acknowledged",
  "bridge_transaction_id": "EB-20260607-000001",
  "transaction_id": "POS-123456",
  "merchant_code": "MRC123",
  "branch_code": "BR001",
  "eis_status": "acknowledged",
  "eis_reference_no": "EIS-INV-20260607-123456",
  "timestamp": "2026-06-07T14:25:10+08:00",
  "signature": "HMAC_SHA256_SIGNATURE"
}

Verify the signature field using HMAC-SHA256 and your shared webhook secret.

Error codes

HTTP	Error	Description
`200`	—	Webhook configured successfully
`400`	`validation_error`	Invalid webhook URL
`401`	`unauthorized`	Invalid or missing API key

Global error format

{
  "error": "validation_error",
  "message": "Missing required field: totals.net",
  "fields": ["totals.net"],
  "code": "EB-VAL-001"
}

HTTP Code	Meaning
`200`	OK
`201`	Created / Accepted
`400`	Bad request (validation error)
`401`	Unauthorized (invalid/missing API key)
`403`	Forbidden (no access to merchant/branch)
`404`	Not found
`409`	Conflict (duplicate `transaction_id`)
`500`	Internal server error