openapi: 3.0.1
info:
  description: >-
    A API Evoluservices Orders facilita a criação de links de pagamento para
    clientes pagarem os estabelecimentos por serviços ou produtos adquiridos
    digitalmente. Ela também permite a consulta dos status dos pagamentos, a data estipulada para
    a liquidação das transações realizadas e os métodos de pagamento
    disponíveis. Para demonstração, use as credenciais `orders:123mudar` para
    testar os filtros de autorização.
  version: 2.0.0
  title: Evoluservices Orders API
  contact:
    email: integracoes@evoluservices.com
servers:
  - url: 'https://sandbox.evoluservices.com'
tags:
  - name: payment-methods
    description: >-
      Obtém os métodos de pagamento disponíveis para estabelecimentos
      específicos conforme o valor desejado.
  - name: orders
    description: Operação para criar novos pedidos e verificar os já existentes.
paths:
  '/api/payment-methods':
    get:
      tags:
        - payment-methods
      summary: Possui as formas de pagamento disponíveis ao estabelecimento dado o valor pré-definido.
      operationId: paymentMethods
      parameters:
        - in: query
          name: paymentMethods.amount
          schema:
            type: string
          description: Valor do pagamento
          required: true
        - in: query
          name: paymentMethods.merchantCode
          schema:
            type: string
          description: Código de identificação do estabelecimento
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodsOutputDto'
        '400':
          description: Exceção de validação
        '401':
          description: Não autorizado
        '404':
          description: Estabelecimento não encontrado
        '422':
          description: Erro de integração
        '500':
          description: Erro interno no servidor
      security:
        - BasicAuth: []
  '/api/orders':
    post:
      tags:
        - orders
      summary: Cria novo link de pagamento e retorna url para o pagamento ser realizado.
      operationId: createOrders
      requestBody:
        description: Objeto contendo as informações para criar o link de pagamento.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientsOrderInputDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientsOrderOutputDto'
        '400':
          description: Exceção de validação
        '401':
          description: Não autorizado
        '404':
          description: Estabelecimento não encontrado
        '422':
          description: Erro de integração
        '500':
          description: Erro interno no servidor
      security:
        - BasicAuth: []
  '/api/orders/{uuid}':
    get:
      tags:
        - orders
      parameters:
        - required: true
          in: path
          name: uuid
          schema:
            type: string
          description: Uuid do Link de Pagamento
      summary: 'Consulta o Link de Pagamento de acordo com o uuid.'
      operationId: consultOrder
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientsOrderTransactionsDto'
        '400':
          description: Exceção de validação
        '401':
          description: Não autorizado
        '404':
          description: Pedido não encontrado
        '422':
          description: Erro de integração
        '500':
          description: Erro interno no servidor
      security:
        - BasicAuth: []
    delete:
      tags:
        - orders
      parameters:
        - required: true
          in: path
          name: uuid
          schema:
            type: string
          description: Uuid do Link de Pagamento a ser cancelado
      summary: 'Tenta efetuar o cancelamento de um Link de Pagamento de acordo com o seu Uuid.'
      operationId: cancelOrder
      responses:
        '200':
          description: OK
        '400':
          description: Exceção de validação
        '401':
          description: Credenciais invalidas, não autorizado
        '403':
          description: Uuid nulo ou vazio, não autorizado
        '404':
          description: Pedido não encontrado
        '500':
          description: Erro interno no servidor
      security:
        - BasicAuth: []
