openapi: 3.0.0 info: title: API Capitalization-bonds - Open Finance Brasil description: | As APIs descritas neste documento é referente a API de Capitalização da fase OpenInsurance do Open Finance Brasil. version: 1.0.0-rc1.0 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-capitalization/v1' description: Servidor de Produção - url: 'https://apih.banco.com.br/open-banking/opendata-capitalization/v1' description: Servidor de Homologação tags: - name: Capitalization Bonds description: Operações para consulta das informações de Titulos de Capitalização paths: /bonds: get: tags: - Capitalization Bonds summary: Conjunto de informações dos Títulos de Capitalização de uma instituição operationId: capitalizationBondsGetProducts description: Método para obter a lista de todos os títulos de Capitalização de uma instituição parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/pageSize' responses: '200': $ref: '#/components/responses/OKResponseCapitalizationBondsProductsList' '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' components: schemas: CapitalizationBondsProductIdentificationData: type: object required: - participant - society - name - code - modality - costType - termsAndConditions - quotas - capitalizationPeriod - latePayment - contributionPayment - finalRedemptionRate - redemptionPercentageEndTerm - draws - additionalInfo - targetAudience properties: participant: $ref: '#/components/schemas/Participant' society: type: object description: Conjunto de informações relativas à seguradora do produto de open insurance required: - name - cnpjNumber properties: name: type: string description: Nome da Sociedade Seguradora. maxLength: 80 example: Society A1 cnpjNumber: $ref: '#/components/schemas/Participant/properties/cnpjNumber' additionalProperties: false 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: $ref: '#/components/schemas/EnumCapitalizationBondsProductModality' costType: $ref: '#/components/schemas/EnumCapitalizationBondsProductCostType' termsAndConditions: $ref: '#/components/schemas/TermsAndConditions' quotas: type: array description: Informações relativas às taxas da Quotas praticadas para cada Parcela minItems: 1 items: $ref: '#/components/schemas/CapitalizationBondsProductQuota' validity: type: integer format: int32 description: Período entre a data de início e a data final para constituição do capital a ser pago ao(s) titular(es) do direito de resgate. Prazo de vigência do título de capitalização em meses (Resolução CNSP 384/20). Em meses. maxLength: 3 example: 48 serieSize: type: integer description: 'Os títulos de capitalização que prevejam sorteio devem ser estruturados em séries, ou seja, em sequências ou em grupos de títulos submetidos às mesmas condições e características, à exceção do valor do pagamento.' maxLength: 10 example: 5000000 capitalizationPeriod: $ref: '#/components/schemas/CapitalizationBondsProductCapitalizationPeriod' latePayment: $ref: '#/components/schemas/LatePayment' contributionPayment: $ref: '#/components/schemas/ContributionPayment' redemptionPercentageEndTerm: type: string 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.' maxLength: 7 pattern: '^[0-1]\.\d{5}$' example: '1.00002' finalRedemptionRate: type: string description: Valor percentual (%) de resgate final permitido. pattern: '^[0-9]\.\d{2}$' maxLength: 4 example: '1.51' draws: type: array description: Informações relativas aos Sorteios minItems: 1 items: $ref: '#/components/schemas/CapitalizationBondsProductPrizeDraw' additionalInfo: type: string description: 'Campo aberto (possibilidade de incluir URL) Observação: As URLs são limitadas a 2048 caracteres mas, para o contexto do Open Insurance , foi adotado a metade deste tamanho (1024). tamanho p.ex. ‘https://ACME.exemplo/capitalizacao/tradicional/pdf/condicoes_gerais.' maxLength: 1024 example: 'https://ACME.exemplo/capitalizacao/tradicional/pdf/condicoes_gerais' minimumRequirementDetails: type: string description: | Campo aberto (possibilidade de incluir URL). Observação: As URLs são limitadas a 2048 caracteres mas, para o contexto do Open Insurance , foi adotado a metade deste tamanho (1024). tamanho. p.ex. ‘https://ACME.exemplo/capitalizacao/tradicional/pdf/condicoes_gerais.’ maxLength: 1024 example: 'https://ACME.exemplo/capitalizacao/tradicional/pdf/condicoes_gerais' targetAudience: type: string description: | A considerar os domínios abaixo: 1. Pessoa Natural 2. Pessoa Jurídica 3. Ambas (Pessoa Natural e Jurídica) maxLength: 23 enum: - PESSOA_NATURAL - PESSOA_JURIDICA - PESSOA_NATURAL_JURIDICA example: PESSOA_NATURAL additionalProperties: false Participant: 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.' maxLength: 80 example: Organização name: type: string description: Nome do participante do Open Finance. 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 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 EnumCapitalizationBondsProductModality: type: string description: | 1. Tradicional: A modalidade tradicional tem por objetivo restituir ao titular, ao final do prazo de vigência, no mínimo, o valor total das contribuições efetuadas pelo subscritor, desde que todas as contribuições previstas tenham sido realizadas nas datas programadas. (Res CNSP 384/20) 2. Instrumento de Garantia: A modalidade tem por objetivo propiciar que a provisão matemática para capitalização do título de capitalização seja utilizada para assegurar o cumprimento de obrigação assumida em contrato principal pelo titular perante terceiro. (Res CNSP 384/20) 3. Compra Programada: A modalidade compra programada garante o valor de resgate em moeda corrente nacional, sendo disponibilizada ao assim desejar e sem qualquer outro custo, pelo recebimento do bem e/ou serviço referenciado no subsidiado por acordos comerciais celebrados com indústrias, atacadistas, empresas comerciais ou prestadores de serviço. (Res CNSP 384/20) 4. Popular: A modalidade popular tem por objetivo propiciar a capitalização da contribuição e a participação do titular em sorteios, sem que haja devolução integral do valor pago. (Res CNSP 384/20) 5. Incentivo: A modalidade incentivo tem por objetivo a vinculação a um evento promocional de caráter comercial instituído pelo subscritor para alavancar a venda de seu(s) produto(s) ou serviços ou para fidelizar seus clientes. (Res CNSP 384/20) 6. Filantropia Premiável: A modalidade filantropia premiável é destinada ao subscritor interessado em contribuir com entidades beneficentes de assistências sociais, certificadas nos termos da legislação vigente, e participar de sorteio(s). (Res CNSP 384/20) minLength: 7 maxLength: 24 enum: - TRADICIONAL - INSTRUMENTO_GARANTIA - COMPRA_PROGRAMADA - POPULAR - INCENTIVO - FILANTROPIA_PREMIAVEL example: TRADICIONAL EnumCapitalizationBondsProductCostType: type: string description: | Pagamento efetuado ao subscritor à sociedade de capitalização para aquisição do título de capitalização, podendo ser única, periódica ou mensal. 1. Pagamento Único 2. Pagamento Mensal 3. Pagamento Periódico minLength: 15 maxLength: 19 enum: - PAGAMENTO_UNICO - PAGAMENTO_MENSAL - PAGAMENTO_PERIODICO example: PAGAMENTO_UNICO TermsAndConditions: type: object required: - susepProcessNumber - detail properties: susepProcessNumber: type: string description: 'Sequência numérica utilizada para consulta dos processos eletrônicos na SUSEP, com caracteres especiais, conforme campo de consulta no site da SUSEP (XXXXX.XXXXXX/XXXX-XX)
Observação: Mascaras da SUSEP – Serão permitidos todas as máscaras de Produtos. Limitar pelos códigos das Máscaras.' maxLength: 20 pattern: '^\d{5}\.\d{6}/\d{4}-\d{2}$' example: 15414.622222/2222-22 detail: type: string description: 'Representam as Condições Gerais, Condições Especiais e Condições ou Cláusulas Particulares de um mesmo produto. (Circular SUSEP 321/06). Campo aberto (possibilidade de incluir URL)' maxLength: 1024 example: 'https://openinsurance.com.br/aaa' additionalProperties: false CapitalizationBondsProductQuota: type: object required: - quota - capitalizationQuota - raffleQuota - chargingQuota properties: quota: type: number format: integer description: Número da parcela. maxLength: 3 example: 10 capitalizationQuota: type: string description: Percentual da contribuição destinado à constituição de capital referente ao direito de resgate. (Resolução CNSP 384/20) Em porcentagem(%). maxLength: 8 pattern: '^[0-1]\.\d{6}$' example: '0.000010' raffleQuota: type: string description: 'Percentual da contribuição destinado a custear os sorteios, se previstos no plano. (Resolução CNSP 384/20) Em porcentagem(%).' maxLength: 8 pattern: '^[0-1]\.\d{6}$' example: '0.000010' 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 relativas ao custeio da contemplação obrigatória e da distribuição de bônus. (Resolução CNSP 384/20) Em porcentagem(%).' maxLength: 8 pattern: '^[0-1]\.\d{6}$' example: '0.000010' additionalProperties: false CapitalizationBondsProductCapitalizationPeriod: type: object required: - interestRate - updateIndex - contributionAmount - earlyRedemptions - redemptionPercentageEndTerm - gracePeriodRedemption properties: interestRate: type: string pattern: '^[0-1]\.[\d]{6}$' description: '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.).' maxLength: 8 example: '0.251231' updateIndex: $ref: '#/components/schemas/CapitalizationBondsProductUpdateIndex' updateIndexAdditionalInfo: type: string description: 'Restrição: Campo obrigatório para complementar a informação quando selecionada a opção ''OUTROS''' maxLength: 200 example: '' contributionAmount: type: array items: $ref: '#/components/schemas/CapitalizationPeriodContributionAmount' minItems: 1 earlyRedemptions: minItems: 1 type: array items: type: object required: - quota - rate properties: quota: type: number format: integer description: Parcela relativa ao Resgate Antecipado maxLength: 3 example: 10 rate: type: number format: double description: Taxa relativa ao Resgate Antecipado maxLength: 9 example: 10.000001 additionalProperties: false redemptionPercentageEndTerm: type: string 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.' maxLength: 7 pattern: '^[0-1]\.\d{5}$' example: '1.00002' gracePeriodRedemption: type: number format: integer description: 'Intervalo de tempo mínimo entre contratação e resgate do direito, em meses.' maxLength: 3 example: 48 additionalProperties: false CapitalizationBondsProductUpdateIndex: type: string maxLength: 37 enum: - IPCA - IGPM - INPC - TR - INDICE_REMUNERACAO_DEPOSITOS_POUPANCA - OUTROS example: IPCA description: | Índice utilizado na atualização dos pagamentos mensais (para títulos com mais de 12 meses de vigência) (não aplicável a pagamento único). CapitalizationPeriodContributionAmount: type: object description: | Corresponde ao pagamento efetuado pelo subscritor à sociedade de capitalização para a aquisição do título de capitalização, podendo ser única, periódica ou mensal (Resolução CNSP 384/20). Valores em reais (R$). Esclarecimentos adicionais SUSEP. Na modalidade Tradicional, informar a faixa de valor mínimo e máximo em R$ de contribuição ao plano. Para as demais modalidades, informar a lista com os valores permitidos de contribuição ao plano. Em todas as situações indicar para qual periodicidade de pagamento se aplicam os valores: pagamento mensal, pagamento único ou periódico. required: - periodicity - minimum - maximum - allowedValue properties: periodicity: type: string description: | Intervalo de tempo regular previsto entre os sorteios. Conforme os domínios: 1. Único 2. Diário 3. Semanal 4. Quinzenal 5. Mensal 6. Bimestral 7. Trimestral 8. Quadrimestral 9. Semestral 10. Anual 11. Outros maxLength: 13 enum: - UNICO - DIARIO - SEMANAL - QUINZENAL - MENSAL - BIMESTRAL - TRIMESTRAL - QUADRIMESTRAL - SEMESTRAL - ANUAL - OUTROS example: UNICO periodicityAdditionalInfo: type: string description: 'Restrição: Campo obrigatório para complementar a informação quando selecionada a opção ''OUTROS''' maxLength: 200 example: '' minimum: type: string pattern: '^\d{1,16}\.\d{2,4}$' description: | Condicional: Quando modalidade for igual 'TRADICIONAL' Valor mínimo correspondente ao pagamento efetuado pelo subscritor à sociedade de capitalização. maxLength: 21 example: '1.2222' maximum: type: string pattern: '^\d{1,16}\.\d{2,4}$' description: | Condicional: Quando modalidade for igual 'TRADICIONAL' Valor máximo correspondente ao pagamento efetuado pelo subscritor à sociedade de capitalização. maxLength: 21 example: '1.2222' allowedValue: type: number format: double description: | Condicional: Quando modalidade for diferente de 'TRADICIONAL' Lista com os valores permitidos de contribuição ao plano. maxLength: 8 example: 5000 additionalProperties: false LatePayment: type: object required: - suspensionMonths - periodExtensionOption properties: suspensionMonths: type: number description: 'Conforme manual SUSEP: 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).' maxLength: 3 example: 10 periodExtensionOption: type: boolean description: | Alteração do prazo de vigência original, pela suspensão (não aplicável a pagamento único). A considerar os seguintes domínios: 1. true 2. false example: true additionalProperties: false ContributionPayment: type: object required: - paymentMethod - updateIndex properties: paymentMethod: $ref: '#/components/schemas/CapitalizationBondsProductPaymentMethod' paymentMethodAdditionalInfo: type: string description: 'Restrição: Campo obrigatório para complementar a informação quando selecionada a opção ''OUTROS''' maxLength: 200 example: '' updateIndex: $ref: '#/components/schemas/CapitalizationBondsProductUpdateIndex' updateIndexAdditionalInfo: type: string description: 'Restrição: Campo obrigatório para complementar a informação quando selecionada a opção ''OUTROS''' maxLength: 200 example: '' additionalProperties: false CapitalizationBondsProductPaymentMethod: type: string maxLength: 27 enum: - CARTAO_CREDITO - CARTAO_DEBITO - DEBITO_CONTA_CORRENTE - DEBITO_CONTA_POUPANCA - BOLETO_BANCARIO - PIX - CONSIGNACAO_FOLHA_PAGAMENTO - PAGAMENTO_PONTOS - OUTROS example: CARTAO_CREDITO description: | Meio de Pagamento utilizado para pagamento da contribuição. A considerar os domínios abaixo: 1. Cartão de Crédito 2. Cartão de Débito 3. Débito em conta corrente 4. Débito em conta poupança 5. Boleto bancário 6. PIX 7. Consignação em Folha de Pagamento 8. Pontos de Programas de Benefício 9. Outros CapitalizationBondsProductPrizeDraw: type: object required: - timeInterval - quantity - prizeMultiplier - earlySettlementRaffle - mandatoryContemplation - minimumContemplationProbability properties: timeInterval: type: string description: | Intervalo de tempo regular previsto entre os sorteios. Conforme os domínios: - UNICO - DIÁRIO - SEMANAL - QUINZENAL - MENSAL - BIMESTRAL - TRIMESTRAL - QUADRIMESTRAL - SEMESTRAL - ANUAL - OUTROS maxLength: 13 enum: - UNICO - DIÁRIO - SEMANAL - QUINZENAL - MENSAL - BIMESTRAL - TRIMESTRAL - QUADRIMESTRAL - SEMESTRAL - ANUAL - OUTROS example: UNICO timeIntervalAdditionalInfo: type: string description: 'Restrição: Campo obrigatório para complementar a informação quando selecionada a opção ''OUTROS''' maxLength: 200 example: '5' quantity: type: number format: integer description: Número da quantidade de sorteios previstos ao longo da vigência. maxLength: 5 example: 10000 prizeMultiplier: type: number format: integer description: 'Valor dos sorteios representado por múltiplo do valor de contribuição. Por exemplo: 5 vezes valor da contribuição' maxLength: 6 example: 5 earlySettlementRaffle: description: | Modelo de sorteio que acarreta, ao título contemplado, o seu resgate total obrigatório (Resolução Normativa 384/20). Conforme os domínios: 1. true 2. false type: boolean example: true mandatoryContemplation: type: boolean description: | 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. Conforme os domínios: 1. true 2. false example: true ruleDescription: type: string description: 'Campo aberto para complementar a regra dos sorteios do produto, a ser feita para cada participante.' maxLength: 200 example: Sorteios próprios às terças-feiras Toda quarta-feira sorteios através da loteria federal. minimumContemplationProbability: type: string pattern: '^[0-1]\.\d{6}$' description: 'Número representativo da probabilidade mínima de contemplação nos sorteios, em porcentagem (%).' maxLength: 8 example: '0.000002' additionalProperties: false Links: type: object description: Referências para outros recusos da API requisitada. required: - self properties: self: type: string format: uri maxLength: 2000 description: URI completo que gerou a resposta atual. example: 'https://api.banco.com.br/open-banking/api/v1/resource' pattern: '^(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$' first: type: string format: uri 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' pattern: '^(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$' prev: type: string format: uri 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' pattern: '^(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$' next: type: string format: uri 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' pattern: '^(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$' last: type: string format: uri 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' pattern: '^(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$' 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 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: OKResponseCapitalizationBondsProductsList: description: Dados de título(s) de capitalização obtidos com sucesso. content: application/json: schema: type: object required: - data - links - meta properties: data: type: array description: Conjunto de informações do Título de Capitalização items: $ref: '#/components/schemas/CapitalizationBondsProductIdentificationData' minItems: 1 links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/OpenDataMeta' additionalProperties: false 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/responses/NotFound/content/application~1json%3B%20charset%3Dutf-8/schema' InternalServerError: description: Ocorreu um erro no gateway da API ou no microsserviço content: application/json; charset=utf-8: schema: $ref: '#/components/responses/NotFound/content/application~1json%3B%20charset%3Dutf-8/schema' MethodNotAllowed: description: O consumidor tentou acessar o recurso com um método não suportado content: application/json; charset=utf-8: schema: $ref: '#/components/responses/NotFound/content/application~1json%3B%20charset%3Dutf-8/schema' NotFound: description: O recurso solicitado não existe ou não foi implementado 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 additionalProperties: false meta: $ref: '#/components/schemas/OpenDataMeta' additionalProperties: false 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/responses/NotFound/content/application~1json%3B%20charset%3Dutf-8/schema'