{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"description":"The Karhoo fares API Gateway service","version":"v1.0","title":"Fares API 1.0","contact":{"email":"api@karhoo.com"},"x-hugo-values":{"tags":["api"],"categories":["fares"],"public":true}},"paths":{"/trip/{trip_id}":{"get":{"tags":["final-fare"],"summary":"Get final fare from trip id","description":"Due to the asynchronous nature of the way our partners arrive at final fares, we sometimes can't provide you with a 'final fare' immediately. This may be due to a number of reasons including the addition of extras, such as 'Waiting Time' that may be added to a journey after it has completed. Because of this, we provide the following endpoint, this will give you an expected time to a final fare, a fare status and ultimately a fare breakdown that includes fares, services, extras and expenses.\n\nThe overall total is the sum of each fare component's `net_price` and `tax_amount`.\n","operationId":"finalFareGet","parameters":[{"name":"trip_id","in":"path","required":true,"description":"An ID of a trip you want the final fare for.","schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}}],"responses":{"200":{"description":"Returned final fare.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalFare"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"}},"security":[{"Bearer":[]}]}},"/trip/{trip_id}/supplier":{"get":{"tags":["supplier-details"],"summary":"Get supplier details related to trip","description":"Use this endpoint to get supplier details to aid in receipts generation.\n","operationId":"supplierDetailsGet","parameters":[{"name":"trip_id","in":"path","required":true,"description":"An ID of a trip you want to receive the supplier details.","schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}}],"responses":{"200":{"description":"Returned supplier details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierDetails"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"}},"security":[{"Bearer":[]}]}},"/trip/{trip_id}/trip-document":{"get":{"tags":["documents"],"summary":"Get trip document PDF","description":"After receiving FinalFare webhook, this endpoint will provide latest issued trip document.\nThe document is sent as binary in its original language.\nIn the event of a 404 response, we recommend implementing a retry mechanism with a brief delay, such as waiting for 500 ms, before making another attempt to access the endpoint.\n","operationId":"getTripDocument","parameters":[{"name":"trip_id","in":"path","description":"Trip identifier.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trip document in PDF format.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"}},"security":[{"Bearer":[]}]}}},"servers":[{"url":"https://rest.sandbox.karhoo.com/v1/fares"}],"components":{"responses":{"400InvalidInput":{"description":"Bad Request. The request was invalid.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0002","description":"Error number"},"message":{"type":"string","example":"Invalid request payload","description":"Message of the error."},"details":{"type":"string","example":"Invalid request payload","description":"Details of the error."}}}}}},"401Unauthorized":{"description":"Unauthorized. The request requires user authentication (not logged in).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K6001","enum":["K6001","K0402"],"description":"Error number"},"message":{"type":"string","example":"Could not authenticate","description":"Message of the error."},"details":{"type":"string","example":"Could not authenticate","description":"Details of the error."}}}}}},"403Forbidden":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request. Please request access by emailing [API Support](api@karhoo.com?subject=API%20Access%20Request).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0005","description":"Error number."},"message":{"type":"string","example":"Missing required role for this request","description":"Message of the error."},"details":{"type":"string","example":"Missing required role for this request","description":"Details of the error."}}}}}},"404NotFound":{"description":"Not found.  Item not found, or following information is not available anymore.","content":{"*/*":{"schema":{"type":"object","description":"Details of the error that occurred whilst processing the request","required":["code","message"],"properties":{"code":{"type":"string","description":"Internally generated code for this error.","example":"K4003","enum":["K4012","K4003"]},"message":{"type":"string","example":"System-generated error message","description":"Message of the error."},"details":{"type":"string","description":"Details of the actual error.","example":"Item not found"}}}}}},"429RateLimit":{"description":"Error. Too Many Requests. Exceeded the rate limit for requests.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0006","description":"Error number."},"message":{"type":"string","example":"System-generated error message","description":"Message of the error."},"details":{"type":"string","example":"Rate limit exceeded","description":"Details of the error."}}}}}},"500InternalServerErr":{"description":"Internal server error. Something has gone wrong on the website's server, but the server could not be more specific on what the exact problem is.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0001","enum":["K0001","K0201","K0202","K0301"],"description":"Error number."},"message":{"type":"string","example":"System-generated error message","description":"Message of the error."},"details":{"type":"string","example":"General request error","description":"Details of the error."}}}}}},"502BadGateway":{"description":"Bad Gateway. The server, which was acting as a gateway or proxy, received an invalid response from the upstream server.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0000","description":"Error number"},"message":{"type":"string","example":"System-generated error message","description":"Message of the error."},"details":{"type":"string","example":"Bad Gateway error","description":"Details of the error."}}}}}}},"securitySchemes":{"Bearer":{"description":"For accessing the API a valid JWT token must be passed in all the queries in the 'Authorization' header.\nA valid JWT token is generated by the auth API.\nThe following syntax must be used in the 'Authorization' header:\n`Bearer: xxxxxx.yyyyyyy.zzzzzz`","type":"apiKey","name":"authorization","in":"header"}},"schemas":{"FinalFare":{"type":"object","required":["state"],"properties":{"state":{"type":"string","x-isnullable":false,"description":"The current state of the fare.\n* PENDING - the fare is not yet final and might be subject to change. It can not yet be charged.\n* FINAL - the fare is final and its value is now chargeable.\n* CANCELLED - the trip has been cancelled (with trip statuses being amongst CANCELLED_BY_DISPATCH, CANCELLED_BY_KARHOO or CANCELLED_BY_USER). The cancellation fee (fare) value is now chargeable.\n* FAILED - something went wrong with the trip.\n","example":"PENDING","enum":["PENDING","FINAL","CANCELLED","FAILED"]},"expected_final_time":{"type":"string","x-isnullable":true,"format":"date-time","description":"The expected RFC3339 timestamp in UTC for fare to turn into `FINAL` state.","example":"2016-04-16T16:06:05Z"},"expected_in":{"type":"integer","format":"int32","description":"The number of seconds until current `expected_final_time`.","example":"360"},"breakdown":{"$ref":"#/components/schemas/Breakdown"}}},"SupplierDetails":{"type":"object","required":["legal_name","registration_address"],"properties":{"legal_name":{"type":"string","description":"The legal business name of the supplier.","example":"Mars Taxi Ltd."},"vat_id":{"type":"string","description":"The VAT ID of the supplier.","example":"GB123456789"},"company_registration_number":{"type":"string","description":"The company registration number of the supplier.","example":"123456789"},"registration_address":{"$ref":"#/components/schemas/Address"},"billing_address":{"$ref":"#/components/schemas/Address"}}},"Breakdown":{"type":"object","description":"Detailed fare breakdown.\n","properties":{"base":{"$ref":"#/components/schemas/BaseComponent"},"commission":{"$ref":"#/components/schemas/Commission"},"extras":{"type":"array","description":"Any additional costs to the base service that might affect the ride's cost, eg. extra passenger, luggage, waiting time, bike, child seat etc.","items":{"$ref":"#/components/schemas/BreakdownItem"}},"expenses":{"type":"array","description":"Expenses the driver may incur while executing the ride. eg. parking, tolls, cleaning fee, congestion charge etc. No commissions or taxes (as they’re already included in the expense) will be charged on expenses.","items":{"$ref":"#/components/schemas/BreakdownItem"}},"total":{"type":"number","description":"Total is the total price of the trip. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence. The overall total is the sum of each fare component's `net_price` and `tax_amount`.","format":"uint","x-omitempty":false},"currency":{"type":"string","example":"EUR","description":"Currency of the fare. Format is ISO4217."}}},"BreakdownItem":{"description":"A single breakdown item. Could be either extra or expense. Its total price is equal to `net_amount` + `tax_amount`.","type":"object","properties":{"tax_percentage":{"type":"number","description":"The percentage of tax applied to the item.","x-omitempty":false},"discount_percentage":{"type":"number","description":"[Deprecated] It's going to be empty.\n\nA percent of a discount applied to the item.\n"},"commission_percentage":{"type":"number","description":"The percent of a commission applied to the item.","x-omitempty":false},"tax_amount":{"type":"number","format":"uint","description":"The amount of tax for the item. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.","x-omitempty":false},"list_price":{"type":"number","format":"uint","description":"[Deprecated] It's going to be equal to the `net_price`.\n\nThe list price of the item. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.\n","x-omitempty":false},"net_price":{"type":"number","format":"uint","description":"The net price of the item. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.","x-omitempty":false},"name":{"type":"string","description":"An English name of the item describing its meaning.\nWarning: it shouldn't be treated as an enumeration. Names can change in the future therefore it's not recommended to use it for any automatic mapping.\n"}}},"BaseComponent":{"description":"Base component of the fare. Its total price is equal to `net_amount` + `tax_amount`.","type":"object","properties":{"tax_percentage":{"type":"number","description":"The percentage of tax applied to the base component.","x-omitempty":false},"commission_percentage":{"type":"number","description":"The percent of a commission applied to the base component.","x-omitempty":false},"tax_amount":{"type":"number","format":"uint","description":"The amount of tax for the base component. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.","x-omitempty":false},"list_price":{"type":"number","format":"uint","description":"[Deprecated] It's going to be equal to the `net_price`.\n\nThe list price of the item. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.\n","x-omitempty":false},"net_price":{"type":"number","format":"uint","description":"The net price of the base component. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.","x-omitempty":false}}},"Commission":{"description":"Commission charged by the Marketplace for facilitating the transaction. Its total price is equal to `net_amount` + `tax_amount`.\n\nIts value depends on `base` and `extras` amounts as it's calculated as a percentage of net amounts of those. Commission percentage is\nconfigured per partner.\n","type":"object","properties":{"tax_percentage":{"type":"number","description":"The percentage of tax applied to the commission.","x-omitempty":false},"tax_amount":{"type":"number","format":"uint","description":"The amount of tax applied to the commission. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.","x-omitempty":false},"list_price":{"type":"number","format":"uint","description":"[Deprecated] It's going to be equal to the `net_price`.\n\nThe list price of the commission. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.\n","x-omitempty":false},"net_price":{"type":"number","format":"uint","description":"The net price of the commission. The unit is the cent or penny value of the currency e.g. EUR is in cents, GBP is in pence.","x-omitempty":false}}},"Address":{"type":"object","required":["country"],"properties":{"country":{"type":"string"},"state_or_province":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"street":{"type":"string"},"house_number_or_name":{"type":"string"}}},"Error":{"type":"object","description":"Details of the error that occurred whilst processing the request","required":["code","message"],"properties":{"code":{"type":"string","description":"Internally generated code for this error"},"message":{"type":"string","description":"Details of the actual error"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}}},"ErrorDetails":{"type":"object","description":"Additional information about the error (such as which field failed validation)","properties":{"message":{"type":"string","description":"Summary of additional information"},"detail":{"type":"string","description":"Actual detail of the error"}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}