Cabify Sales API

openapi: 3.2.0
info:
  contact:
    email: ridehailing.api@cabify.support
  license:
    name: Cabify Api support
    url: https://cabify.com
  title: Cabify Ride-Hailing Sales API
  version: '4.0'
  description: "Sales objects are created once a journey transitions into the terminated state and they are associated with the user who requested the journey (which not necessarily is the rider).\n            <br> <br>The transition to terminated happens automatically after 2 hours in production (10 minutes in sandbox environment).\n            <br> <br>You can request them per user (requester of the journey), the client (all of your sales), or journey (all Sales associated to a specific journey which in most cases is just one)."
servers:
- url: https://cabify.com
  description: Production
- url: https://cabify-sandbox.com
  description: Sandbox
security:
- access_token: []
tags:
- description: "Sales objects are created once a journey transitions into the terminated state and they are associated with the user who requested the journey (which not necessarily is the rider).\n            <br> <br>The transition to terminated happens automatically after 2 hours in production (10 minutes in sandbox environment).\n            <br> <br>You can request them per user (requester of the journey), the client (all of your sales), or journey (all Sales associated to a specific journey which in most cases is just one)."
  name: Sales
paths:
  /api/v4/journey/{journey_id}/sales:
    get:
      callbacks: {}
      description: Fetch the sales of the journey
      operationId: getJourneySales
      parameters:
      - description: Id of the journey
        example: 6f80363aa84fa61a58dc5720
        in: path
        name: journey_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Sale'
                type: array
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedRequest'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '500':
          content:
            application/text:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal server error
      summary: Get journey's sales
      tags:
      - Sales
  /api/v4/sales:
    get:
      callbacks: {}
      description: Get sales paginated
      operationId: getSales
      parameters:
      - description: Start date
        example: '2021-12-01'
        in: query
        name: from
        required: true
        schema:
          format: date
          pattern: '[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])'
          type: string
      - description: End date
        example: '2021-12-01'
        in: query
        name: to
        required: true
        schema:
          format: date
          pattern: '[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])'
          type: string
      - description: Currency of the sale
        example: EUR
        in: query
        name: currency
        required: true
        schema:
          default: EUR
          enum:
          - EUR
          - CLP
          - PEN
          - MXN
          - COP
          - USD
          - BRL
          - ARS
          type: string
      - description: Number of page to fetch
        example: 1
        in: query
        name: page
        required: true
        schema:
          default: 1
          type: integer
      - description: Amount of sales per page
        example: 20
        in: query
        name: per
        required: true
        schema:
          default: 20
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedRequest'
          description: Unauthorized
        '500':
          content:
            application/text:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal server error
      summary: Fetch client's sales paginated
      tags:
      - Sales
  /api/v4/user/{user_id}/sales:
    get:
      callbacks: {}
      description: Fetch user's sales paginated
      operationId: getUserSales
      parameters:
      - description: Id of the user
        example: 6f80363aa84fa61a58dc5720
        in: path
        name: user_id
        required: true
        schema:
          type: string
      - description: Start date
        example: '2021-12-01'
        in: query
        name: from
        required: true
        schema:
          format: date
          pattern: '[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])'
          type: string
      - description: End date
        example: '2021-12-01'
        in: query
        name: to
        required: true
        schema:
          format: date
          pattern: '[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])'
          type: string
      - description: Currency of the sale
        example: EUR
        in: query
        name: currency
        required: true
        schema:
          default: EUR
          enum:
          - EUR
          - CLP
          - PEN
          - MXN
          - COP
          - USD
          - BRL
          - ARS
          type: string
      - description: Number of page to fetch
        example: 1
        in: query
        name: page
        required: true
        schema:
          default: 1
          type: integer
      - description: Amount of sales per page
        example: 20
        in: query
        name: per
        required: true
        schema:
          default: 20
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedRequest'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '500':
          content:
            application/text:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal server error
      summary: Get user's sales paginated
      tags:
      - Sales
