openapi: 3.0.0
info:
  title: APIs Open Data do Open Insurance Brasil
  description:
    API de informações de Título de Capitaliazação.
  version: 1.3.0
  contact:
    url: 'https://www.gov.br/susep/'
servers:
  - url: 'https://api.organizacao.com.br/open-insurance/products-services/v1'
    description: Servidor de Produção
  - url: 'https://api.organizacao.com.br/open-insurance/products-services/v1'
    description: Servidor de Homologação
tags:
- name: "capitalization-title"
paths:
  /capitalization-title:
    get:
      tags:
        - capitalization-title
      summary: Obtém a lista dos produtos do tipo título de capitalização
      description: "Obtém a lista dos produtos do tipo título de capitalização"
      operationId: "capitalizationTitle"
      parameters:
        - $ref: "#/components/parameters/cache-Control"
        - $ref: "#/components/parameters/content-Security-Policy"
        - $ref: "#/components/parameters/content-Type"
        - $ref: "#/components/parameters/strict-Transport-Security"
        - $ref: "#/components/parameters/x-Content-Type-Options"
        - $ref: "#/components/parameters/x-Frame-Options"
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/x-v"
        - $ref: "#/components/parameters/x-min-v"
      responses:
        '200':
          description: Dados dos produtos de Título de Capitalização
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCapitalizationTitleList'
          headers:
            x-v:
              description: |
                Caso x-min-v e x-v tenham sido enviados, o titular dos dados deve responder
                com a versao mais alta suportada entre x-min-v e x-v.
                Caso x-min-v e x-v nao tenham sido enviados, o titular dos dados deve responder
                com a versao que esta sendo utilizada naquele momento.
              required: true
              schema:
                type: string
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Dados dos produtos de Título de Capitalização
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCapitalizationTitleList'
          headers:
            x-v:
              description: |
                Caso x-min-v e x-v tenham sido enviados, o titular dos dados deve responder
                com a versao mais alta suportada entre x-min-v e x-v.
                Caso x-min-v e x-v nao tenham sido enviados, o titular dos dados deve responder
                com a versao que esta sendo utilizada naquele momento.
              required: true
              schema:
                type: string
