Latest Developer SDK - generated 2026-11-07 15:22 UTC

BI Soft Tech Services LLC Developer SDK

Current integration guide for ERP developers, accountants, API users, and ASP onboarding teams. This page documents live local endpoints on http://127.0.0.1:8002, production URLs, authentication, JSON invoice payloads, PINT-AE / UBL XML, PDF evidence, document status, onboarding, customer/supplier/product setup, and OpenAPI downloads.

UAE MoF ready PINT-AE / UBL XML Peppol BIS Billing 3.0 ERPGlobal PostgreSQL Sandbox credentials required for production

Quick Start

Local Base URLhttp://127.0.0.1:8002

Use this for local testing and portal validation.

Sandbox Base URLhttps://sandbox.asp.bisofttechservices.com

Use after sandbox gateway credentials are issued.

Production Base URLhttps://asp.bisofttechservices.com

Use only after onboarding and certification readiness.

Common headers: Content-Type: application/json, Accept: application/json, X-API-Key or Authorization: Bearer <token>, and optional Idempotency-Key for create operations.

Authentication

Client Credentials Token

POST /auth/authenticate accepts HTTP Basic credentials and grant_type=client_credentials. The GET page at the same URL opens a browser test form.

curl -X POST http://127.0.0.1:8002/auth/authenticate ^
  -H "Authorization: Basic BASE64(clientId:clientSecret)" ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  --data "grant_type=client_credentials"

Portal Session Login

POST /portal/api/auth/login returns a portal token. The GET page is browser-friendly and includes a live login test.

curl -X POST http://127.0.0.1:8002/portal/api/auth/login ^
  -H "Content-Type: application/json" ^
  -d "{"username":"admin@bisofttechservices.com","password":"Admin@12345"}"

Invoice and Document APIs

Method	Endpoint	Use
POST	`/v1/invoices`	Create, validate, generate UBL XML, store invoice JSON/XML, audit and lifecycle status.
POST	`/v1/invoices/validate`	Validate invoice JSON against core UAE MoF, PINT-AE and business rules.
POST	`/v1/invoices/generate`	Return JSON with generated XML, warnings and XML validation.
POST	`/v1/invoices/xml`	Return direct `application/xml` UBL invoice output.
POST	`/v1/invoices/pdf`	Return direct `application/pdf` MoF-style invoice evidence.
GET	`/v1/invoices/{uuid}`	Retrieve stored invoice detail by invoice id or UUID-compatible identifier.
GET	`/v1/invoices/{uuid}/status`	Retrieve canonical `statusCode`, Legacy field `status` compatibility, XML/PDF availability, errors and warnings.
GET	`/v1/invoices/date/{date}`	Search invoices by issue date or storage date.
GET	`/v1/invoices/{id}/xml`	Download stored XML.
GET	`/v1/invoices/{id}/pdf`	Download stored PDF evidence.
POST	`/v1/invoices/{id}/send`	Send to access point adapter and trigger webhooks.

Onboarding and Master Data APIs

POST /v1/onboarding/vat

Company registration, VAT/TRN, trade license and Peppol participant setup.

POST /v1/onboarding/users

API user onboarding and credential request payloads.

POST /v1/customers

Buyer/customer party master data.

POST /v1/suppliers

Supplier/seller party master data.

POST /v1/products

Product, SKU, VAT category, unit code and item classification setup.

POST /v1/tax/configuration

VAT/tax category, code and rate setup for ERP invoice mapping.

GET /v1/audit/logs

Audit trail query for stored invoice lifecycle events.

Storage

Payloads are stored in api_master_data while preserving invoice compatibility.

Compliance Coverage

UAE MoF / PINT-AE

Mandatory supplier/buyer identity, TRN/VAT data, invoice type codes, issue dates, AED currency handling, monetary totals, tax totals and line-level VAT checks.

UBL XML / Peppol BIS Billing 3.0

UBL 2.1 invoice generation, profile/customization identifiers, parties, payment means, allowance/charge, tax category, legal monetary total and invoice lines.