components:
  schemas:
    StopResponse:
      description: 'Stop of a journey. A journey needs to have at least 2 stops: the first one is considered the pickup point the last one the destination.'
      example:
        addr: Calle de la cruz
        city: Madrid
        contact:
          mobile_cc: '34'
          mobile_num: '123456789'
          name: Jhon Doe
          stop_action: pickup
        country: ES
        id: '123'
        loc:
        - 40.4169335
        - -3.7061872
        name: Work
        num: '1428'
        postal_code: '28002'
      properties:
        addr:
          description: If an address was provided when creating the journey this field will have its value.
          type: string
        city:
          description: City name where the address is located, e.g. Madrid.
          type: string
        contact:
          $ref: '#/components/schemas/Contact'
        contacts:
          default: []
          description: List of contacts for the stop, in case of multiple contacts.
          items:
            $ref: '#/components/schemas/Contact'
          type: array
        country:
          description: Country name where the address is located, e.g. España.
          type: string
        hit_at:
          description: DateTime when the driver arrived at the indicated point.
          format: date-time
          type: string
        id:
          description: Id of the stop.
          type: string
        instr:
          description: Set of instructions for the Driver.
          type: string
        loc:
          default: []
          description: The actual coordinates of the address. Required floats per location latitude and longitude.
          items:
            format: float
            type: number
          type: array
        meeting_point:
          $ref: '#/components/schemas/MeetingPoint'
        name:
          description: A short name for previously stored addresses. These can be viewed in places.
          type: string
        num:
          description: Street number.
          type: string
        postal_code:
          description: Postal code of the address.
          type: string
      required:
      - loc
      title: StopResponse
      type: object
    UnauthorizedRequest:
      description: The token used is invalid either because it is expired or because it is incorrect.
      example:
        error: Unauthorized
      properties:
        error:
          type: string
      title: UnauthorizedRequest
      type: object
    InternalServerError:
      description: indicates that an internal server error occurred
      example:
        error: Something went wrong
      properties:
        error:
          type: string
      title: InternalServerError
      type: object
    Expense:
      example:
        data:
        - code: ESP22AX002004
          concept:
            type: journey
            type_object:
              charge_code: P004
              country: ES
              description: 2022-02-17. Sol, Madrid. P004
              end_at: '2022-02-17T09:31:27.028Z'
              id: 41f11290-8fd4-11ec-879a-acde48001122
              region: madrid
              start_at: '2022-02-17T09:30:34.831Z'
          currency: EUR
          invoice_date: '2022-02-21'
          price_details:
            discount: 0
            tax_rate: 0
            tax_type: iva
            total: 0
        page: 1
        pages: 1
        per: 25
        total: 3
      properties:
        data:
          description: List of sales
          items:
            $ref: '#/components/schemas/Sale'
          type: array
        page:
          description: Number of page to fetch.
          type: integer
        pages:
          description: Total amount of pages.
          type: integer
        per:
          description: Amount of sales by page.
          type: integer
        total:
          description: Amount total of users obtained in all the pages.
          type: integer
      title: Expense
      type: object
    Contact:
      description: Contact details on each Stop. Include this object if you want the Driver to see additional Contact details on each Stop.
      example:
        mobile_cc: '34'
        mobile_num: '123456789'
        name: Jhon Doe
        stop_action: pickup
      properties:
        mobile_cc:
          description: Mobile Country Code of the Contact of the Stop passed when creating the Journey.
          type: string
        mobile_num:
          description: Mobile Number of the Contact of the Stop passed when creating the Journey.
          type: string
        name:
          description: Name of the Contact of the Stop passed when creating the Journey.
          type: string
        stop_action:
          description: 'Action to be performed on the Stop. Possible values: ''pickup'', ''dropoff''. Ignored when it is included in the `contact` field (`stop/contact`), i.e. only taken into account when specific for the contacts within `stop/contacts`.'
          enum:
          - pickup
          - dropoff
          type: string
      title: Contact
      type: object
    Concept:
      description: Prices of the Sale detailed.
      example:
        type: journey
        type_object:
          charge_code: P004
          country: ES
          description: 2022-02-17. Sol, Madrid. P004
          dropoff:
            addr: Calle de oviedo
            city: Madrid
            contact:
              mobile_cc: '34'
              mobile_num: '123456789'
              name: Jhon Doe
            country: ES
            loc:
            - 40.449074
            - -3.700908
            name: Home
            num: '1428'
          end_at: '2022-02-17T09:31:27.028Z'
          id: 41f11290-8fd4-11ec-879a-acde48001122
          pickup:
            addr: Calle de la cruz
            city: Madrid
            contact:
              mobile_cc: '34'
              mobile_num: '123456789'
              name: Jhon Doe
            country: ES
            loc:
            - 40.4169335
            - -3.7061872
            name: Work
            num: '1428'
          region: madrid
          start_at: '2022-02-17T09:30:34.831Z'
      properties:
        type:
          description: Type of the element being sold.
          type: string
        type_object:
          $ref: '#/components/schemas/TypeObject'
      title: Concept
      type: object
    TypeObjectRectification:
      properties:
        description:
          description: Description usually indicating the reason of the Rectification.
          type: string
        rectified_sale_id:
          description: ID of the Sale which was rectified.
          type: string
      title: TypeObjectRectification
      type: object
    TypeObject:
      anyOf:
      - $ref: '#/components/schemas/TypeObjectSale'
      - $ref: '#/components/schemas/TypeObjectRectification'
      title: TypeObject
      type: object
    Sale:
      example:
        code: ESP22AX002004
        concept:
          type: journey
          type_object:
            charge_code: P004
            country: ES
            description: 2022-02-17. Sol, Madrid. P004
            dropoff:
              addr: Calle de oviedo
              city: Madrid
              contact:
                mobile_cc: '34'
                mobile_num: '123456789'
                name: Jhon Doe
              country: ES
              loc:
              - 40.449074
              - -3.700908
              name: Home
              num: '1428'
            end_at: '2022-02-17T09:31:27.028Z'
            id: 41f11290-8fd4-11ec-879a-acde48001122
            pickup:
              addr: Calle de la cruz
              city: Madrid
              contact:
                mobile_cc: '34'
                mobile_num: '123456789'
                name: Jhon Doe
              country: ES
              loc:
              - 40.4169335
              - -3.7061872
              name: Work
              num: '1428'
            region: madrid
            start_at: '2022-02-17T09:30:34.831Z'
        currency: EUR
        invoice_date: '2022-02-21'
        price_details:
          discount: 0
          tax_rate: 0
          tax_type: iva
          total: 0
      properties:
        code:
          description: Code of the Sale.
          type: string
        concept:
          $ref: '#/components/schemas/Concept'
        currency:
          description: Currency of the Sale.
          type: string
        invoice_date:
          description: Date of the Invoice of the Sale.
          format: date
          type: string
        price_details:
          $ref: '#/components/schemas/PriceDetail'
      title: Sale
      type: object
    PriceDetail:
      example:
        discount: 0
        tax_rate: 0
        tax_type: iva
        total: 0
      properties:
        discount:
          default: 0
          description: Total discount in cents with taxes.
          type: integer
        tax_rate:
          default: 0
          description: Tax Rate.
          type: integer
        tax_type:
          description: Tax Type. Usually is 'iva_av'.
          type: string
        total:
          default: 0
          description: Total amount in cents with taxes.
          type: integer
      title: PriceDetail
      type: object
    BadRequest:
      description: Indicates that the server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing).
      example:
        error: Bad Request error message
      properties:
        message:
          type: string
      title: BadRequest
      type: object
    MeetingPoint:
      description: A specific meeting point within a hub location (e.g. a terminal at an airport). Obtained from the hub data returned in the estimates response.
      example:
        id: mp_001
        loc:
        - 40.4722
        - -3.5608
        name: Terminal 1 - Puerta de llegadas
      properties:
        id:
          description: Unique identifier of the meeting point.
          type: string
        loc:
          description: Coordinates of the meeting point as [latitude, longitude].
          items:
            format: float
            type: number
          maxItems: 2
          minItems: 2
          type: array
        name:
          description: Display name of the meeting point.
          type: string
      required:
      - id
      - loc
      - name
      title: MeetingPoint
      type: object
    NotFound:
      description: The server did not find a current representation for the target resource
      example:
        error: user with provided ID does not exist
      properties:
        message:
          type: string
      title: NotFound
      type: object
    TypeObjectSale:
      description: Entity description in a Sale.
      example:
        charge_code: P004
        country: ES
        description: 2022-02-17. Sol, Madrid. P004
        dropoff:
          addr: Calle de oviedo
          city: Madrid
          contact:
            mobile_cc: '34'
            mobile_num: '123456789'
            name: Jhon Doe
          country: ES
          loc:
          - 40.449074
          - -3.700908
          name: Home
          num: '1428'
        end_at: '2022-02-17T09:31:27.028Z'
        id: 41f11290-8fd4-11ec-879a-acde48001122
        pickup:
          addr: Calle de la cruz
          city: Madrid
          contact:
            mobile_cc: '34'
            mobile_num: '123456789'
            name: Jhon Doe
          country: ES
          loc:
          - 40.4169335
          - -3.7061872
          name: Work
          num: '1428'
        region: madrid
        start_at: '2022-02-17T09:30:34.831Z'
      properties:
        charge_code:
          description: Charge code of the Journey of the Sale.
          type: string
        country:
          description: Country of the Journey of the Sale.
          type: string
        description:
          description: The Description includes the detail of the Journey associated to the Sale.
          type: string
        dropoff:
          $ref: '#/components/schemas/StopResponse'
        end_at:
          description: DateTime when the Journey ended.
          format: date-time
          type: string
        id:
          description: ID of the Journey of the Sale.
          type: string
        pickup:
          $ref: '#/components/schemas/StopResponse'
        region:
          description: Region where the Journey happened.
          type: string
        start_at:
          description: DateTime when the Journey started.
          format: date-time
          type: string
      title: TypeObjectSale
      type: object
  securitySchemes:
    access_token:
      scheme: bearer
      type: http