components:
  schemas:
    ResponseCapitalizationTitleList:
      type: object
      required:
        - data
        - links
        - meta
      properties:
        requestTime:
          description: 'Data e hora da consulta, conforme especificação RFC-3339, formato UTC.'
          type: string
          pattern: '[\w\W\s]*'
          maxLength: 2048
          format: date-time
          example: '2021-08-20T08:30:00Z'
        data:
          type: object
          required:
            - brand
          properties:
            brand:
              $ref: '#/components/schemas/CapitalizationTitleBrand'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'

    CapitalizationTitleBrand:
      type: object
      description: Organização controladora do grupo.
      required:
        - name
        - companies
      properties:
        name:
          type: string
          description: Nome da marca reportada pelo participante do Open Insurance. O conceito a que se refere a marca é em essência uma promessa das sociedades sob ela em fornecer uma série específica de atributos, benefícios e serviços uniformes aos clientes.
          maxLength: 80
          example: ACME seguros
        companies:
          $ref: '#/components/schemas/CapitalizationTitleCompany'

    CapitalizationTitleCompany:
      type: array
      items:
        description: Informações referente a sociedade a qual a marca pertence.
        required:
          - name
          - cnpjNumber
          - products
        properties:
          name:
            type: string
            description: Nome da sociedade pertencente à marca.
            maxLength: 80
            example: ACME cap da ACME seguros
          cnpjNumber:
            type: string
            description: CNPJ da sociedade pertencente à marca.
            pattern: ^\d{14}$
            example: '12345678901234'
          products:
            $ref: '#/components/schemas/CapitalizationTitleProduct'

    CapitalizationTitleProduct:
      type: array
      description: Lista de produtos de uma empresa.
      items:
        type: object
        required:
          - name
          - code
          - modality
          - quotas
          - validity
          - capitalizationPeriod
          - costType
          - termsAndConditions
          - latePayment
          - contributionPayment
          - redemption
          - raffle
          - additionalDetails
          - minimumRequirements
          - targetAudiences
        properties:
          name:
            type: string
            description: Nome comercial do produto, pelo qual é identificado nos canais de distribuição e atendimento da sociedade.
            maxLength: 80
            example: ACMEcap
          code:
            type: string
            description: Código único a ser definido pela sociedade.
            maxLength: 100
            example: 01234589_cap
          modality:
            type: string
            description: Modalidade.
            enum: [TRADICIONAL, INSTRUMENTO_GARANTIA, COMPRA_PROGRAMADA, POPULAR, INCENTIVO, FILANTROPIA_PREMIAVEL]
            example: TRADICIONAL
          costType:
            type: string
            description: Forma de custeio
            enum: [PAGAMENTO_UNICO, PAGAMENTO_MENSAL, PAGAMENTO_PERIODICO]
            example: PAGAMENTO_UNICO
          termsAndConditions:
            $ref: '#/components/schemas/CapitalizationTitleTerms'
          quotas:
            type: array
            items:
              $ref: '#/components/schemas/CapitalizationTitleQuotas'
          validity:
            $ref: '#/components/schemas/CapitalizationTitleValidity'
          serieSize:
            $ref: '#/components/schemas/CapitalizationTitleSerieSize'
          capitalizationPeriod:
            $ref: '#/components/schemas/CapitalizationTitlePeriod'
          latePayment:
            $ref: '#/components/schemas/CapitalizationTitleLatePayment'
          contributionPayment:
            $ref: '#/components/schemas/CapitalizationTitleContributionPayment'
          redemption:
            $ref: '#/components/schemas/CapitalizationTitleRedemption'
          raffle:
            $ref: '#/components/schemas/CapitalizationTitleRaffle'
          additionalDetails:
            $ref: '#/components/schemas/CapitalizationTitleAdditionals'
          minimumRequirements:
            $ref: '#/components/schemas/CapitalizationTitleMinimumRequirements'
          targetAudiences:
            description: Público Alvo
            type: array
            items:
              type: string
              example: PESSOA_NATURAL
              enum: [PESSOA_NATURAL, PESSOA_JURIDICA]

    CapitalizationTitleTerms:
      type: object
      description: Informações dos termos e condições conforme número do processo SUSEP.
      required:
        - susepProcessNumber
        - termsRegulations
      properties:
        susepProcessNumber:
          type: string
          description: Número do processo SUSEP.
          maxLength: 30
          example: '15414622222222222'
        termsRegulations:
          type: string
          description: Campo aberto (possibilidade de incluir uma url).
          maxLength: 1024
          example: https://seguradora.exemplo.com.br/capitalizacao/pdf/condicoes_gerais.pdf

    CapitalizationTitleQuotas:
        type: object
        description: Quotas
        required:
          - quota
          - capitalizationQuota
          - raffleQuota
          - chargingQuota
        properties:
            quota:
              type: integer
              description: Número da parcela.
              example: 10
            capitalizationQuota:
              type: string
              description: Percentual da contribuição destinado à constituição de capital referente ao direito de resgate.
              pattern: ^[0-1]\.\d{6}$
              example: '0.000002'
            raffleQuota:
              type: string
              description: Percentual da contribuição designado a custear os sorteios, se previstos no plano
              pattern: ^[0-1]\.\d{6}$
              example: '0.000002'
            chargingQuota:
              type: string
              description: Percentual da contribuição destinado aos custos de despesas com corretagem, colocação e administração do título de capitalização, emissão, divulgação, lucro da sociedade de capitalização e eventuais despesas relavas ao custeio da contemplação obrigatória e da distribuição de bônus.
              pattern: ^[0-1]\.\d{6}$
              example: '0.000002'

    CapitalizationTitleValidity:
        type: integer
        description: Prazo de vigência do título de capitalização em meses.
        maxLength: 3
        example: 48

    CapitalizationTitleSerieSize:
        type: integer
        description: Os títulos de capitalização que prevejam sorteio devem ser estruturados em series, ou seja, em sequencias ou em grupos de títulos submetidos às mesmas condições e características, à exceção do valor do pagamento.
        maxLength: 10
        example: 5000000

    CapitalizationTitlePeriod:
        description: Período de Capitalização
        type: object
        required:
          - interestRate
          - updateIndex
          - contributionAmount
          - earlyRedemption
          - redemptionPercentageEndTerm
          - gracePeriodRedemption
        properties:
          interestRate:
            description: |
              Taxa de juros que remunera a provisão matemática para capitalização.
              (Taxa que remunera a parte da mensalidade destinada a formar o Capital,
              ou seja, a Provisão Matemática de Resgate, também chamada de saldo de capitalização.
              Em porcentagem ao mês (% a.m)). Exemplo 1.000000 igual a 100 por cento
            type: string
            pattern: ^[0-1]\.\d{6}$
            example: '0.000002'
          updateIndex:
            type: string
            description: Índice utilizado na correção que remunera a provisão matemática para capitalização
            example: IPCA
            enum: [IPCA, IGPM, INPC, TR, INDICE_REMUNERACAO_DEPOSITOS_POUPANCA, OUTROS]
          updateIndexOthers:
            type: string
            description: Preenchida pelas participantes quando houver ‘Outros’ no campo.
            example: Índice de atualização
          contributionAmount:
            $ref: '#/components/schemas/CapitalizationTitleContributionAmount'
          earlyRedemption:
            description: Possibilidade de o titular efetuar o resgate do capital constituído antes do fim do prazo de vigência do título, podendo ocorrer por solicitação expressa do titular ou por contemplação em sorteio com liquidação antecipada
            type: array
            items:
              type: object
              required:
                - quota
                - percentage
              properties:
                quota:
                  type: integer
                  description: Número de parcela.
                percentage:
                  type: number
                  description: Percentual da quota
          redemptionPercentageEndTerm:
            description: Percentual mínimo da soma das contribuições efetuadas que poderá ser resgatado ao final da vigência, tendo como condição os pagamentos das parcelas nos respectivos vencimentos.
            type: string
            pattern: ^\d{1}\.\d{6}$
            example: '0.000002'
          gracePeriodRedemption:
            description: Intervalo de tempo mínimo entre contratação e resgate do direito, em meses.
            type: integer
            maxLength: 3
            example: 48

    CapitalizationTitleContributionAmount:
      type: object
      properties:
        minValue:
          type: number
          description: Valor Mínimo
          example: 500
        maxValue:
          type: number
          description: Valor Máximo
          example: 5000
        frequency:
          type: string
          description: Pagamento mensal, pagamento único ou periódico.
          example: MENSAL
          enum: [MENSAL, UNICO, PERIODICO]
        value:
          type: number
          description: valor

    CapitalizationTitleLatePayment:
        type: object
        description: Atraso de Pagamento
        required:
        - suspensionPeriod
        - termExtensionOption
        properties:
          suspensionPeriod:
            description: Prazo máximo (contínuo ou intermitente) em meses que o título fica suspenso por atraso de pagamento, antes de ser cancelado (não aplicável a pagamento único).
            type: integer
            maxLength: 3
            example: 10
          termExtensionOption:
            description: Alteração do prazo de vigência original, pela suspensão.
            type: boolean
            example: true

    CapitalizationTitleContributionPayment:
      type: object
      description: Pagamento da contribuição
      required:
        - paymentMethod
        - updateIndex
      properties:
        paymentMethod:
          description: Meio de Pagamento utilizados para pagamento da contribuição.
          type: array
          items:
            type: string
            example: CARTAO_CREDITO
            enum: [CARTAO_CREDITO, CARTAO_DEBITO, DEBITO_CONTA_CORRENTE, DEBITO_CONTA_POUPANCA, BOLETO_BANCARIO, PIX, CONSIGNACAO_FOLHA_PAGAMENTO, PAGAMENTO_COM_PONTOS, OUTROS]
        paymentDetail:
          description: Descrição do Meio de Pagamento utilizados para pagamento da contribuição quando for informada a opção OUTROS
          type: string
          maxLength: 100
          example: OUTROS
        updateIndex:
          description: Índice utilizado na atualização dos pagamentos mensais (para títulos com mais de 12 meses de vigência)
          type: array
          items:
            type: string
            example: IPCA
            enum: [IPCA, IGPM, INPC, TR, INDICE_REMUNERACAO_DEPOSITOS_POUPANCA, OUTROS]
        updateIndexOthers:
            type: array
            description: Preenchida pelas participantes quando houver ‘Outros’ no campo.
            items:
                type: string
                example: Índice de atualização

    CapitalizationTitleRedemption:
        type: object
        required:
        - redemption
        properties:
          redemption:
            description: Valor percentual (%) de resgate final permitido. Exemplo 1.000000 igual a 100 por cento
            type: string
            pattern: ^\d{1}\.\d{6}$
            example: '0.000002'

    CapitalizationTitleRaffle:
      description: Sorteios
      type: array
      items:
        type: object
        required:
          - timeInterval
          - raffleQty
          - raffleValue
          - earlySettlementRaffle
          - mandatoryContemplation
          - ruleDescription
          - minimumContemplationProbability
        properties:
          raffleQty:
            type: integer
            description: Número da quantidade de sorteios previstos ao longo da vigência
            maxLength: 5
            example: 10000
          timeInterval:
            description: Intervalo de tempo regular previsto entre os sorteios.
            type: array
            items:
              type: string
              example: QUINZENAL
              enum: [UNICO, DIARIO, SEMANAL, QUINZENAL, MENSAL, BIMESTRAL, TRIMESTRAL, QUADRIMESTRAL, SEMESTRAL, ANUAL, OUTROS]
          timeIntervalOthers:
            description: Descrição do Intervalo de tempo regular previsto entre os sorteios quando for informada a opção OUTROS.
            type: string
            maxLength: 100
            example: OUTROS
          raffleValue:
            type: number
            description: Valor dos sorteios representado por múltiplo do valor de contribuição.
            example: 5
          earlySettlementRaffle:
            type: boolean
            description: Liquidação antecipada em Sorteio. Modelo de sorteio que acarreta, ao título contemplado, o seu resgate total obrigatório (Resolução Normativa 384/20).
            example: true
          mandatoryContemplation:
            type: boolean
            description: Contemplação obrigatória. Possibilidade de realização de sorteio com previsão de que o título sorteado seja obrigatoriamente um título comercializado, desde que atingidos os requisitos definidos nas condições gerais do plano.
            example: true
          ruleDescription:
            type: string
            description: Campo aberto para descrição a ser feita por cada participante das regras dos sorteios do produto.
            maxLength: 200
            example: Sorteio às quartas-feiras
          minimumContemplationProbability:
            type: string
            description: Número representativo da probabilidade mínima de contemplação nos sorteios, em porcentagem (%). Exemplo 1.000000 igual a 100 por cento
            pattern: ^\d{1}\.\d{6}$
            example: '0.000002'

    CapitalizationTitleAdditionals:
      type: object
      required:
        - additionalDetails
      properties:
        additionalDetails:
          type: string
          description: Campo aberto (possibilidade de incluir URL).
          maxLength: 1024
          example: https://example.com/openinsurance

    CapitalizationTitleMinimumRequirements:
      type: object
      description: Requisitos mínimos.
      required:
        - minimumRequirementDetails
      properties:
        minimumRequirementDetails:
          type: string
          description: Detalhamento do requisito mínimo para contratação - Campo aberto (possibilidade de incluir URL).
          maxLength: 1024
          example: https://seguradora.exemplo.com.br/capitalizacao/requisitos_min.pdf

    Links:
      type: object
      properties:
        self:
          type: string
          description: URL da página atualmente requisitada
          pattern: ^(https:\/\/)(.*?)(\/open-insurance\/products-services\/v\d+)(\/capitalization-title.*)?$
          example: 'https://api.organizacao.com.br/open-insurance/products-services/v1/capitalization-title'
        first:
          type: string
          description: URL da primeira página de registros
          pattern: ^(https:\/\/)(.*?)(\/open-insurance\/products-services\/v\d+)(\/capitalization-title.*)?$
          example: 'https://api.organizacao.com.br/open-insurance/products-services/v1/capitalization-title'
        prev:
          type: string
          description: URL da página anterior de registros
          pattern: ^(https:\/\/)(.*?)(\/open-insurance\/products-services\/v\d+)(\/capitalization-title.*)?$
          example: 'https://api.organizacao.com.br/open-insurance/products-services/v1/capitalization-title'
        next:
          type: string
          description: URL da próxima página de registros
          pattern: ^(https:\/\/)(.*?)(\/open-insurance\/products-services\/v\d+)(\/capitalization-title.*)?$
          example: 'https://api.organizacao.com.br/open-insurance/products-services/v1/capitalization-title'
        last:
          type: string
          description: URL da última página de registros
          pattern: ^(https:\/\/)(.*?)(\/open-insurance\/products-services\/v\d+)(\/capitalization-title.*)?$
          example: 'https://api.organizacao.com.br/open-insurance/products-services/v1/capitalization-title'

    Meta:
      type: object
      properties:
        totalRecords:
          type: integer
          description: Total de registros encontrados
          example: 10
        totalPages:
          type: integer
          description: Total de páginas para os registros encontrados
          example: 1
      required:
        - totalRecords
        - totalPages

    ResponseError:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          minItems: 1
          maxItems: 13
          items:
            type: object
            required:
              - code
              - title
              - detail
              - requestDateTime
            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
              requestDateTime:
                description: 'Data e hora da consulta, conforme especificação RFC-3339, formato UTC.'
                type: string
                pattern: '[\w\W\s]*'
                maxLength: 2048
                format: date-time
                example: '2021-08-20T08:30:00Z'
            additionalProperties: false
        meta:
          $ref: '#/components/schemas/Meta'
      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
    pageSize:
      name: page-size
      in: query
      description: Quantidade total de registros por páginas.
      schema:
        type: integer
        default: 10
        minimum: 1
    cnpjNumber:
      name: cnpjNumber
      in: path
      description: Número de CNPJ.
      required: true
      schema:
        type: string
    cache-Control:
      name: cache-control
      in: header
      description: Controle de cache para evitar que informações confidenciais sejam armazenadas em cache.
      required: true
      schema:
        type: string
        pattern: '[\w\W\s]*'
    content-Security-Policy:
      name: Content-Security-Policy
      in: header
      description: Campo para proteção contra ataques clickjack do estilo - drag and drop.
      schema:
        type: string
        pattern: '[\w\W\s]*'
    content-Type:
      name: content-Type
      in: header
      description: Especificar o tipo de conteúdo da resposta.
      schema:
        type: string
        pattern: '[\w\W\s]*'
    strict-Transport-Security:
      name: Strict-Transport-Security
      in: header
      description: Campo para exigir conexões por HTTPS e proteger contra certificados falsificados.
      schema:
        type: string
        pattern:  '[\w\W\s]*'
    x-Content-Type-Options:
      name: X-Content-Type-Options
      in: header
      description: Campo para evitar que navegadores executem a detecção de MIME e interpretem respostas como HTML de forma inadequada.
      schema:
        type: string
        pattern: '[\w\W\s]*'
    x-Frame-Options:
      name: X-Frame-Options
      in: header
      description: Campo indica se o navegador deve ou não renderizar um frame.
      schema:
        type: string
        pattern: '[\w\W\s]*'
    x-v:
      name: x-v
      in: header
      description: |
        Versão do endpoint da API requisitado pelo cliente. O titular dos dados deve 
        responder com a versão mais alta suportada entre x-min-v e x-v. Se o valor de 
        x-min-v for igual ou maior que o valor de x-v, o cabeçalho x-min-v deve ser 
        tratado como ausente. Se todas as versões solicitadas não forem suportadas, 
        o titular dos dados deve responder com o código de status 406 Not Acceptable.
      required: false
      schema:
        type: string
      example: '2.1.3'
    x-min-v:
      name: x-min-v
      in: header
      description: |
        Versão mínima do endpoint da API requisitado pelo cliente. O detentor dos dados 
        deve responder com a versão mais alta suportada entre x-min-v e x-v. Se todas as 
        versões solicitadas não forem suportadas, o titular dos dados deve responder com 
        um código de status 406 Not Acceptable.
      required: false
      schema:
        type: string
      example: '2.0.0'

  responses:
    UnprocessableEntity:
      description: 'O servidor entende o tipo de conteúdo da entidade da requisição, e a sintaxe da requisição esta correta, mas não foi possível processar as instruções presente.'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    NoContent:
      description: 'O recurso solicitado não existe ou não foi localizado.'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError' 
    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'
    Forbidden:
      description: O token tem escopo incorreto ou uma política de segurança foi violada
      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'
    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'
    NotAcceptable:
      description: A solicitação continha um cabeçalho Accept diferente dos tipos de mídia permitidos ou um conjunto de caracteres diferente de UTF-8
      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'
    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'
    Unauthorized:
      description: Cabeçalho de autenticação ausente/inválido ou token inválido
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'