Partner Integration API (1.5.0)

Overview

BravoTran uses an event-driven pull model to stay in sync with your freight forwarding system:

1. Your system sends an event notification to BravoTran when an entity is created or updated.
2. BravoTran reads the entity type and identifier from the event.
3. BravoTran issues a GET request to your API with the entity type and identifier.
4. Your API returns the entity as JSON per this specification.

BravoTran also POSTs approved invoices to your system for cost posting. When an invoice is approved in BravoTran, it sends a POST /payables-invoices request to your API with the invoice details. Your system must create or record the invoice accordingly.

Polling alternative

If your system cannot reliably push live event notifications, you may instead implement the optional list endpoints GET /orgs, GET /jobs, and GET /payables-invoices. BravoTran will periodically poll them with an updated_after window, get back the identifiers of anything that changed, then call the existing single-entity detail endpoints to fetch each one. Implement either the events API or the list endpoints — not both. All three list endpoints must be implemented together; BravoTran's polling assumes complete coverage of all entity types.

Creates and updates are surfaced through the same filter: when an entity is created, set updated_at to the creation timestamp and it will appear in any subsequent polling response whose updated_after is at or before that timestamp. There is no separate "creation" feed.

Terminology

BravoTran maps a Company in the FFS to an Account in BravoTran. Often a company represents a country. It is acceptable to have more than one account for a country if that country has multiple companies, but a single account must never represent multiple companies or countries.

Conventions

• external_id — Unique, immutable identifier for every entity. Used as the foreign key between systems. Typically the primary key in your database. Not visible to end users. The example external_id values throughout these docs are GUIDs, but they don't have to be — an external_id is whatever the stable identifier for the entity is in the FFS.
• updated_at — ISO 8601 timestamp of when the entity was last modified. BravoTran uses this as a version marker to prevent overwriting with stale data. For jobs, this must update when any child data changes (e.g., accrual added/edited, shipment added to consol). On creation, updated_at must be set to (at least) the creation timestamp so newly created entities appear in polling responses alongside updates — the polling endpoints make no distinction between creates and updates.
• Amounts — Wherever there is an amount, a corresponding currency (ISO 4217) must be provided.
• Local vs. overseas amounts — local_amount is in the account's local currency (the currency of the country the forwarder operates in). overseas_amount is in the vendor's currency — whatever currency the charge or invoice is denominated in. The two may be the same (e.g., a domestic vendor).
• Country codes — Country fields use ISO 3166-1 alpha-2 two-letter codes.
• Nested references — Related entities are represented as nested objects containing at minimum an external_id.
• Error codes — Error responses use lower_snake codes in both directions. BravoTran keys off the HTTP status rather than partner error bodies.

Staff

Staff data is provided via flat file — typically a spreadsheet export from the FFS. Any format your FFS can export works; field names don't matter as long as the required contents are present. If you don't have an existing export, use the recommended format, which lists each field and whether it is required. Alternatively, implement GET /staff and BravoTran will fetch staff data from your API instead.

Charge Codes

Charge code data is provided via flat file — typically a spreadsheet export from the FFS. Any format your FFS can export works; field names don't matter as long as the required contents are present. If you don't have an existing export, use the recommended format, which lists each field and whether it is required. Alternatively, implement GET /charge-codes and BravoTran will fetch charge code data from your API instead. Accruals and charge lines reference charge codes by external_id; the mapping is maintained through the charge code data.

Tax Codes

Tax code data is provided via flat file — typically a spreadsheet export from the FFS. Any format your FFS can export works; field names don't matter as long as the required contents are present. If you don't have an existing export, use the recommended format, which lists each field and whether it is required. Alternatively, implement GET /tax-codes and BravoTran will fetch tax code data from your API instead.

Authentication

Each direction of communication supports one of the following authentication methods, agreed upon during onboarding:

BravoTran → Partner (partner-hosted endpoints):

• OAuth 2.0 — Client credentials flow
• Bearer Token — Static token in the Authorization header

Partner → BravoTran (POST /events):

• OAuth 2.0 — Client credentials flow
• Token — API token in the Authorization header, formatted as Token token=<token>
• API Key — API token in the x-api-key header

Changelog

1.5.0 — 2026-08-28

• Charge codes returned by GET /charge-codes now include a required charge_type field classifying the charge as freight, origin, destination, or other.

1.4.0 — 2026-07-17

• Renamed the org reference to creditor on job accruals (GET /jobs/{external_id}), payables invoices (GET /payables-invoices/{external_id}), and outbound payables invoices (POST /payables-invoices). The referenced entity is still an org fetched via the /orgs endpoints; the key now reflects the role the org plays on these records.

1.3.0 — 2026-07-16

• Payables invoice responses now include a status field (draft or posted) — in both GET /payables-invoices/{external_id} and the POST /payables-invoices response body.
• POST /payables-invoices charge lines now always include an accrual reference whose external_id matches an accrual returned by GET /jobs/{external_id} (null when the charge line has no matching accrual).
• Job accruals now include a tax_code reference. Like other tax fields, it is optional for non-tax / US-based accounts.
• Added supporting data endpoints — GET /staff, GET /charge-codes, and GET /tax-codes — as an alternative to flat file delivery of staff, charge code, and tax code data.
• POST /payables-invoices now documents a 409 response with error code duplicate_invoice, returned when an invoice with the same invoice_number already exists for the org.

1.2.0 — 2026-07-08

• POST /payables-invoices requests no longer include an external_id. Your system generates its own identifier for the created invoice and returns it as external_id in the 200 response. BravoTran stores that identifier and uses it for GET /payables-invoices/{external_id}.
• POST /events error responses now use lower_snake error codes (validation_error, invalid_json, unauthorized), matching the partner-hosted endpoints.

1.1.0 — 2026-07-07

• tax is now required on invoice-level and charge-line amounts returned by GET /payables-invoices/{external_id} for tax-enabled accounts. Non-tax / US-based accounts are unaffected.
• Zero-tax lines must state tax: 0.0 explicitly rather than omitting the field or sending null.