Vendor bills

The vendor bill API lets a supplier send its bills to a company in TrakIT from its own system, instead of typing them into the external portal. It does what the portal’s bills page does: create a bill, attach the scanned bill, submit it, correct and resubmit a rejected bill, and list bills with their status and payments. The same rules apply as in the portal.

Endpoint	What it does
POST /api/public/createbill	Creates a draft bill.
POST /api/public/uploadbillfile	Attaches a file to a bill.
POST /api/public/submitbill	Submits a draft bill to the company.
POST /api/public/updatebill	Changes a draft or rejected bill.
GET /api/public/getbills	Lists the supplier’s bills, with status and payments.

How a vendor key works

Each API key is tied to three things:

• one supplier: the entity the bills are from;
• one company: the company in TrakIT that the bills are addressed to;
• one external user of that supplier: the person the key acts as.

Every bill and file the key sends is recorded as added by that external user. The bills show in that user’s portal, and the company’s finance team sees them as bills sent by the supplier, the same way as bills sent through the portal. The supplier and company always come from the key: a request cannot name another supplier or company.

A key works only while all of these hold:

• the key is active and has the permission of the endpoint (see the table below);
• the external user is active and still linked to the supplier;
• the supplier still bills that company;
• the external user’s portal role allows the action, in its Vendor Bills and Documents sections.

Key permission	Endpoint	Portal role action needed
bill.create	createbill	Vendor Bills: Create
bill.update	updatebill	Vendor Bills: Update
bill.upload	uploadbillfile	Vendor Bills: Read, and Documents: Upload
bill.submit	submitbill	Vendor Bills: Submit Bill
bill.list	getbills	Vendor Bills: Read

To get a key, ask TrakIT support. Support sets the key up with its permissions, the company and the supplier’s external user. A supplier that bills two companies needs a key for each.

Typical flow

1. Create the bill with createbill. Keep the BillID it returns.
2. Attach the scanned bill with uploadbillfile. Repeat for each file.
3. Submit the bill with submitbill. It becomes Submitted and waits for the company to accept it.
4. Follow the bill with getbills: its status, due date and payments.
5. If the company rejects the bill, read its Remarks for the reason, correct it with updatebill, attach a corrected file if needed, and submit it again.

Authentication

Send the key in the APIKey header of every request, over HTTPS:

APIKey: your-api-key

Never put the key in the URL. For how keys work across the public API, see API keys.

Responses

Every endpoint answers with HTTP status 200 and the same JSON envelope:

{
  "Code": 1,
  "Info": "",
  "RetInfo": { },
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 0
}

Field	Meaning
Code	1 when the request succeeded, 0 when it was refused, -1 on an error.
Info	Why the request was refused, or the error. Empty on success.
RetInfo	The result: a bill, a list of bills, or a file.
RowsAffected	For getbills, the number of bills on the page.
Identity	The ID of what was created or changed: the bill, or the file for uploadbillfile.

Always check Code. A refused request changes nothing.

These refusals can come from any endpoint:

Info	Means
API Key Missing	The APIKey header is missing.
Key is disabled, not recognized or permission denied	The key is wrong, disabled, or lacks the endpoint’s permission.
This API key is not set up for vendor billing	The key has no supplier, company or external user.
The vendor user must be an active external user linked to the vendor	The key’s external user is locked or no longer linked to the supplier.
The vendor does not bill that company	The supplier no longer bills the key’s company.
The vendor user of this API key is locked or not permitted to do this	The external user’s portal role does not allow the action.
Bill not found	No bill with that ID belongs to the key’s supplier and company.

Bill object

createbill, updatebill, submitbill and getbills return bills in this form. Dates are yyyy-MM-dd.

{
  "BillID": 109827,
  "BillNumber": "INV-2026-0042",
  "BillDate": "2026-10-20",
  "DueDate": null,
  "CurrCode": "USD",
  "Amount": 1000.00,
  "TaxAmount": 150.00,
  "Total": 1150.00,
  "AdjTotal": 0.00,
  "PaidAmount": 0.00,
  "Outstanding": 1150.00,
  "Status": "Draft",
  "Remarks": "",
  "FileCount": 1,
  "Company": "Example Logistics Ltd"
}

Field	Meaning
BillID	The bill’s ID in TrakIT. Use it in the other endpoints.
BillNumber	The supplier’s bill number, in capitals and without spaces.
BillDate	The date of the bill.
DueDate	The due date, once the company sets it. Otherwise null.
CurrCode	The currency of the bill.
Amount	The amount before tax.
TaxAmount	The tax.
Total	The billed amount, tax included.
AdjTotal	Adjustments the company made to the bill.
PaidAmount	The amount paid so far.
Outstanding	What is still due: Total + AdjTotal - PaidAmount.
Status	Where the bill is: see Statuses.
Remarks	The company’s remarks to the supplier, such as the reason for a rejection.
FileCount	The number of files on the bill, including any the company added.
Company	The company the bill is addressed to.

Statuses

Status	Means
Draft	Created, not yet submitted. It can be changed and submitted.
Submitted	Sent to the company, waiting for it to accept the bill.
Received	Accepted by the company, or entered by the company itself, and being processed.
Approved	Validated by the company. Payments follow.
Disputed	The company disputes the bill. See Remarks.
Rejected	The company sent the bill back. See Remarks, then correct it with updatebill and submit it again.

When more than one applies, the first one in this order is shown: Rejected, Approved, Disputed, Draft, Submitted, Received.

Retries

A bill number can be used only once per supplier. If a createbill request times out and you do not know whether it went through, look the bill up with getbills?BillNumber=... before sending it again. Sending it again otherwise returns Bill Number specified already exists for this entity and office.