ERP API Integration

Developer Guide

ERP systems integrate with Al Yamamah ASP Core through secured APIs. The ERP sends invoice payloads, receives accepted/rejected status, and can retrieve XML/JSON evidence and document status.

Submit PINT AE invoice

POST /api/v1/invoices
Accept: application/json
Content-Type: application/json
X-ASP-API-KEY: ********
X-Source-Tenant-Domain: allowed-domain.com
Idempotency-Key: unique-request-key

Accepted response

{
  "status": "accepted",
  "validation_status": "passed",
  "document_uuid": "...",
  "connector_reference": "...",
  "trust_hash": "...",
  "qr_payload": "...",
  "errors": [],
  "links": {
    "xml": "...",
    "json": "..."
  }
}

Endpoint catalog

Method	Endpoint	Purpose	Auth
POST	`/api/v1/invoices`	Submit normalized PINT AE JSON invoice.	API Key
POST	`/api/v1/ubl/invoices`	Submit ready UBL XML invoice.	API Key
GET	`/api/v1/documents`	List documents for the authenticated client.	API Key
GET	`/api/v1/documents/{uuid}`	Get document status, validation result, and links.	API Key
GET	`/api/v1/documents/{uuid}/xml`	Download XML evidence.	API Key
GET	`/api/v1/documents/{uuid}/json`	Download original JSON evidence.	API Key

Required payload structure

{
  "source_system": "Client ERP",
  "source_tenant_domain": "allowed-domain.com",
  "invoice": {
    "id": "INV-001",
    "invoice_number": "INV-001",
    "issue_date": "2026-06-20",
    "due_date": "2026-07-20"
  },
  "pint_ae": {
    "invoice_type_code": "380",
    "invoice_transaction_type_code": "00000000",
    "invoice_currency_code": "AED",
    "business_process_type": "urn:peppol:bis:billing",
    "specification_identifier": "urn:peppol:pint:billing-1@ae-1",
    "payment_due_date": "2026-07-20",
    "payment_means_type_code": "30",
    "payment_account_identifier": "AE000000000000000000000",
    "seller": { "...": "..." },
    "buyer": { "...": "..." },
    "items": [ { "...": "..." } ],
    "tax_breakdown": [ { "...": "..." } ],
    "totals": { "...": "..." }
  }
}

Security rules

✓Never expose API keys
Keys are private credentials.
✓Send X-Source-Tenant-Domain
Must match the configured client domain.
✓Use Idempotency-Key
Safe retries without duplicate processing.
✓Verify webhooks
Use HMAC signature validation on receiving side.

Common HTTP results

`200/201`	Accepted or retrieved successfully.
`401`	Invalid/missing/expired API key.
`403`	IP/domain/client blocked.
`409`	Duplicate invoice detected.
`422`	Validation failed.
`429`	Rate limit or quota exceeded.