Audit and Evidence

JSON payload, generated XML, PDF evidence, validation warnings/errors, lifecycle state, audit log and webhook delivery diagnostics.

StatusCode Flow

DRAFT → VALIDATING → VALID or INVALID → SUBMITTED → ACCEPTED or REJECTED; CANCELLED is terminal. Transport failures return to retryable VALID.

statusCode is authoritative and read-only. The legacy status field remains in responses for existing clients.

Try It

Sample Invoice JSON

API Result

Run a Try It action. The local API key header is added automatically for this page.

Invoice Period

Use the optional invoicePeriods array in create, validate, generate, update, and read payloads. The installed PINT-AE 1.0.3 profile permits at most one header period (IBR-097).

{"invoicePeriods":[{"startDate":"2026-09-01","endDate":"2026-09-30","descriptionCode":"MTH","sequenceNo":1}]}

UBL mappings: /ubl:Invoice/cac:InvoicePeriod/cbc:StartDate, /cbc:EndDate, and /cbc:DescriptionCode. Sequence is internal, positive ordering. The array may be omitted for existing invoices.

Exchange Rate

Use the optional exchangeRates array in create, validate, generate, update, and read payloads. PINT-AE 1.0.3 supports one TaxExchangeRate; its currencies must match currency and taxCurrencyCode.

{"exchangeRates":[{"exchangeRateType":"TaxExchangeRate","sourceCurrencyCode":"USD","targetCurrencyCode":"AED","calculationRate":"3.6725","rateDate":"2026-09-18","exchangeMarketId":"Central Bank"}]}

UBL mapping: /ubl:Invoice/cac:TaxExchangeRate. Legacy currencyExchangeRate remains accepted and is normalized into this collection.

Prepaid Payments

Use the optional prepaidPayments array for zero or more payments. When rows are supplied, prepaidAmount must equal their total.

{"prepaidAmount":"500.00","prepaidPayments":[{"paymentId":"PAY-001","paidAmount":"500.0000","receivedDate":"2026-09-18","paidDate":"2026-09-18"}]}

UBL mapping: /ubl:Invoice/cac:PrepaidPayment with cbc:ID, cbc:PaidAmount, cbc:ReceivedDate, and cbc:PaidDate. Existing requests may omit the array.

Document Flags

The optional documentFlags object is the named representation of the PINT-AE eight-bit invoiceTransactionTypeCode. When both are supplied they must match.

{"documentFlags":{"isSelfBilled":false,"isFTZ":false,"isDeemed":false,"isMargin":false,"isSummary":false,"isContinuous":false,"isDAB":false,"isECommerce":false,"isExport":true},"invoiceTransactionTypeCode":"00000001"}

The eight transaction flags map, in order, to cbc:ProfileExecutionID. Self-billing controls the existing PINT-AE self-billing profile and remains separate from those eight bits.

Additional Document References

Use additionalDocumentReferences for zero or more ordered supporting-document references. documentIdentifier is required and sequenceNo must be unique and at least 1.

{"additionalDocumentReferences":[{"documentIdentifier":"PO-2026-000123","documentTypeCode":"130","schemeID":"AUN","documentDescription":null,"attachmentURI":null,"sequenceNo":1}]}

UBL mapping: /cac:AdditionalDocumentReference/cbc:ID; embedded files use cac:Attachment/cbc:EmbeddedDocumentBinaryObject with Base64 content, mimeCode, and filename; external URIs use cac:Attachment/cac:ExternalReference/cbc:URI. The server calculates SHA-256, limits Portal uploads to 5 MB, omits binary content from normal invoice detail/list responses, and requires the invoice tenant/company ownership chain for metadata and downloads.

Code Samples

Downloads and Live Docs

OpenAPI JSON

Machine-readable API contract.

Open JSON

OpenAPI YAML

Developer-friendly API contract.

Open YAML

Swagger UI

Interactive browser API documentation.

Open Swagger