openapi: 3.0.0
info:
  title: API Acquiring Services - Open Finance Brasil
  description: |
    API de Credenciamento do Open Finance Brasil – Fase 4.
    API que retorna informações de Credenciamento.
  version: 1.0.1
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0'
  contact:
    name: Governança do Open Finance Brasil – Especificações
    email: gt-interfaces@openbankingbr.org
    url: 'https://openbanking-brasil.github.io/areadesenvolvedor/'
servers:
  - url: 'https://api.banco.com.br/open-banking/opendata-acquiring-services/v1'
    description: Servidor de Produção
  - url: 'https://apih.banco.com.br/open-banking/opendata-acquiring-services/v1'
    description: Servidor de Homologação
tags:
  - name: PersonalAcquiringServices
    description: Operações para obter as informações de Credenciamento para Pessoa Física.
  - name: BusinessAcquiringServices
    description: Operações para obter as informações de Credenciamento para Pessoa Jurídica.
paths:
  /personals:
    get:
      tags:
        - PersonalAcquiringServices
      summary: Conjunto de informações de Credenciamento para Pessoa Física.
      operationId: getPersonalAcquiringServices
      description: Método para disponibilizar as taxas e tarifas por serviços.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          $ref: '#/components/responses/OKResponseAcquiringServices'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
  /businesses:
    get:
      tags:
        - BusinessAcquiringServices
      summary: Conjunto de informações de Credenciamento para Pessoa Jurídica.
      operationId: getBusinessAcquiringServices
      description: Método para disponibilizar as taxas e tarifas por serviços.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          $ref: '#/components/responses/OKResponseAcquiringServices'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
