Integration Guide — CRM Customer Workspace

Introduction

This guide describes read-only endpoints under /gateway/crm/customers/{keyId} that power the CRM customer card: entity header, contacts, extra addresses, and paginated sales and receipt history with aggregate totals.

For balance by overdue periods, receivable accounts, and receipt settlement, see the CRM Current Account guide.

The public prefix is /gateway.

---

Concepts

Customer (entityKeyId)

Text identifier of the customer (up to 25 characters). All routes in this guide use this value as keyId in the URL.

Document composite key

Sales and receipt documents in the CRM workspace are identified by documentTypeId, serieId, and number. Use these three route parameters to load payment details or sale body lines.

---

Endpoints

Method	URL	Description
GET	/gateway/crm/customers/{keyId}	Entity header, contacts, and extra addresses
GET	/gateway/crm/customers/{keyId}/receipts	Paginated receipt headers and paymentsAmount aggregate
GET	/gateway/crm/customers/{keyId}/receipts/{documentTypeId}/{serieId}/{number}/payment-details	Payment lines grouped by payment type
GET	/gateway/crm/customers/{keyId}/sales	Paginated sale headers and salesTotal aggregate
GET	/gateway/crm/customers/{keyId}/sales/{documentTypeId}/{serieId}/{number}/lines	Body lines of a sale document

Route parameter: keyId — customer entityKeyId.

Sales and receipt tabs are loaded on demand: the workspace endpoint returns only the header, contacts, and addresses. Call /receipts or /sales when the user opens those tabs.

Workspace response (200 OK)

{
  "entity": {
    "keyId": "CLI001",
    "name": "Example Customer Lda",
    "balance": 1250.5,
    "limitCredit": 5000,
    "lastPurchase": "2026-05-20T00:00:00Z"
  },
  "contacts": [
    {
      "id": 1,
      "name": "John Smith",
      "email1": "john@example.com",
      "mobilePhone1": "+351900000000"
    }
  ],
  "addresses": [
    {
      "id": 1,
      "addressLine1": "Rua Example 1",
      "city": "Lisbon",
      "postalCode": "1000-001"
    }
  ]
}

The entity object includes financial summary fields (balance, limitCredit, lastPurchase) alongside standard address and contact data.

Paginated sales and receipts

Both list endpoints accept optional query parameters:

Parameter	Type	Description
page	int	Page number (1-based)
pageSize	int	Records per page

The response follows the paginated list structure plus an aggregate total:

Endpoint	Aggregate field	Description
/receipts	paymentsAmount	Sum of receipt totals across all matching documents
/sales	salesTotal	Signed sum of sale totals (cashier flow applied)

Each data item includes documentTypeId, serieId, number, documentIdentifier, createDate, and totalAmount. Use the three-part key to open detail endpoints.

Receipt header fields (summary): otherValues, virtualTotalAmount, salesmanName, observation.

Sale header fields (summary): salesmanId, salesmanName, headerDiscountPercent, headerDiscountAmount, observation.

Receipt payment details

Returns an array of payment lines grouped by payment type:

Field	Description
paymentTypeId	Payment type identifier
paymentTypeDescription	Payment type label
netAmount	Net amount for this payment type
paymentMechanism	Payment mechanism code
currencyId, currencyRate	Currency and exchange rate
isChange	Whether the line represents change
bankDetail	Bank details when applicable (account, check, deferred date, …)

Sale body lines

Returns an array of document body lines:

Field	Description
itemKeyId	Item identifier
description	Line description
quantity	Quantity
taxIncludedPrice	Unit price with tax
discountPercent	Line discount percentage
lineTotal	Line total

---

Paginated list structure

Field	Type	Description
totalCount	int	Total records
pageSize	int	Page size
currentPage	int	Current page (1-based)
totalPages	int	Total pages
data	array	Documents on the page

/receipts and /sales responses also include paymentsAmount or salesTotal, respectively.

---

Examples

Customer workspace

GET /gateway/crm/customers/CLI001

See Gets the CRM workspace listing for the customer.

Paginated receipts

GET /gateway/crm/customers/CLI001/receipts?page=1&pageSize=20

See Gets paginated receipt document headers for the customer.

Receipt payment details

GET /gateway/crm/customers/CLI001/receipts/5/1/100/payment-details

See Gets payment details for a receipt document.

Paginated sales

GET /gateway/crm/customers/CLI001/sales?page=1&pageSize=20

See Gets paginated sale document headers for the customer.

Sale body lines

GET /gateway/crm/customers/CLI001/sales/2/1/250/lines

See Gets the body lines of a sale document.

---

Recommended flow

1. Identify the customer — obtain entityKeyId.
2. Open CRM card — GET /gateway/crm/customers/{keyId} for header, contacts, and addresses.
3. Sales or receipt history — GET .../sales or GET .../receipts when the user opens those tabs.
4. Document detail — use documentTypeId, serieId, and number on line or payment endpoints.

For balance, open items, and settlement, follow the CRM Current Account guide.

---

Common errors

HTTP code	Situation	Suggested action
401	Missing or invalid token	Authenticate on the gateway
404	Unknown keyId or document key	Verify identifiers

---

Conclusion

The CRM customer workspace exposes read access to the customer card and commercial history under /gateway/crm/customers/{keyId}. Load sales and receipts on demand and use the composite key to access body lines and payment details.

---

Last updated: 2 June 2026