Malga Flows API

openapi: 3.2.0
info:
  version: '0.5'
  title: Documentação Malga Flows API
  description: '# Authentication


    Os serviços de API da Malga são protegidos através de chaves de acesso.'
servers:
- url: https://api.malga.io
  description: Production
security:
- X-Client-ID: []
  X-Api-Key: []
tags:
- name: Flows
  description: 'Através da API de `flows` é possível recuperar detalhes de um Fluxo ou listar todas os Fluxos cadastrados em determinado `clientId`.


    Os fluxos inteligentes são um recurso disponibilizado pela Malga para gestão dos pagamentos, possibilitando a configuração e a inserção de regras e condicionais personalizados para processamento das cobranças. Para mais informações, consulte a documentação link.'
paths:
  /v1/flows:
    get:
      summary: Recuperar todos os fluxos paginado
      operationId: getAllFlows
      parameters:
      - in: query
        name: page
        schema:
          type: number
        required: false
        description: Número da página
      - in: query
        name: limit
        schema:
          type: number
        required: false
        description: Quantidade de itens por página
      - in: query
        name: merchantId
        schema:
          type: string
        required: false
        description: Usado para filtrar os fluxos por merchantId
      - in: query
        name: paymentMethod
        schema:
          type: string
        required: false
        description: Usado para filtrar os fluxos por método de pagamento
      responses:
        '200':
          description: Response de flow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllFlowResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Flows
  /v1/flows/{id}:
    get:
      operationId: getFlowById
      summary: Consultar um fluxo pelo id
      parameters:
      - name: id
        required: true
        description: Flow id
        in: path
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Response de flow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Flows
components:
  schemas:
    FlowResponse:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do fluxo
        paymentMethod:
          type: string
          description: Método de pagamento a qual aquele fluxo é relacionado
        clientId:
          type: string
          description: Identificador do cliente dono do fluxo
        merchants:
          type: array
          items:
            type: object
            properties:
              merchantId:
                type: string
                description: Identificador do merchant relacionado ao fluxo
        parentId:
          type: string
          description: Identificador do fluxo que originou o novo
        restoredFrom:
          type: string
          description: Identificador do fluxo do qual este foi restaurado
        createdAt:
          type: string
          description: Data e hora em que o fluxo foi criado (UTC)
        flow:
          type: object
          description: Dados do fluxo que será cadastrado
      example:
        id: b4ced0dd-2136-4bce-a231-364e93554073
        merchants:
        - merchantId: z1babb21-6a4c-987d-89db-11d3af737ee1
        paymentMethod: credit
        clientId: f1babb21-6a4c-323d-12db-69d3af407ee1
        parentId: g1babb21-6a4c-987d-89db-11d3af737ee1
        createdAt: '2023-03-22T20:45:06.020Z'
        flow:
          version: 0.0.0
          root:
          - rule: provider
            id: z1babb21-6a4c-987d-89db-11d3af737ee1
        restoredFrom: df601922-e024-6394-8f12-af21ec4218b1
    ErrorResponse:
      properties:
        error:
          type: object
          allOf:
          - $ref: '#/components/schemas/ErrorItem'
    AllFlowResponse:
      type: object
      properties:
        items:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/FlowResponse'
        meta:
          allOf:
          - $ref: '#/components/schemas/MetaPagination'
      example:
        items:
        - id: b4ced0dd-2136-4bce-a231-364e93554073
          paymentMethod: credit
          clientId: f1babb21-6a4c-323d-12db-69d3af407ee1
          merchants:
          - merchantId: z1babb21-6a4c-987d-89db-11d3af737ee1
          parentId: g1babb21-6a4c-987d-89db-11d3af737ee1
          createdAt: '2023-03-22T20:45:06.020Z'
          flow:
            version: 0.0.0
            root:
            - rule: provider
              id: z1babb21-6a4c-987d-89db-11d3af737ee1
          restoredFrom: df601922-e024-6394-8f12-af21ec4218b1
        meta:
          itemCount: 10
          totalItems: 20
          itemsPerPage: 10
          totalPages: 5
          currentPage: 2
    ErrorItem:
      properties:
        type:
          type: string
          enum:
          - api_error
          - bad_request
          - invalid_request_error
          - card_declined
        code:
          type: integer
          description: Código HTTP do erro (por exemplo, `422` em erros de regra de negócio).
        declinedCode:
          type: string
          description: Código de retorno da transação em caso de falha na autorização
        key:
          type: string
          description: 'Chave estável que identifica o erro de negócio (ex.: `bank_identifier_required`). Útil para tratar o erro programaticamente, independente da mensagem traduzida.'
        businessCode:
          type: string
          description: 'Chave estável de regra de negócio retornada em `422`. Permite tratar o erro programaticamente independente da mensagem traduzida. Exemplos em sessões: `pix_boleto_multiple_payments_not_allowed`, `pix_boleto_one_to_one_reactivation_blocked`, `platform_fee_exceeds_link_amount`, `session_disabled`, `multiple_payments_limit_reached`.

            '
        message:
          type: string
          description: Descrição breve do erro
        details:
          type: array
          description: Lista contendo objetos que detalham o erro de validação
    MetaPagination:
      properties:
        itemCount:
          type: integer
          description: Quantidade de itens na página
        totalItems:
          type: integer
          description: Quantidade total de itens na consulta (esse valor é mantido em cache por 5 minutos para melhorar a performance da API)
        itemsPerPage:
          type: integer
          description: Quantidade de itens por página
        totalPages:
          type: integer
          description: Quantidade total de páginas
        currentPage:
          type: integer
          description: Página atual
  securitySchemes:
    X-Client-ID:
      type: apiKey
      in: header
      name: X-Client-Id
    X-Api-Key:
      type: apiKey
      in: header
      name: X-Api-Key
x-tagGroups:
- name: API Key
  tags:
  - Client-token
- name: Cartões
  tags:
  - Tokens
  - Cards
- name: Pagamentos
  tags:
  - Customers
  - Charges
  - Sessions
  - Sellers
  - Vendors
  - Split
  - 3DSecure2
  - Settings
- name: Notificação e eventos
  tags:
  - Webhooks
- name: Provedores
  tags:
  - Merchants
  - Providers
- name: Gestão de pagamentos
  tags:
  - Flows
- name: Exportar Dados
  tags:
  - Reports
- name: Apêndice
  tags:
  - Tabelas de tipos