{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-openapi.yaml","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"openapi.yaml","dynamicMarkdocComponents":[],"baseSlug":"/openapi","seo":{"title":"Partner Integration API"},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"Partner Integration API","description":"API specification for freight forwarding system (FFS) partners integrating with BravoTran.\n\n## Overview\n\nBravoTran uses an event-driven pull model to stay in sync with your freight forwarding system:\n\n1. Your system sends an **event notification** to BravoTran when an entity is created or updated.\n2. BravoTran reads the entity type and identifier from the event.\n3. BravoTran issues a `GET` request to your API with the entity type and identifier.\n4. Your API returns the entity as JSON per this specification.\n\nBravoTran 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.\n\n![API Flow Diagram](images/api-flow.png)\n\n### Polling alternative\n\nIf 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 so that newly created payables invoices are also surfaced.\n\nCreates 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.\n\n## Terminology\n\n| Term | Definition |\n|------|-----------|\n| **FFS** | Freight Forwarding System — your system |\n| **Company** | A country-level entity in the FFS; maps to a BravoTran **Account** |\n| **Account** | BravoTran's representation of a company/country |\n| **Org** | Vendors, carriers, creditors, debtors |\n| **Job** | A consol (consolidation/master) or shipment (house) |\n| **Accrual** | Expected charges on a job |\n| **Charge Line** | Line items on a payables invoice |\n| **Payables Invoice** | AP invoice from a creditor |\n| **Outbound Payables Invoice** | Approved invoice posted from BravoTran to the partner's system for cost posting |\n\nBravoTran 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.\n\n## Conventions\n\n- **`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.\n- **`updated_at`** — [ISO 8601](https://en.wikipedia.org/wiki/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.\n- **Amounts** — Wherever there is an amount, a corresponding `currency` ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) must be provided.\n- **Country codes** — Country fields use [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) two-letter codes.\n- **Nested references** — Related entities are represented as nested objects containing at minimum an `external_id`.\n\n## Staff\n\nStaff data will be provided via flat file. Documentation forthcoming.\n\n## Charge Codes\n\nCharge code data will be provided via flat file. Documentation forthcoming. Accruals and charge lines reference charge codes by `external_id`; the mapping is maintained through the flat file data.\n\n## Tax Codes\n\nTax code data will be provided via flat file. Documentation forthcoming.\n\n## Authentication\n\nBoth directions of communication support one of the following authentication methods, agreed upon during onboarding:\n\n- **OAuth 2.0** — Client credentials flow\n- **Bearer Token** — Static token in the `Authorization` header\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"apidocs.bravotran.com","port":4000,"ipAddress":"216.73.216.140"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/openapi","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}