swagger.yaml

openapi: "3.0.1"
tags:
  - name: "payments"
    description: "Payments operations"
info:
  title: "Groceries API"
  description: "Definition of Groceries APIs integratios between Lolamarket and Cabify"
  version: "0.0.1"

servers:
  - url: "https://integrations.cabify.com"
    description: "Production"
  - url: "https://integrations.rider-groceries-01.cabify-testing.com"
    description: "Testing"

paths:
  /lola/api/v1/payments/hook:
    post:
      tags:
        - "payments"
      summary: "Finish an Order and dispatch payments events"
      description: "Finish an <b>Order</b> and dispatch payments events like billing or cancelling an authorization.<br><br><b>Events:</b><ul><li><b>groceries.order_delivered:</b> Dispatch a terminating event to Cabify and should be triggered when an order is marked as finished and Cabify needs to charge a previous authorized payment. <br>**This event will require the whole billing information in the `order` object `total_amount`, `currency` and `items`**</li><br><li><b>groceries.order_cancelled:</b> Should be triggered when an Order is cancelled and the payment authorization needs to be totally refund to the user.<br>**Only the `order.id` is mandatory in this case**</li></ul>"
      operationId: "payments-hook"
      security:
        - ApiKeyAuth: [ ]
      requestBody:
        $ref: "#/components/requestBodies/paymentsHookMessage"
      responses:
        "202":
          description: "message accepted and published"
        "400":
          description: "bad request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error_message"
        "401":
          description: "unauthorized"

  /lola/api/v1/order/hook:
    post:
      tags:
        - "order"
      summary: "Dispatch order events"
      description: "Dispatch changes of an <b>Order</b> like state changes.<br><br><b>Events:</b><ul><li><b>groceries.order_state_changed:</b> Dispatch an event to Cabify notifying about states changes of an Order<br>**This event will require the `order` object with the new `state` field**</li></ul>"
      operationId: "order-hook"
      security:
        - ApiKeyAuth: [ ]
      requestBody:
        $ref: "#/components/requestBodies/orderHookMessage"
      responses:
        "202":
          description: "message accepted and published"
        "400":
          description: "bad request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error_message"
        "401":
          description: "unauthorized"

  /third-party/payments/hook:
    post:
      tags:
        - "payments"
      summary: "Lola WebHook that will listen payment and cancellation result"
      description: "Since all payments operations are async all payment results will be published into this endpoint."
      operationId: "result-payments-hook"
      security:
        - ApiKeyAuth: [ ]
      requestBody:
        $ref: "#/components/requestBodies/paymentsHookResult"
      responses:
        "202":
          description: "message accepted and published"
        "400":
          description: "bad request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error_message"
        "401":
          description: "unauthorized"

components:
  requestBodies:
    paymentsHookMessage:
      description: "Request body for a Payment Operation"
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/payment_operation"

    paymentsHookResult:
      description: "Request body for a Payment Operation Result"
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/payment_operation_result"

    orderHookMessage:
      description: "Request body for a Order Operation"
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/order_operation"

  schemas:
    payment_operation:
      type: "object"
      required:
        - caller
        - event
        - data
      properties:
        caller:
          type: "string"
          description: "Caller's ID"
          example: "26345b2f-3125-11eb-87d8-801234232f4e"
        event:
          type: "string"
          description: "Define the type of Payment Event that needs to be processed"
          enum: [
              "groceries.order_delivered",
              "groceries.order_cancelled"
          ]
        data:
          type: "object"
          required:
            - order
          properties:
            order:
              $ref: "#/components/schemas/order"

    order_operation:
      type: "object"
      required:
        - caller
        - event
        - data
      properties:
        caller:
          type: "string"
          description: "Caller's ID"
          example: "26345b2f-3125-11eb-87d8-801234232f4e"
        event:
          type: "string"
          description: "Define the type of Order Event that needs to be processed"
          enum: [
              "groceries.order_state_changed"
          ]
        data:
          type: "object"
          required:
            - order
          properties:
            order:
              $ref: "#/components/schemas/order"

    payment_operation_result:
      type: "object"
      required:
        - result
        - data
      properties:
        event:
          type: "string"
          description: "Define the type of Payment Event that needs to be processed"
          enum: [
              "groceries.order_delivered",
              "groceries.order_cancelled"
          ]
        result:
          type: "string"
          description: "An Enum describing the result of the operation"
          enum:
            - "success"
            - "error"
        message:
          type: "string"
          description: "Message describing the error if applicable"
        data:
          type: "object"
          properties:
            order:
              $ref: "#/components/schemas/order"

    order:
      type: "object"
      required:
        - id
      properties:
        id:
          type: "string"
          description: "Order ID"
          example: "XXXXX-XXXXX-XXXXX-XXXXX"
        currency:
          type: "string"
          description: "Order's currency, three letters ISO"
          example: "eur"
        total_amount:
          type: "integer"
          description: "Order's total amount, decimal value multipled by 100"
          example: "10000"
        state:
          type: "string"
          description: "Current order state"
          example: "delivered"
          enum:
            - "confirmed"
            - "shopping"
            - "delivering"
            - "delivered"
        items:
          type: "array"
          items:
            $ref: "#/components/schemas/order_item"

    order_item:
      type: "object"
      required:
        - quantity
        - price
        - total_price
        - discount
        - tax_rate
        - description
      properties:
        quantity:
          type: "integer"
          description: "Quantity of the product"
          example: "5"
        price:
          type: "integer"
          description: "Unit price, decimal multipled by 100"
          example: "100"
        total_price:
          type: "integer"
          description: "Total price (quantity * price) - (quantity * discount), decimal multipled by 100"
          example: "500"
        discount:
          type: "integer"
          description: "Unit discount value, decimal multipled by 100"
        tax_rate:
          type: "number"
          format: "float"
          description: "Percentage of tax rate included in the price"
          example: 0.0
        description:
          type: "string"
          description: "Name of the product"

    error_message:
      type: "object"
      properties:
        error:
          type: "string"
          description: "Error description"

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"