API and integrations

Other software works with PALBONTradeFinance over HTTP: the standard record API for every record type, and PALBONTradeFinance's own methods for forms, record actions, workflow actions, the assistant, dashboards and SWIFT text. Every call runs with the permissions of the user it signs in as, and goes through the same validation, workflow and audit trail as the screens.

The full, generated list of endpoints with their parameters is the API reference at /api-docs/tradefinance (signed-in users), with an OpenAPI 3 document for code generators.

Use an API key and secret of a dedicated integration user:

In Desk, open the user (/app/user/<email>) and give it only the roles the integration needs (for example Trade Finance Executive to record credits).
Settings › API Access › Generate Keys. Copy the secret once; it is not shown again. Keep it in your secret store, never in code.
Send it on every request:

Authorization: token <api_key>:<api_secret>

Browser sessions (signed in through /login) work too; they also need the X-Frappe-CSRF-Token header on changes.

2. Records

Every record type is available at /api/resource/<Record Type>:

Method	Path	Does
GET	`/api/resource/Letter of Credit?filters=[["status","=","Issued"]]&fields=["name","lc_number","expiry_date"]`	List (with filters, fields, `order_by`, `limit_start`, `limit_page_length`)
GET	`/api/resource/Letter of Credit/LC-2026-00001`	One record, with its tables
POST	`/api/resource/Trade` with a JSON body	Create
PUT	`/api/resource/Trade/TRD-2026-00001` with the changed fields	Update
DELETE	`/api/resource/Trade/TRD-2026-00001`	Delete (when allowed)

Example: create a back-to-back trade.

curl -X POST "https://<your-site>/api/resource/Trade" \
  -H "Authorization: token $PALBON_API_KEY:$PALBON_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "trade_title": "T.0201 Steam Coal",
    "company": "<company>",
    "trade_type": "Back-to-Back",
    "commodity": "<item code>",
    "quantity": 50000, "uom": "MT", "tolerance_pct": 10,
    "currency": "USD", "incoterm": "FOB",
    "legs": [
      {"leg_type": "Purchase", "party_type": "Supplier", "party": "<supplier>", "price": 51.72, "currency": "USD"},
      {"leg_type": "Sale", "party_type": "Customer", "party": "<customer>", "price": 52.39, "currency": "USD"}
    ]
  }'

Field names are the record types' own (shown in the API reference and in Desk's Customize Form). Workflow-controlled records start in their first state; move them with a workflow action (below), never by writing the state field.

3. PALBONTradeFinance methods

Call a method with POST /api/method/<path> (or GET for reads). Each path also works with the PALBON alias palbon.tradefinance. in place of palbon_trade., for example palbon.tradefinance.trade_process.api.take_action.

Path	Does
`palbon_trade.trade_process.api.record_actions` (`doctype`, `name`)	The workflow actions open to the user on a record, and why others are not
`palbon_trade.trade_process.api.take_action` (`doctype`, `name`, `action`, `comment`)	Takes a workflow action, for example `Approve Issuance`; checks roles, conditions, approvals, required fields and four eyes
`palbon_trade.trade_process.api.simulate` (`doctype`, `name`, `role`)	What a role could do on a record, without doing it
`palbon_trade.api.form.get_form` (`doctype`, `name`)	A record with its fields, tables, rights, workflow actions, record actions and print designs
`palbon_trade.api.form.run_tool` (`doctype`, `name`, `method`)	Runs a record action (below)
`palbon_trade.api.form.get_activity` (`doctype`, `name`)	The record's activity: comments, changes, workflow moves
`palbon_trade.api.assistant.understand` (`sentence`, `channel`) then `run` (`token`)	Asks the assistant; a change comes back as a preview with a token
`palbon_trade.api.assistant.confirm` / `cancel` (`token`)	Confirms or cancels a previewed change
`palbon_trade.api.assistant.read_document` (`doctype`, `file_url`)	Reads an uploaded file into a record type's fields; saves nothing
`palbon_trade.api.dashboard.get_command_centre`	The overall dashboard's figures
`palbon_trade.api.guarantee.write_mt760` (`name`) / `write_mt767` (`name`, `new_amount`, `new_expiry`, `text`)	A guarantee's SWIFT messages as drafts
`palbon_trade.trade_risk.audit_trail.verify_chain`	Verifies the audit trail
`palbon_trade.api.automation.try_rule` (`name`, `reference_name`)	What an automation rule would do on a record

3.1 Record actions for `run_tool`

Record type	`method`
Letter of Credit	`check_against_contract`, `generate_mt700`, `propose_amendment`
Trade Contract	`refresh_deviations`, `email_to_counterparty`, `send_for_esignature`
Laytime Calculation	`reload_from_voyage`, `raise_note`
SWIFT Message	`apply_to_lc`
Document Instruction	`run_checks`, `prepare_our_documents`, `draw_bill_of_exchange`
Surveyor Work Order	`email_to_surveyor`
Commercial Settlement	`make_invoice`, `record_payment`
Voyage	`raise_freight_invoices`
Sanctions Screening	`run`

Each returns {"say": "<what happened>", "open": [<record type>, <name>]} when it made a record.

Example: approve a credit's issuance.

curl -X POST "https://<your-site>/api/method/palbon_trade.trade_process.api.take_action" \
  -H "Authorization: token $PALBON_API_KEY:$PALBON_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"doctype": "Letter of Credit", "name": "LC-2026-00003", "action": "Approve Issuance", "comment": "Facility headroom checked"}'

4. SWIFT text from your bank

Post the bank's message as a SWIFT Message record, then apply it:

curl -X POST "https://<your-site>/api/resource/SWIFT Message" \
  -H "Authorization: token $PALBON_API_KEY:$PALBON_API_SECRET" -H "Content-Type: application/json" \
  -d '{"message_type": "MT700", "direction": "Incoming", "raw_text": "<the MT700 text>"}'

curl -X POST "https://<your-site>/api/method/palbon_trade.api.form.run_tool" \
  -H "Authorization: token $PALBON_API_KEY:$PALBON_API_SECRET" -H "Content-Type: application/json" \
  -d '{"doctype": "SWIFT Message", "name": "<SWF-…>", "method": "apply_to_lc"}'

The record's errors field (on screen: Problems Found) lists missing mandatory fields. Outgoing MT700, MT760 and MT767 drafts are read the same way (GET /api/resource/SWIFT Message/<name>, field raw_text) to pass to your bank's channel. Direct SWIFT network connectivity is not part of this release.

5. Webhooks out

An automation rule with the action Webhook posts the record as JSON to your address when its trigger fires, for example Tell the group ERP when a trade is confirmed. A workflow state can also call a webhook On entry (see Workflows). Make the receiving endpoint idempotent: retries can repeat a call.

6. Good practice

One integration user per system, with the fewest roles it needs.
Read with filters and fields; page through large lists with limit_start and limit_page_length.
Use workflow actions to move records; do not set state fields.
Never put keys or secrets in a URL, a log or source code.