openapi: 3.0.0
info:
  title: Monato's API
  version: 2.0.0
paths:
  /v2/account:
    get:
      summary: Returns account details
      operationId: getAccount
      description: Endpoint to get basic data from your account with Monato.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Successfuly returns account's information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
  /v2/utilities:
    get:
      summary: Retrieve utility companies
      operationId: retrieveUtilitiesCompanies
      description: Endpoint to retrieve a list of utility companies available.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Successfully returns a list of utility companies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UtilitiesResponse'
  /v2/utilities/{companyId}:
    get:
      summary: Retrieve the details for an utility company
      operationId: retrievUtilityCompany
      description: Endpoint to retrieve company details based on the provided company ID.
      security:
        - BearerAuth: []
      parameters:
        - name: companyId
          in: path
          required: true
          description: The ID of the utility company
          schema:
            type: string
            example: '1234567'
      responses:
        '200':
          description: Successfully returns account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
  /v2/utilities/{companyId}/{reference}:
    get:
      summary: Retrieve the current balance for a reference
      operationId: retrieveBillsBalance
      description: >-
        Endpoint to retrieve the current balance for a companies refence – also
        knowns as account number, or service number – based on company ID and
        reference.
      security:
        - BearerAuth: []
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
          example: '123456789012'
        - name: reference
          in: path
          required: true
          schema:
            type: string
          example: '019701209060882503020000042191'
      responses:
        '200':
          description: Successfully returns private account information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
  /v2/payments:
    post:
      summary: Create a payment
      operationId: createPayment
      description: Endpoint to create a Payment.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
            example:
              companyId: '123456'
              reference: '055810100345'
              amount: '100.00'
              currency: MXN
      responses:
        '200':
          description: Successfully created payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
              example:
                id: '123456789000'
                customerServiceNumberId: '1234567890'
                companyId: '00012345679'
                reference: '055810100345'
                amount: '100.0'
                currency: MXN
                status: COMPLETED
                authNumber: '123456789012'
                ticketMessage: Lorem ipsum
                metadata: {}
                customerServiceNumber: '123456789012'
                createdAt: '2024-04-10T19:48:43.222Z'
  /customer-bills/{billId}:
    get:
      summary: Get customer bill
      operationId: retrieveCustomerBill
      description: Returns the Customer Bill content.
      security:
        - BearerAuth: []
      parameters:
        - name: billId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBill'
  /customer-bills/{billId}/track:
    put:
      summary: Set customer bill  as tracked
      operationId: trackCustomerBill
      description: Update the Customer Bill to be tracked.
      security:
        - BearerAuth: []
      parameters:
        - name: billId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tracked:
                  type: boolean
                  example: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBill'
  /customer-bills/{billId}/untrack:
    put:
      summary: Set customer bill as untracked
      operationId: untrackCustomerBill
      description: Update the Customer Bill to stop being tracked.
      security:
        - BearerAuth: []
      parameters:
        - name: billId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tracked:
                  type: boolean
                  example: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBill'
  /api/v2/webhooks:
    post:
      summary: Create a webhook configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
            example:
              url: https://your-api.com/webhooks
      responses:
        '201':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              example:
                id: 1
                url: https://your-api.com/webhooks
                secret: >-
                  6e5a9465cb8e117cfe63473ba7310ec96898db7c893a967b35cf58d669e47337
components:
  schemas:
    CreatePaymentRequest:
      type: object
      properties:
        companyId:
          type: string
          example: '123456'
        reference:
          type: string
          example: '055810100345'
        amount:
          type: string
          example: '100.00'
        currency:
          type: string
          example: MXN
    Account:
      type: object
      properties:
        id:
          type: string
          example: '000123456789'
        name:
          type: string
          example: Client
        balance:
          type: string
          example: 999,999.99
        currency:
          type: string
          example: MXN
    UtilitiesResponse:
      type: object
      properties:
        companies:
          type: array
          items:
            $ref: '#/components/schemas/Company'
    Company:
      type: object
      properties:
        id:
          type: string
          example: '123456789012'
        code:
          type: string
          example: '123456789'
        name:
          type: string
          example: CFE
        country:
          type: string
          example: MX
        currency:
          type: string
          example: MXN
        tags:
          type: array
          items:
            type: string
          example:
            - Electricity
        allowConsult:
          type: boolean
          example: true
        logo:
          type: string
          example: https://logos.monato.com/cfe.png
    Balance:
      type: object
      properties:
        id:
          type: string
          example: '1234567890123456789'
        companyName:
          type: string
          example: CFE
        companyId:
          type: string
          example: '123456789012'
        reference:
          type: string
          example: '019701209060882503020000042191'
        accountNumber:
          type: string
          example: '970120906088'
        amount:
          type: string
          example: '36.67'
        currency:
          type: string
          example: MXN
        due_date:
          type: string
          format: date
          example: '2024-04-20'
        metadata:
          type: object
          example: {}
        consultedAt:
          type: string
          format: date-time
          example: '2024-04-10T19:21:13.387Z'
    Payment:
      type: object
      properties:
        id:
          type: string
          example: '123456789000'
        customerBillId:
          type: string
          example: '123456789012'
        companyId:
          type: string
          example: '00012345679'
        reference:
          type: string
          example: '055810100345'
        amount:
          type: string
          example: '100.0'
        currency:
          type: string
          example: MXN
        status:
          type: string
          example: COMPLETED
        authNumber:
          type: string
          example: '123456789012'
        ticketMessage:
          type: string
          example: >-
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris
            pellentesque venenatis odio, ut varius lacus. Fusce vel ullamcorper
            turpis. Suspendisse eu turpis a leo porta porta
        metadata:
          type: object
          example: {}
        createdAt:
          type: string
          format: date-time
          example: '2024-04-10T19:48:43.222Z'
    CustomerBill:
      type: object
      properties:
        id:
          type: string
          example: '123456789012'
        companyId:
          type: string
          example: '123456'
        companyName:
          type: string
          example: CFE
        accountNumber:
          type: string
          example: '123'
        balance:
          type: string
          example: '99.99'
        currency:
          type: string
          example: MXN
        dueDate:
          type: string
          format: date
          example: '2024-04-20'
        tracked:
          type: boolean
          example: false
    WebhookCreateRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Endpoint to which the webhook will be sent.
          example: https://your-api.com/webhooks
    WebhookResponse:
      type: object
      required:
        - id
        - url
        - secret
      properties:
        id:
          type: integer
          format: int64
          description: Identifier of the webhook configuration.
          example: 1
        url:
          type: string
          format: uri
          description: URL registered for the webhook.
          example: https://your-api.com/webhooks
        secret:
          type: string
          format: hex
          description: Secret key used for signing (e.g., in the X-Signature header).
          example: 6e5a9465cb8e117cfe63473ba7310ec96898db7c893a967b35cf58d669e47337
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Access Token
