• Table of Contents

Terms

Definitions of terms used in this document can be found in the glossary.

Country/Company/Account Model

BravoTran maps a company in the FFS to an account in BravoTran. Often a company represents a country in the FFS. It’s ok to have more than one account in BravoTran for a country if that country has multiple companies, but it’s not ok to have one account in BravoTran represent multiple companies / countries. BravoTran will discuss this with you before starting the implementation.

General

• updated_at – ISO 8601 timestamp (ex 2024-04-25T08:00:00Z) of when the entity was last updated. BravoTran uses this as a “version” to prevent overwriting with old data if updates get out of sync.
  • This should be whenever any applicable data was updated, for example, with jobs, if an accrual is added or edited, this timestamp should update. If a shipment is added to a consol, both the shipment and consol updated_at should change.
• external_id – unique and immutable identifier for the entity used as a “foreign key” between BravoTran and the FFS. This will be used in “upserts” to BravoTran’s database.
  • If multiple tables are being combined into the orgs file, these should be prefixed with what type they are to keep the external_id unique in BravoTran. For example, vendor-123
  • This is not visible to the end user and is often the primary key in the database.
• [x] – represents an index in what would be an array in JSON.
  • For example, a job can have multiple way_bills, so there would be way_bill_1_number, way_bill_1_type, way_bill_2_number, way_bill_2_type, etc. We don’t care if they’re 0 or 1 indexed, just as long as they’re unique.
• Repeating groups ([x]) only need values in the groups you use. A group whose columns are all blank is ignored, so a job with no accruals leaves every accrual_[x]_* column blank. Within a group you do use, fields marked required must have values.
• Required: Yes means the column must be present and have a value (in each group you use, for repeating groups). Depends means the column must be present with a value when its condition applies, and is left blank otherwise. No means the column may be left out or left blank.
• Whenever there is an amount there should be a corresponding currency.
• Order of columns doesn’t matter.
• Tax in files you send to BravoTran (FFS → BravoTran): on GST/VAT accounts, tax code references (tax_code_external_id columns) are required, and every tax amount must be present, using 0.0 when there is no tax. On accounts without GST/VAT, leave tax code references blank; accrual tax amounts are still required (0.0), while invoice and charge line tax amounts may be left blank. Invoice files BravoTran sends to you follow their own rule, described with that file: tax amounts are always present.

Outbound

FFS → BravoTran

Filename Conventions

Each file should have the entity type as well as a unix timestamp to ensure files don’t get overwritten if there is a delay processing them by BravoTran.

[ENTITY_TYPE]-[UNIX_TIMESTAMP].csv

[ENTITY_TYPE] is one of: staff, orgs, jobs, payables_invoices, charge_codes, tax_codes (case-insensitive). The unix timestamp is required on every file and a filename must never be reused. Files that don't follow this convention are moved to failed with a result file explaining why.