components:
  schemas:
    PaymentMethodsInputDto:
      type: object
      description: >-
        Objeto para a busca de formas de pagamento disponíveis ao estabelecimento conforme valor desejado.
      properties:
        amount:
          type: string
          example: '10000.00'
          description: 'Valor do pagamento'
        merchantCode:
          type: string
          example: AVD242AN
          description: 'Código do estabelecimento'
    PaymentMethodsOutputDto:
      type: object
      description: >-
        Objeto de retorno contendo as informações sobre as formas de pagamento disponíveis.
      properties:
        paymentMethods:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethod'
    PaymentMethod:
      type: object
      description: >-
        Objeto contendo as informações de pagamento do estabelecimento.
      properties:
        type:
          type: string
          example: CREDIT
          enum:
            - CREDIT
            - RECURRENT
          description: >-
            Determina o método de pagamento, podendo ser crédito ou recorrente
        options:
          type: object
          $ref: '#/components/schemas/PaymentOption'
    PaymentOption:
      type: object
      description: 'Opção para o tipo de pagamento do estabelecimento'
      properties:
        maxInstallments:
          type: number
          example: '12'
          description: 'Número máximo de parcelas permitido para a opção'
        paymentBrands:
          type: object
          description: 'Bandeiras disponíveis para a opção'
          properties:
            value:
              type: array
              items:
                type: string
                example: VISA
    ClientsOrderInputDto:
      type: object
      description: >-
        Objeto contendo informações para a solicitação de uma nova transação.
      properties:
        order:
          type: object
          properties:
            reference:
              type: string
              example: 123CLIENTS
              description: >-
                Identificação referenciando o order
            redirectUrl:
              type: string
              example: 'https://example.com/callback'
              description: >-
                Redireciona a URL depois do pagamento do pedido. Faça um retorno
                de chamada 'POST' com o formato 'x-www-form-urlencoded' e com os
                parâmetros 'uuid' e 'transactionNumber'
            amount:
              type: string
              example: '10000.00'
              description: >-
                Valor do order, em formato decimal (XXXX.XX)
            maxInstallments:
              type: number
              example: '2'
              description: >-
                Número máximo de parcelas permitidos pelo order
            minInstallments:
              type: number
              example: '2'
              description: >-
                Número mínimo de parcelas permitidos pelo order.
                Opcional, caso não seja inserido um valor será considerado como `1`, por padrão.
                Não pode ser maior do que o valor inserido em `maxInstallments`.
            merchantCode:
              type: string
              example: A1B2C3
              description: >-
                Código do estabelecimento referente ao order
            customerName:
              type: string
              example: Rodrigo
              description: >-
                Nome do cliente do order
            customerDocument:
              type: string
              example: 01234567890
              description: >-
                Documento do cliente do order
            recurrent:
              type: boolean
              example: true
              description: >-
                Indica se o pagamento do order é do tipo recorrente ou não
            recurrenceType:
              type: string
              description: >-
                Tipo de recorrência do pagamento do order podendo ser mensal ou flexível
                (por período fixo determinado).
                O preenchimento do campo é Obrigatório caso o campo
                `recurrent` seja definido como `true`.
              enum:
                - MONTHLY
                - FLEXIBLE
            quantityCharges:
              type: number
              example: '10'
              description: >-
                Quantidade de recorrências que serão cobradas no order
                O preenchimento do campo é Obrigatório caso o campo
                `recurrent` seja definido como `true`.
            frequency:
              type: number
              example: '30'
              description: >-
                Período fixo entre as cobranças da recorrência, em dias.
                O preenchimento do campo é Obrigatório caso o campo
                `recurrent` seja definido como `true`.
            description:
              type: string
              example: "Venda de equipamento efetuada na data 13/05/2020"
              description: >-
                Descrição mais detalhada referente à order.
            expirationDate:
              type: string
              example: "2020-07-16"
              description: >-
                Data de expiração da order no formato yyyy-MM-dd. O campo é opcional
    ClientsOrderOutputDto:
      type: object
      description: >-
        Objeto de retorno contendo informações sobre o link de pagamento gerado pelo order.
      properties:
        uuid:
          type: string
          example: e2ba235d-0b30-4edc-981d-e2c222763aee
          description: >-
            UUID do link de pagamento gerado pelo order
        payUrl:
          type: string
          example: api.evoluservices.com/orders/pay
          description: >-
            URL do link de pagamento para tal order
        reference:
          type: string
          example: 123CLIENTS
          description: >-
            Identificação referenciando o order
        status:
          type: string
          description: >-
            Status do order
          enum:
            - APPROVED
            - CANCELED
            - PENDING
    ClientsOrderTransactionsDto:
      type: object
      description: >-
        Objeto de retorno contendo informações sobre a transação efetuada por um link de pagamento
        de acordo com o UUID buscado.
      properties:
        uuid:
          type: string
          example: e2ba235d-0b30-4edc-981d-e2c222763aee
          description: >-
            UUID do link de pagamento
        reference:
          type: string
          example: 123CLIENTS
          description: >-
            Identificação referenciando o order da transação
        status:
          type: string
          description: >+
            Status da transação
          enum:
            - APPROVED
            - CANCELED
            - PENDING
        transactionList:
          type: array
          description: >-
            Transações efetuadas pelo link de pagamento.
          items:
            $ref: '#/components/schemas/ClientsTransactionDto'
    ClientsTransactionDto:
      type: object
      description: >-
        Objeto contendo as informações sobre as transações efetuadas pelo link de pagamento.
      properties:
        number:
          type: number
          example: '12345678909'
          description: >-
            Número da transação
        status:
          type: string
          enum:
            - APPROVED
            - CANCELLED
            - ABORTED
            - ABORTED_BY_MERCHANT
            - PARTIALLY_CANCELED
          description: >-
            Além dos valores abaixo, temos algumas outras possibilidades de
            status para controle interno, por exemplo: COMPLETE, INCOMPLETE,
            CANCEL_REQUESTED, etc, mas eles não devem ser considerados como
            valores esperados porque são extremamente voláteis
        amount:
          type: number
          example: '100.00'
          description: >-
            Valor da transação no formato decimal (XXXX.XX)
        installments:
          type: number
          example: '2'
          description: >-
            Número de parcelas efetuadas na transação
        paymentBrand:
          type: string
          description: >-
            Bandeira com a qual a transação foi efetuada
          enum:
            - VISA_CREDITO
            - VISA_ELECTRON
            - MASTERCARD
            - MAESTRO
            - AMEX
            - DINERS
            - HIPERCARD
            - AURA
            - SOROCRED
            - BANRISUL
            - ELO
            - SICREDI
            - ELO_DEBITO
            - BRADESCO
            - HIPER
            - AGIPLAN
            - BANESCARD
            - CREDZ
            - JCB
            - CABAL
            - MAIS
            - CHEQUE_TELECHEQUE
            - CHEQUE_CREDITALL
            - BOLETO
            - BANESCARD_DEBITO
            - CABAL_DEBITO
            - HIPER_DEBITO
            - REDESHOP
        paymentQuantity:
          type: number
          example: '3'
          description: >-
            Quantidades de pagamentos existentes na transação
        nsu:
          type: string
          example: '993485982'
          description: >-
            NSU da transação
        authorizationNumber:
          type: string
          example: '470216'
          description: >-
            Número de autorização da transação
        customer:
          type: object
          $ref: '#/components/schemas/SubjectIdentifierDto'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/ClientsTransactionPaymentDto'
    SubjectIdentifierDto:
      type: object
      description: >-
        Objeto contendo informações do cliente que efetuou a transação com link de pagamento.
      properties:
        name:
          type: string
          example: Jose da Silva
          description: >-
            Nome do cliente
        document:
          type: string
          example: 123.456.789-09
          description: >-
            Documento do cliente
    ClientsTransactionPaymentDto:
      type: object
      description: >-
        Objeto contendo informações sobre o pagamento da transação feita pelo link de pagamento.
      properties:
        number:
          type: number
          example: '12345678909'
          description: >-
            Número do pagamento
        amount:
          type: number
          example: '100.00'
          description: >-
            Valor do pagamento, em formato decimal
        status:
          type: string
          description: >-
            Status do pagamento da transação
          enum:
            - PAYED
            - UNPAID
            - ANTICIPATION_REQUESTED
            - ANTICIPATED
            - CANCEL_REQUESTED
            - CANCELLED
        payDate:
          type: string
          example: 01/01/2001
          description: >-
            Data em que o pagamento efetivamente foi feito ou, se
            ainda não foi pago, data esperada de pagamento
        merchant:
          type: object
          $ref: '#/components/schemas/SubjectIdentifierDto'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic