bsp

Documentation

Overview

Package bsp is the settlement side of the ticket: the Airline Accounting/Sales data file -- the HOT -- that a Billing and Settlement Plan hands each airline for the documents agents sold on its behalf, and that the airline's revenue accounting reconciles against its own sales.

This package is specified. IATA publishes the BSP Data Interchange Specifications Handbook (DISH, revision 23) free of charge, and the records here follow its chapter 6 layouts column by column: the file, cycle and office headers, the transaction header, the document identification, amounts and commission records, the itinerary segments, the passenger and form-of-payment records, and the office, cycle and file totals. Amounts are signed by the handbook's over-punch convention and add up the way its section 6.7 says they must. What the handbook leaves to bilateral agreement -- net reporting, card data, taxes on commission -- is left out; a record type this package does not lay out is kept verbatim as a fragment when read.

Index

• Constants
• func CheckDigit(number string) (int, error)
• type Cycle
• type File
  • func Parse(r io.Reader) (*File, error)
  • func (f *File) Write(w io.Writer) error
• type Office
  • func (o Office) OfficeTotals() Totals
• type Payment
• type RET
  • func ParseRET(r io.Reader) (*RET, error)
  • func (f *RET) Write(w io.Writer) error
• type Segment
• type Tax
• type Totals
• type Transaction
  • func (t *Transaction) Compute() Totals

Constants

const (
	TransSale   = "TKTT" // electronic ticketing sale, automated
	TransRefund = "RFND"
	TransCancel = "CANX"
	TransEMDA   = "EMDA"
	TransEMDS   = "EMDS"
	TransADM    = "ADMA"
	TransACM    = "ACMA"
)

Transaction codes (TRNC), from the handbook's glossary.

const (
	PaymentCash     = "CA"
	PaymentCard     = "CC"
	PaymentExchange = "EX"
)

Form of payment types (FPTP). There is always one CA record, even when its amounts are zero; an exchange carries the exchanged document's value as its own form of payment, EX.

const (
	MemoFareDifference = "FARE" // the fare collected fell short of the fare due
	MemoCommission     = "COMM" // commission taken beyond the agreed rate
	MemoTaxDifference  = "TAX"  // taxes collected fell short
	MemoNotReported    = "NREP" // a document issued and never reported
	MemoRefundRecall   = "RFND" // a refund made on a document already refunded
	MemoCommissionOwed = "COMR" // commission due to the agent and not paid (credit)
	MemoOvercollection = "OVER" // more collected than due (credit)
	MemoCourtesyCredit = "CRED" // a credit agreed between the parties
	MemoNoReasonGiven  = ""
)

Memo reason codes (RMIC) this package names; the plans' own lists are longer and agreed locally.

const RETRecordLen = 255

RETRecordLen is the fixed length of an agent reporting record.

const RecordLen = 136

RecordLen is the fixed length of a HOT record.

Functions

func CheckDigit

func CheckDigit(number string) (int, error)

CheckDigit is the unweighted modulus-7 check digit of a document number: the number modulo seven.

Types

type Cycle

type Cycle struct {
	// ProcessingWeek is MMW, the month and week within it (PDAI); Number
	// the processing cycle (PCYC), 1 by default.
	ProcessingWeek string
	Number         int
	// Ending is the billing analysis ending date (BAED); ReportingEnd the
	// last date of issue the file covers (HRED).
	Ending, ReportingEnd time.Time
	// Final marks the final run of the period (DYRI F); otherwise D.
	Final bool
}

Cycle is the billing analysis (cycle) header: which period, which run.

type File

type File struct {
	// BSP is the plan's city code (BSPI); Airline the ticketing airline's
	// three-digit code (TACN); Country the ISO country of the agents.
	BSP, Airline, Country string
	// Test marks a test file; production files say PROD.
	Test bool
	// Processed is when the plan produced the file; Sequence its file
	// sequence number (FSQN), which increments even for an empty file.
	Processed time.Time
	Sequence  int
	// Cycle describes the billing period.
	Cycle Cycle
	// Offices are the reporting agents, each with its transactions.
	Offices []Office
	// Fragments holds records of types this package does not lay out,
	// verbatim, in the order read.
	Fragments []string
}

File is one HOT: a file header, one billing cycle, and the reporting offices with their transactions and totals.

func Parse

func Parse(r io.Reader) (*File, error)

Parse reads a HOT. It rebuilds the offices and their transactions from the records, checks each transaction's record count against its header and each record's sequence against its position, and keeps records of types it does not lay out as fragments. Amounts come back signed.

func (*File) Write

func (f *File) Write(w io.Writer) error

Write renders the file. Records are 136 characters, newline-terminated, numbered from 1 in the order written; each transaction is numbered from 1 within the file and counts its own records (TREC). Office subtotals are per transaction code; office, cycle and file totals per currency.

type Office

type Office struct {
	// Agent is the eight-digit agent numeric code (seven digits and a
	// modulus-7 check digit).
	Agent string
	// RemittanceEnd is the last day of the agent's remittance period.
	RemittanceEnd time.Time
	// Currency is the currency type (CUTP): ISO code plus decimals, "USD2".
	Currency     string
	Transactions []Transaction
}

Office is one reporting agent: its IATA numeric code, its remittance period and currency, and what it sold.

func (Office) OfficeTotals

func (o Office) OfficeTotals() Totals

OfficeTotals sums an office's transactions the way BOT94 does, without changing them.

type Payment