components:
  schemas:
    OKResponseAcquiringServices:
      type: object
      required:
        - data
        - links
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AcquiringServicesContractData'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/OpenDataMeta'
      additionalProperties: false
    Links:
      type: object
      description: Referências para outros recusos da API requisitada.
      required:
        - self
      properties:
        self:
          type: string
          format: url
          maxLength: 2000
          description: URI completo que gerou a resposta atual.
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
        first:
          type: string
          format: url
          maxLength: 2000
          description: URI da primeira página que originou essa lista de resultados. Restrição - Obrigatório quando não for a primeira página da resposta
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
        prev:
          type: string
          format: url
          maxLength: 2000
          description: "URI da página anterior dessa lista de resultados. Restrição - \tObrigatório quando não for a primeira página da resposta"
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
        next:
          type: string
          format: url
          maxLength: 2000
          description: URI da próxima página dessa lista de resultados. Restrição - Obrigatório quando não for a última página da resposta
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
        last:
          type: string
          format: url
          maxLength: 2000
          description: URI da última página dessa lista de resultados. Restrição - Obrigatório quando não for a última página da resposta
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
      additionalProperties: false
    OpenDataMeta:
      type: object
      description: Meta informações referente à API requisitada.
      required:
        - totalRecords
        - totalPages
      properties:
        totalRecords:
          type: integer
          format: int32
          description: Número total de registros no resultado
          example: 1
        totalPages:
          type: integer
          format: int32
          description: Número total de páginas no resultado
          example: 1
      additionalProperties: false
    AcquiringParticipant:
      type: object
      description: Conjunto de informações relativas ao participante do produto de Open Finance
      required:
        - brand
        - name
        - cnpjNumber
      properties:
        brand:
          type: string
          description: 'Nome da marca reportada pelo participante do Open Finance. O conceito a que se refere a ''marca'' é em essência uma promessa da empresa em fornecer uma série específica de atributos, benefícios e serviços uniformes aos clientes.'
          pattern: '[\w\W\s]*'
          maxLength: 80
          example: Organização
        name:
          type: string
          description: Nome do participante do Open Finance.
          pattern: '[\w\W\s]*'
          maxLength: 80
          example: Organização A1
        cnpjNumber:
          type: string
          description: 'O CNPJ corresponde ao número de inscrição no Cadastro de Pessoa Jurídica. Deve-se ter apenas os números do CNPJ, sem máscara.'
          pattern: '^\d{14}$'
          example: '13456789000112'
        urlComplementaryList:
          type: string
          description: |
            Espera-se que valor de retorno, após acesso ao link ‘urlComplementaryList’, deve ser array de objeto com a estrutura abaixo:

            - ‘name’ com o valor contido no campo ‘LegalEntityName’ conforme cadastro no diretório;

            - 'cnpjNumber' com o valor contido no campo CNPJ (‘RegistrationNumber’) correspondente a esta instituição;

            - Ambos do tipo string;

            - Ambos obrigatórios.
          maxLength: 1024
          pattern: '^(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$'
          example: 'https://empresaa1.com/companies'
      additionalProperties: false
    EnumAcquiringServicesFeeName:
      type: string
      description: |
        Nome da tarifa cobrada sobre o serviço de credenciamento, para pessoa física/jurídica.
          1. Taxa de Desconto na Modalidade Crédito
          2. Taxa de Desconto na Modalidade Débito
      enum:
        - TAXA_DESCONTO_MODALIDADE_CREDITO
        - TAXA_DESCONTO_MODALIDADE_DEBITO
      example: TAXA_DESCONTO_MODALIDADE_CREDITO
    EnumAcquiringServicesCode:
      type: string
      description: Sigla da Tarifa cobrada sobre o Serviço de Credenciamento informado.
      enum:
        - MDR_CREDITO
        - MDR_DEBITO
      example: MDR_CREDITO
    EnumAcquiringServicesInterval:
      type: string
      description: Identificação do intervalo a ser exibido.
      enum:
        - 1_FAIXA
        - 2_FAIXA
        - 3_FAIXA
        - 4_FAIXA
      example: 1_FAIXA
    Price:
      type: object
      description: '4 Faixas de igual tamanho, com suas respectivas medianas e percentuais de clientes.'
      required:
        - interval
        - value
        - customerRate
      properties:
        interval:
          $ref: '#/components/schemas/EnumAcquiringServicesInterval'
        value:
          type: string
          example: '0.019800'
          minLength: 8
          maxLength: 8
          pattern: '^\d{1}\.\d{6}$'
          description: Mediana referente a taxa de desconto de débito ou crédito a cada intervalo.
        customerRate:
          type: string
          example: '0.019800'
          minLength: 8
          maxLength: 8
          pattern: '^\d{1}\.\d{6}$'
          description: Percentual de cliente em cada intervalo.
      additionalProperties: false
    AcquiringServicesContractData:
      type: object
      description: Conjunto de informações referentes às informações de credenciamento
      required:
        - participant
        - feeName
        - code
        - prices
        - chargingTriggerInfo
        - minimum
        - maximum
      properties:
        participant:
          $ref: '#/components/schemas/AcquiringParticipant'
        feeName:
          $ref: '#/components/schemas/EnumAcquiringServicesFeeName'
        code:
          $ref: '#/components/schemas/EnumAcquiringServicesCode'
        prices:
          type: array
          minItems: 4
          maxItems: 4
          items:
            $ref: '#/components/schemas/Price'
          example:
            - interval: 1_FAIXA
              value: '0.020300'
              customerRate: '0.500000'
            - interval: 2_FAIXA
              value: '0.030600'
              customerRate: '0.100000'
            - interval: 3_FAIXA
              value: '0.034300'
              customerRate: '0.300000'
            - interval: 4_FAIXA
              value: '0.246800'
              customerRate: '0.100000'
        chargingTriggerInfo:
          type: string
          minLength: 1
          maxLength: 200
          example: Recebimento através de transação de cartão.
          description: |
            Descrição do Fator gerador de cobrança que incide sobre o serviço de credenciamento.
        minimum:
          type: string
          minLength: 8
          maxLength: 8
          pattern: '^\d{1}\.\d{6}$'
          description: Valor mínimo
          example: '0.019800'
        maximum:
          type: string
          minLength: 8
          maxLength: 8
          pattern: '^\d{1}\.\d{6}$'
          description: Valor máximo
          example: '0.019800'
      additionalProperties: false
    OpenDataResponseError:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          minItems: 1
          maxItems: 13
          items:
            type: object
            required:
              - code
              - title
              - detail
            properties:
              code:
                description: Código de erro específico do endpoint
                type: string
                pattern: '[\w\W\s]*'
                maxLength: 255
              title:
                description: Título legível por humanos deste erro específico
                type: string
                pattern: '[\w\W\s]*'
                maxLength: 255
              detail:
                description: Descrição legível por humanos deste erro específico
                type: string
                pattern: '[\w\W\s]*'
                maxLength: 2048
            additionalProperties: false
        meta:
          $ref: '#/components/schemas/OpenDataMeta'
      additionalProperties: false
  parameters:
    page:
      name: page
      in: query
      description: Número da página que está sendo requisitada (o valor da primeira página é 1).
      schema:
        type: integer
        default: 1
        minimum: 1
        maximum: 2147483647
        format: int32
    pageSize:
      name: page-size
      in: query
      description: Quantidade total de registros por páginas.
      schema:
        type: integer
        default: 25
        minimum: 1
        format: int32
        maximum: 1000
  responses:
    OKResponseAcquiringServices:
      description: Dados de operações de credenciamento obtidos com sucesso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OKResponseAcquiringServices'
    BadRequest:
      description: 'A requisição foi malformada, omitindo atributos obrigatórios, seja no payload ou através de atributos na URL.'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OpenDataResponseError'
    NotFound:
      description: O recurso solicitado não existe ou não foi implementado
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OpenDataResponseError'
    MethodNotAllowed:
      description: O consumidor tentou acessar o recurso com um método não suportado
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OpenDataResponseError'
    TooManyRequests:
      description: 'A operação foi recusada, pois muitas solicitações foram feitas dentro de um determinado período ou o limite de requisições concorrentes foi atingido.'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OpenDataResponseError'
    InternalServerError:
      description: Ocorreu um erro no gateway da API ou no microsserviço
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OpenDataResponseError'
    SiteIsOverloaded:
      description: 'O site está sobrecarregado e a operação foi recusada, pois foi atingido o limite máximo de TPS global, neste momento.'
      content:
        application/json; charset=utf-8:
          schema:
            type: object
            required:
              - errors
            properties:
              errors:
                type: array
                minItems: 1
                maxItems: 13
                items:
                  type: object
                  required:
                    - code
                    - title
                    - detail
                  properties:
                    code:
                      description: Código de erro específico do endpoint
                      type: string
                      pattern: '[\w\W\s]*'
                      maxLength: 255
                    title:
                      description: Título legível por humanos deste erro específico
                      type: string
                      pattern: '[\w\W\s]*'
                      maxLength: 255
                    detail:
                      description: Descrição legível por humanos deste erro específico
                      type: string
                      pattern: '[\w\W\s]*'
                      maxLength: 2048
              meta:
                type: object
                description: Meta informações referente à API requisitada.
                required:
                  - requestDateTime
                properties:
                  requestDateTime:
                    description: 'Data e hora da consulta, conforme especificação RFC-3339, formato UTC.'
                    type: string
                    maxLength: 20
                    format: date-time
                    example: '2021-05-21T08:30:00Z'