openapi: 3.0.0
info:
  title: APIs OpenData do Open Finance Brasil
  description: As APIs descritas neste documento são referentes as APIs da fase OpenData do Open Finance Brasil.
  version: 2.0.1
  contact:
    url: 'https://servicedesk.openbankingbrasil.org.br/Login.jsp?navLanguage=pt-BR'
servers:
  - url: 'http://api.banco.com.br/open-banking/discovery/v2'
tags:
- name: "Discovery"
paths:
  /status:
    get:
      tags:
        - Discovery
      summary: Descrição do status da implementação das APIs do OFB
      description: Descrição do status da implementação das APIs do OFB
      operationId: "getStatus"
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/pageSize"
      responses:
        '200':
          description: Descrição do status da implementação das APIs do OFB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDiscoveryStatusList'
        '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'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
        default:
          $ref: '#/components/responses/Default'
  /outages:
    get:
      tags:
        - Discovery
      summary: a descrição referente ao código de status retornado pelas APIs
      description: "a descrição referente ao código de status retornado pelas APIs"
      operationId: "getOutage"
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/pageSize"
      responses:
        '200':
          description: código de status retornado pelas APIs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDiscoveryOutageList'
        '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'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
        default:
          $ref: '#/components/responses/Default'
components:
  schemas:
    ResponseDiscoveryStatusList:
      type: object
      required:
        - data
        - links
        - meta
      properties:
        data:
          type: object
          required:
            - status
          properties:
            status:
              type: array
              maxItems: 1000
              items:
                $ref: '#/components/schemas/Status'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    ResponseDiscoveryOutageList:
      type: object
      required:
        - data
        - links
        - meta
      properties:
        data:
          type: array
          maxItems: 1000
          items:
            type: object
            required:
              - outageTime
              - duration
              - isPartial
              - explanation
            properties:
              outageTime:
                type: string
                pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$'
                description: Data e hora planejada do início da indisponibilidade
                example: '2020-07-21T08:30:00Z'
              duration:
                type: string
                pattern: '^(?!\s)[\w\W\s]*[^\s]$'
                description: Duração prevista da indisponibilidade
                example: PT2H30M
              isPartial:
                type: boolean
                description: Flag que indica se a indisponibilidade é parcial (atingindo apenas alguns end points) ou total (atingindo todos os end points)
                example: false
              explanation:
                type: string
                pattern: '^(?!\s)[\w\W\s]*[^\s]$'
                description: Explicação sobre os motivos da indisponibilidade, podendo a instituição indicar quais implementações estarão indisponíveis.
                example: Atualização do API Gateway
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    Links:
      type: object
      properties:
        self:
          type: string
          format: url
          description: URL da página atualmente requisitada
          maxLength: 2000
          example: 'https://api.banco.com.br/open-banking/common/v2/resource'
        first:
          type: string
          format: url
          description: URL da primeira página de registros
          maxLength: 2000
          example: 'https://api.banco.com.br/open-banking/common/v2/resource'
        prev:
          type: string
          format: url
          description: URL da página anterior de registros
          maxLength: 2000
          example: 'https://api.banco.com.br/open-banking/common/v2/resource'
        next:
          type: string
          format: url
          description: URL da próxima página de registros
          maxLength: 2000
          example: 'https://api.banco.com.br/open-banking/common/v2/resource'
        last:
          type: string
          format: url
          description: URL da última página de registros
          maxLength: 2000
          example: 'https://api.banco.com.br/open-banking/common/v2/resource'
    Meta:
      type: object
      properties:
        totalRecords:
          type: integer
          description: Total de registros encontrados
          example: 1
        totalPages:
          type: integer
          description: Total de páginas para os registros encontrados
          example: 1
      required:
        - totalRecords
        - totalPages
    Status:
      type: object
      required:
        - code
        - explanation
      properties:
        code:
          type: string
          enum:
            - OK
            - PARTIAL_FAILURE
            - UNAVAILABLE
            - SCHEDULED_OUTAGE
          description: |
            Condição atual da Implementação das APIs do OFB:
            - OK - A implementação de todas as APIs foi concluída e está totalmente funcional 
            - UNAVAILABLE - Uma ou mais APIs estão indisponíveis 
            - PARTIAL_FAILURE - Um ou mais endpoints estão indisponíveis 
            - SCHEDULED_OUTAGE - Uma interrupção programada (anunciada pelo endpoint /outages) está em vigor 
            
            A hierarquia de `data/status/code`, em casos concomitantes, segue a ordem conforme os bullets acima (OK, UNAVAILABLE, PARTIAL_FAILURE, SCHEDULED_OUTAGE)
          example: OK
        explanation:
          type: string
          description: Fornece uma explicação da interrupção atual que pode ser exibida para um cliente final. Será obrigatoriamente preenchido se code tiver algum valor que não seja OK
          pattern: '^(?!\s)[\w\W\s]*[^\s]$'
          maxLength: 2000
          example: Retorno com Sucesso
        detectionTime:
          type: string
          description: A data e hora em que a interrupção atual foi detectada. Será obrigatoriamente preenchido se a propriedade code for PARTIAL_FAILURE ou UNAVAILABLE
          pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$'
          maxLength: 20
          example: '2020-07-21T08:30:00Z'
        expectedResolutionTime:
          type: string
          description: A data e hora em que o serviço completo deve continuar (se conhecido). Será obrigatoriamente preenchido se code tiver algum valor que não seja OK
          pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$'
          maxLength: 20
          example: '2020-07-21T08:30:00Z'
        updateTime:
          type: string
          description: A data e hora em que esse status foi atualizado pela última vez pelo titular dos dados.
          pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$'
          maxLength: 20
          example: '2020-01-02T01:00:00Z'
        unavailableEndpoints:
          type: array
          description: Endpoints com indisponibilidade
          maxItems: 1000
          items:
            type: string
            maxLength: 2000
          example:
            - 'https://api.banco.com.br/open-banking/common/v2/resource'
    ResponseErrorMetaSingle:
      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'
    ResponseError:
      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:
            - totalRecords
            - totalPages
            - requestDateTime
          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
            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'
  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
        maximum: 1000
        format: int32
  responses:
    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/ResponseError'
    NotFound:
      description: O recurso solicitado não existe ou não foi implementado.
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    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/ResponseError'
    TooManyRequests:
      description: A operação foi recusada, pois muitas solicitações foram feitas dentro de um determinado período ou o limite global de requisições concorrentes foi atingido.
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    InternalServerError:
      description: Ocorreu um erro no gateway da API ou no microsserviço.
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    GatewayTimeout:
      description: GATEWAY TIMEOUT - A requisição não foi atendida dentro do tempo limite estabelecido.
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    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:
            $ref: '#/components/schemas/ResponseErrorMetaSingle'
    Default:
      description: '\-'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'