type Payment struct {
	Type   string // CA, CC...
	Amount int64
	// Account is the card number for a card payment, masked as the plan
	// masks it; Expiry MMYY; Approval the authorisation code.
	Account, Expiry, Approval string
	// Remittance is the amount due to the airline on the cash record: the
	// cash paid less the effective commission (and tax on commission).
	// Set by Compute; zero on every record but the cash one.
	Remittance int64
}

Payment is one form of payment (BKP84).

type RET

type RET struct {
	// PeriodEnd is the reporting period ending date (SPED); System the
	// reporting system identifier (RPSI); Country the ISO country code.
	PeriodEnd time.Time
	System    string
	Country   string
	Test      bool
	Processed time.Time
	// Sequence is the file type sequence number within the period (FTSN).
	Sequence     int
	Transactions []Transaction
	// Fragments holds records of types this package does not lay out.
	Fragments []string
}

RET is one agent reporting file.

func ParseRET

func ParseRET(r io.Reader) (*RET, error)

ParseRET reads an agent reporting file into transactions, grouped by transaction number. Records of types this package does not lay out are kept as fragments; amounts are read as the unsigned values the file carries.

func (*RET) Write

func (f *RET) Write(w io.Writer) error

Write renders the file with transactions numbered from 1.

type Segment

type Segment struct {
	Coupon int
	// Stopover is X when no stopover is permitted at the destination, O
	// when one is.
	Stopover string
	// NotValidBefore and NotValidAfter are DDMMM, when stated.
	NotValidBefore, NotValidAfter string
	Origin, Destination           string
	Carrier                       string
	// Cabin is the sold cabin code; Flight the flight number; Class the
	// booking designator; Departs the date and, when known, local time.
	Cabin, Flight, Class string
	Departs              time.Time
	DepartsHasTime       bool
	// Status is the booking status, OK when confirmed.
	Status string
	// Baggage is the allowance, e.g. 1PC or 23K.
	Baggage   string
	FareBasis string
	Equipment string
}

Segment is one flight coupon of the itinerary (BKI63).

type Tax

type Tax struct {
	Code   string // e.g. GB, YQ, XF
	Amount int64
}

Tax is one tax, fee or charge on a document.

type Totals

type Totals struct {
	Gross, Remittance, Commission, Taxes, TaxOnCommission int64
}

Totals are the office, cycle and file sums the handbook defines: the document amounts (GROS), the remittances (TREM), the effective commission (TCOM), the taxes (TTMF) and the tax on commission (TTCA).

type Transaction

type Transaction struct {
	Code string // TRNC
	// Issued is the date (and time, when known) of issue.
	Issued time.Time
	// Document is the ticket number: three-digit airline code and ten-digit
	// serial, fourteen characters with the form code; CheckDigit its
	// modulus-7 check digit. Coupons is the coupon use indicator, one
	// character per coupon position: F for a flight coupon, blank for
	// none.
	Document   string
	CheckDigit int
	Coupons    string
	// Agent is the issuing agent's numeric code; ReportingSystem the GDS or
	// system that reported it (RPSI).
	Agent           string
	ReportingSystem string
	// Locator is the PNR reference with the controlling system, "ABC123/1G".
	Locator string
	// Origin and Destination are the true origin and destination cities.
	Origin, Destination string
	// Currency is the currency type (CUTP) the amounts are in.
	Currency string
	// Fare is the commissionable amount (COBL): the fare paid, in minor
	// units. Taxes are the taxes, fees and charges, up to three per
	// amounts record. Total is the document amount (TDAM), fare plus
	// payable taxes.
	Fare  int64
	Taxes []Tax
	Total int64
	// FareText and TotalText are the document's own fare and total boxes
	// (FARE, TOTL): "USD 123.00" as printed, with the currency code.
	FareText, TotalText string
	// Commission is the standard commission: rate in hundredths of a
	// percent (10.5% is 1050) and amount in minor units.
	CommissionRate   int
	CommissionAmount int64
	// Segments are the flight coupons, up to four.
	Segments []Segment
	// Passenger is SURNAME/GIVEN TITLE as the document carries it; Type
	// the passenger type code.
	Passenger     string
	PassengerType string
	// Payments are the forms of payment; the cash record is always present
	// and carries the remittance.
	Payments []Payment
	// TicketingMode is "/" for a document generated by the carrier or a
	// CRS, "X" for one generated by an agent's own system from an
	// interface record.
	TicketingMode string
	// ServicingSystem is the airline or system provider code that made the
	// reservation (SASI), three digits and a check digit.
	ServicingSystem string
	// OriginalDocument, when set, marks an exchange: the document this one
	// was issued against, with where and when and by whom it was issued
	// (BKS46, qualifying issue information).
	OriginalDocument string
	OriginalIssued   time.Time
	OriginalLocation string
	OriginalAgent    string
	// RelatedDocument, when set, is the document a memo or refund relates
	// to (BKS45), with the reason the memo was raised (RMIC) and the
	// coupon it concerns. A memo's own Document is the memo number.
	RelatedDocument string
	RelatedIssued   time.Time
	RelatedCoupon   int
	MemoReason      string
}

Transaction is one accountable sale, refund or memo: a document with its amounts, commission, itinerary, passenger and payments.

func (*Transaction) Compute

func (t *Transaction) Compute() Totals

Compute fills in what the handbook derives: the document amount from fare and taxes (6.7.1c), the remittance on the cash payment from cash less commission (6.7.1d), and a cash payment record when there is none. It returns the transaction's totals for the office subtotals.