openapi: 3.0.0 info: title: API Consents - Open Finance Brasil description: | API que trata da criação, consulta, renovação e revogação de consentimentos para o Open Finance Brasil Dados cadastrais e transacionais - customer-data. Não possui segregação entre pessoa natural e pessoa jurídica. # Orientações importantes A API Consents trata exclusivamente dos consentimentos para Dados Cadastrais e Transacionais do Open Finance Brasil. - A API consents é composta de endpoints que permitem: - Pedido de criação do consentimento pela receptora: `POST /consents` - Devolução do pedido de criação pela transmissora: `GET /consents/{consentId}` - Pedido de renovação de consentimento do cliente pela receptora: `POST /consents/{consentId}/extends` - Devolução de lista com histórico de renovações efetuadas: `GET /consents/{consentId}/extensions` - Pedido de revogação do consentimento: `DELETE /consents/{consentId}` - Recomenda-se fortemente a leitura da seção [Orientações - [DC] Consentimento](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/219480491) para maiores detalhes, regras e restrições referente aos endpoints da API Consents - As informações da instituição receptora não trafegam na API Consents – a autenticação da receptora se dá através do [DCR](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/17378307/Dynamic+Client+Registration). - Na chamada para a criação, consulta e revogação do consentimento deve-se utilizar um token gerado via `client_credentials`. Na chamada para renovação do consentimento deve-se utilizar um token gerado via `authorization_code`. - Após o `POST` de criação do consentimento, o `STATUS` devolvido na resposta deverá ser `AWAITING_AUTHORISATION`. - O `STATUS` será alterado para `AUTHORISED` somente após autenticação e confirmação por parte do usuário na instituição transmissora dos dados. - Caso não haja confirmação por parte do usuário na transmissora, o status do consentimento deve ser alterado de `AWAITING_AUTHORISATION` para `REJECTED` após 60 minutos. - Todas as datas trafegadas nesta API seguem o padrão da [RFC3339](https://tools.ietf.org/html/rfc3339) e formato "zulu". - A descrição do fluxo de consentimento encontra-se disponível no [Portal do desenvolvedor](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/17369300/Dados+Cadastrais+e+Transacionais#Fluxo-b%C3%A1sico-de-consentimento). - O arquivo com o mapeamento completo entre `Roles`, `scopes` e `permissions` está disponibilizado no Portal do desenvolvedor, no mesmo item acima - descrição do fluxo de consentimento. - A receptora deve enviar obrigatoriamente, no pedido de criação de consentimento, todas as permissions dos agrupamentos de dados as quais ela deseja consentimento, conforme tabela abaixo: ``` |-------|----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | ROLE | CATEGORIA DE DADOS | AGRUPAMENTO | PERMISSIONS | SCOPE OAUTH 2.0 | |-------|----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ | customers | | | Cadastro | Dados Cadastrais PF |----------------------------------------------------------| | | | | | RESOURCES_READ | resources | | |----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | CUSTOMERS_PERSONAL_ADITTIONALINFO_READ | customers | | | Cadastro | Informações complementares PF |----------------------------------------------------------| | | | | | RESOURCES_READ | resources | | DADOS |----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ | customers | | | Cadastro | Dados Cadastrais PJ |----------------------------------------------------------| | | | | | RESOURCES_READ | resources | | |----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | CUSTOMERS_BUSINESS_ADITTIONALINFO_READ | customers | | | Cadastro | Informações complementares PJ |----------------------------------------------------------| | | | | | RESOURCES_READ | resources | |-------|----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | ACCOUNTS_READ | | | | | |----------------------------------------------------------| accounts | | | Contas | Saldos | ACCOUNTS_BALANCES_READ | | | | | |----------------------------------------------------------| resources | | | | | RESOURCES_READ | | | |----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | ACCOUNTS_READ | | | | | |----------------------------------------------------------| accounts | | DADOS | Contas | Limites | ACCOUNTS_OVERDRAFT_LIMITS_READ | | | | | |----------------------------------------------------------| resources | | | | | RESOURCES_READ | | | |----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | ACCOUNTS_READ | | | | | |----------------------------------------------------------| accounts | | | Contas | Extratos | ACCOUNTS_TRANSACTIONS_READ | | | | | |----------------------------------------------------------| resources | | | | | RESOURCES_READ | | |-------|----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | CREDIT_CARDS_ACCOUNTS_READ | | | | | |----------------------------------------------------------| credit-cards-accounts | | | Cartão de Crédito | Limites | CREDIT_CARDS_ACCOUNTS_LIMITS_READ | | | | | |----------------------------------------------------------| resources | | | | | RESOURCES_READ | | | |----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | CREDIT_CARDS_ACCOUNTS_READ | | | | | |----------------------------------------------------------| credit-cards-accounts | | | Cartão de Crédito | Transações | CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ | | | DADOS | | |----------------------------------------------------------| resources | | | | | RESOURCES_READ | | | |----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | CREDIT_CARDS_ACCOUNTS_READ | | | | | |----------------------------------------------------------| | | | | | CREDIT_CARDS_ACCOUNTS_BILLS_READ | credit-cards-accounts | | | Cartão de Crédito | Faturas |----------------------------------------------------------| | | | | | CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ | resources | | | | |----------------------------------------------------------| | | | | | RESOURCES_READ | | |-------|----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | LOANS_READ | | | | | |----------------------------------------------------------| | | | | | LOANS_WARRANTIES_READ | | | | | |----------------------------------------------------------| | | | | | LOANS_SCHEDULED_INSTALMENTS_READ | | | | | |----------------------------------------------------------| | | | | | LOANS_PAYMENTS_READ | | | | | |----------------------------------------------------------| | | | | | FINANCINGS_READ | | | | | |----------------------------------------------------------| | | | | | FINANCINGS_WARRANTIES_READ | | | | | |----------------------------------------------------------| | | | | | FINANCINGS_SCHEDULED_INSTALMENTS_READ | loans | | | | |----------------------------------------------------------| | | | | | FINANCINGS_PAYMENTS_READ | financings | | | | |----------------------------------------------------------| | | DADOS | Operações de Crédito | Dados do Contrato | UNARRANGED_ACCOUNTS_OVERDRAFT_READ | unarranged-accounts-overdraft | | | | |----------------------------------------------------------| | | | | | UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ | invoice-financings | | | | |----------------------------------------------------------| | | | | | UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ | resources | | | | |----------------------------------------------------------| | | | | | UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ | | | | | |----------------------------------------------------------| | | | | | INVOICE_FINANCINGS_READ | | | | | |----------------------------------------------------------| | | | | | INVOICE_FINANCINGS_WARRANTIES_READ | | | | | |----------------------------------------------------------| | | | | | INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ | | | | | |----------------------------------------------------------| | | | | | INVOICE_FINANCINGS_PAYMENTS_READ | | | | | |----------------------------------------------------------| | | | | | RESOURCES_READ | | |-------|----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | BANK_FIXED_INCOMES_READ | bank-fixed-incomes | | | | |----------------------------------------------------------| | | | | | CREDIT_FIXED_INCOMES_READ | credit-fixed-incomes | | | | |----------------------------------------------------------| | | DADOS | Investimento | Dados da Operação | FUNDS_READ | variable-incomes | | | | |----------------------------------------------------------| | | | | | VARIABLE_INCOMES_READ | treasure-titles | | | | |----------------------------------------------------------| | | | | | TREASURE_TITLES_READ | funds | | | | |----------------------------------------------------------| | | | | | RESOURCES_READ | resources | |-------|----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| | | | | EXCHANGES_READ | | | DADOS | Câmbio | Dados da Operação |----------------------------------------------------------| exchanges | | | | | RESOURCES_READ | | |-------|----------------------|-------------------------------|----------------------------------------------------------|-------------------------------| ``` - A instituição transmissora deve validar o preenchimento correto dos agrupamentos acima no momento da geração do consentimento. - Caso a instiuição receptora envie permissões não existentes nos agrupamentos especificados na tabela, a transmissora deve rejeitar o pedido da receptora dando retorno HTTP Status Code 400. - A transmissora deve retornar, da lista de permissions requisitadas, apenas o subconjunto de permissions por ela suportada, removendo da lista as permissions de produtos não suportados e retornando HTTP Status Code 201. A única exceção a este comportamento são os casos de produtos agrupados, como Operações de Crédito, Investimentos e Câmbio, para os quais todas as permissões do agrupamento devem ser mantidas. Caso não restem permissões funcionais, a instituição transmissora deve retornar o erro HTTP Code "422 Unprocessable Entity". - A renovação de consentimento não pode ser efetuada em situações determinadas. É esperado status 401 ou 403 para situações em que o erro for tratado na camada de segurança. Para erros tratados em camada de negócio, a transmissora deve retornar 422 conforme mensagens especificadas na página [Orientações – [DC] Consentimento](https://openfinancebrasil.atlassian.net/wiki/spaces/DraftOF/pages/232915037) - Caso o método `DELETE` seja chamado para um consentimento que já se encontra no `STATUS REJECTED` deve se retornar o STATUS CODE 422. - Pedidos de renovação de consentimento somente podem alterar a data de validade (conforme as regras definidas em [Orientações – [DC] Consentimento](https://openfinancebrasil.atlassian.net/wiki/spaces/DraftOF/pages/232915037)) e a finalidade do consentimento, e aplica-se somente a consentimentos ativos (status `AUTHORISED`). - No caso de criação ou renovação de consentimentos com prazo indeterminado, a receptora não deve enviar o atributo expirationDateTime. Para prazos determinados o campo deve ser enviado. - A renovação de consentimento (`POST /consents/{consentId}/extends`) deve ser possível por apenas um cliente logado. Isso implica que qualquer usuário (`loggedUser`) com permissão para o consentimento Pessoa Jurídica deve ser capaz de finalizar o fluxo de renovação sem redirecionamento. Para consentimentos Pessoa Natural apenas o `loggedUser` criador do consentimento consegue renovar sem redirecionamento. version: 3.2.0 license: name: Apache 2.0 url: 'http://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/consents/v3' description: Servidor de Produção - url: 'https://apih.banco.com.br/open-banking/consents/v3' description: Servidor de Homologação tags: - name: Consents description: 'Operações para criação, consulta, renovação e revogação do consentimento dado pelo cliente.' paths: /consents: post: tags: - Consents summary: Criar novo pedido de consentimento. operationId: consentsPostConsents description: Método para a criação de um novo consentimento. parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddress' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgent' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateConsent' description: Payload para criação do consentimento. required: true responses: '201': $ref: '#/components/responses/201ConsentsCreated' '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' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '504': $ref: '#/components/responses/GatewayTimeout' '529': $ref: '#/components/responses/SiteIsOverloaded' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OAuth2Security: - consents '/consents/{consentId}': get: tags: - Consents summary: Obter detalhes do consentimento identificado por consentId. operationId: consentsGetConsentsConsentId description: Método para obter detalhes do consentimento identificado por consentId. parameters: - $ref: '#/components/parameters/ConsentId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddress' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgent' responses: '200': $ref: '#/components/responses/200ConsentsConsentIdRead' '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' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '504': $ref: '#/components/responses/GatewayTimeout' '529': $ref: '#/components/responses/SiteIsOverloaded' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OAuth2Security: - consents delete: tags: - Consents summary: Deletar / Revogar o consentimento identificado por consentId. operationId: consentsDeleteConsentsConsentId description: Método para deletar / revogar o consentimento identificado por consentId. parameters: - $ref: '#/components/parameters/ConsentId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddress' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgent' responses: '204': $ref: '#/components/responses/204ConsentsConsentIdDeleted' '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/UnprocessableEntityDelete' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '504': $ref: '#/components/responses/GatewayTimeout' '529': $ref: '#/components/responses/SiteIsOverloaded' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OAuth2Security: - consents '/consents/{consentId}/extensions': get: tags: - Consents summary: Obter detalhes de extensões feitas no consentimento identificado por consentId. operationId: consentsGetConsentsConsentIdExtensions description: | Método para obter histórico de extensões de consentimento identificado por consentId. IMPORTANTE: A lista do payload de resposta deve ser entregue em ordem decrescente pela data de requisição (`data[].requestDateTime`). Dessa forma, o primeiro item da lista apresentará a mesma data de expiração do consentimento vigente, pois foi a última renovação feita. parameters: - $ref: '#/components/parameters/ConsentId' - $ref: '#/components/parameters/AuthorizationExtensions' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddress' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgent' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': $ref: '#/components/responses/200ConsentsConsentIdReadExtensions' '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' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '504': $ref: '#/components/responses/GatewayTimeout' '529': $ref: '#/components/responses/SiteIsOverloaded' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OAuth2Security: - consents '/consents/{consentId}/extends': post: tags: - Consents summary: Renovar consentimento identificado por consentId. operationId: consentsPostConsentsConsentIdExtends description: Método utilizado para renovação de consentimento do cliente. O consentimento só pode ser renovado caso esteja ativo (status AUTHORISED) e tenha alçada simples de aprovação (não dependa de múltiplos aprovadores). A alteração de data efetuada pela renovação deve ser refletida também na consulta do método _GET/consents/{consentId}_. parameters: - $ref: '#/components/parameters/ConsentId' - $ref: '#/components/parameters/AuthorizationExtensions' - $ref: '#/components/parameters/xFapiAuthDate' - $ref: '#/components/parameters/xFapiCustomerIpAddressExtensions' - $ref: '#/components/parameters/xFapiInteractionId' - $ref: '#/components/parameters/xCustomerUserAgentExtensions' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateConsentExtensions' description: Payload para renovação do consentimento. required: true responses: '201': $ref: '#/components/responses/201ConsentsCreatedExtensions' '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' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/UnprocessableEntityConsents' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '504': $ref: '#/components/responses/GatewayTimeout' '529': $ref: '#/components/responses/SiteIsOverloaded' default: description: Erro inesperado. content: application/json: schema: $ref: '#/components/schemas/ResponseError' security: - OAuth2AuthorizationCode: - openid - 'consent:consentId' components: schemas: 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@:%_\+.~#?&\/\/=]*)$' LinksConsents: 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@:%_\+.~#?&\/\/=]*)$' 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' MetaExtensions: 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' MetaError: 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' CreateConsent: type: object required: - data properties: data: type: object required: - permissions - loggedUser x-regulatory-required: - permissions - expirationDateTime properties: loggedUser: $ref: '#/components/schemas/LoggedUser' businessEntity: $ref: '#/components/schemas/BusinessEntity' permissions: type: array items: description: 'Especifica os tipos de permissões de acesso às APIs no escopo do Open Finance Brasil - Dados cadastrais e transacionais, de acordo com os blocos de consentimento fornecidos pelo usuário e necessários ao acesso a cada endpoint das APIs. Esse array não deve ter duplicidade de itens.' type: string enum: - ACCOUNTS_READ - ACCOUNTS_BALANCES_READ - ACCOUNTS_TRANSACTIONS_READ - ACCOUNTS_OVERDRAFT_LIMITS_READ - CREDIT_CARDS_ACCOUNTS_READ - CREDIT_CARDS_ACCOUNTS_BILLS_READ - CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ - CREDIT_CARDS_ACCOUNTS_LIMITS_READ - CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ - CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ - CUSTOMERS_PERSONAL_ADITTIONALINFO_READ - CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ - CUSTOMERS_BUSINESS_ADITTIONALINFO_READ - FINANCINGS_READ - FINANCINGS_SCHEDULED_INSTALMENTS_READ - FINANCINGS_PAYMENTS_READ - FINANCINGS_WARRANTIES_READ - INVOICE_FINANCINGS_READ - INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ - INVOICE_FINANCINGS_PAYMENTS_READ - INVOICE_FINANCINGS_WARRANTIES_READ - LOANS_READ - LOANS_SCHEDULED_INSTALMENTS_READ - LOANS_PAYMENTS_READ - LOANS_WARRANTIES_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ - RESOURCES_READ - BANK_FIXED_INCOMES_READ - CREDIT_FIXED_INCOMES_READ - FUNDS_READ - VARIABLE_INCOMES_READ - TREASURE_TITLES_READ - EXCHANGES_READ minItems: 1 example: - ACCOUNTS_READ - ACCOUNTS_OVERDRAFT_LIMITS_READ - RESOURCES_READ expirationDateTime: description: | Data e hora de expiração da permissão. Reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC (UTC time format). [Restrição] De preenchimento obrigatório nos casos em que houver validade determinada. Em casos de consentimento com prazo indeterminado o campo não deve ser enviado. Quando preenchido, o valor do campo não pode ultrapassar 12 meses. type: string maxLength: 20 format: date-time 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$' example: '2021-05-21T08:30:00Z' CreateConsentExtensions: type: object required: - data properties: data: type: object required: - loggedUser properties: expirationDateTime: description: | Data e hora de expiração da permissão. Reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC (UTC time format). [Restrição] De preenchimento obrigatório nos casos em que houver validade determinada. Em casos de consentimento com prazo indeterminado o campo não deve ser enviado. Quando preenchido, o valor do campo não pode ultrapassar 12 meses. type: string format: date-time 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: '2021-05-21T08:30:00Z' loggedUser: $ref: '#/components/schemas/LoggedUserExtensions' businessEntity: $ref: '#/components/schemas/BusinessEntityExtensions' EnumRejectedBy: type: string description: | Informar usuário responsável pela rejeição. 1. USER usuário 2. ASPSP instituição transmissora 3. TPP instituição receptora enum: - USER - ASPSP - TPP example: USER ResponseConsent: type: object required: - data properties: data: type: object required: - consentId - creationDateTime - status - statusUpdateDateTime - permissions x-regulatory-required: - permissions - expirationDateTime properties: consentId: description: | O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name. Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/rfc8141) é um Uniform Resource Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN seja um identificador de recurso persistente e independente da localização. Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos: - o namespace(urn) - o identificador associado ao namespace da instituição transnmissora (bancoex) - o identificador específico dentro do namespace (C1DD33123). Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://tools.ietf.org/html/rfc8141). type: string pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$' maxLength: 256 example: 'urn:bancoex:C1DD33123' creationDateTime: description: 'Data e hora em que o recurso foi criado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).' type: string format: date-time 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$' example: '2021-05-21T08:30:00Z' maxLength: 20 status: description: Estado atual do consentimento cadastrado. type: string enum: - AUTHORISED - AWAITING_AUTHORISATION - REJECTED example: AWAITING_AUTHORISATION statusUpdateDateTime: description: 'Data e hora em que o recurso foi atualizado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).' type: string format: date-time 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$' example: '2021-05-21T08:30:00Z' maxLength: 20 permissions: type: array minItems: 1 description: 'Especifica os tipos de permissões de acesso às APIs no escopo do Open Finance Brasil - Dados cadastrais e transacionais, de acordo com os blocos de consentimento fornecidos pelo usuário e necessários ao acesso a cada endpoint das APIs. Esse array não deve ter duplicidade de itens.' items: type: string enum: - ACCOUNTS_READ - ACCOUNTS_BALANCES_READ - ACCOUNTS_TRANSACTIONS_READ - ACCOUNTS_OVERDRAFT_LIMITS_READ - CREDIT_CARDS_ACCOUNTS_READ - CREDIT_CARDS_ACCOUNTS_BILLS_READ - CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ - CREDIT_CARDS_ACCOUNTS_LIMITS_READ - CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ - CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ - CUSTOMERS_PERSONAL_ADITTIONALINFO_READ - CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ - CUSTOMERS_BUSINESS_ADITTIONALINFO_READ - FINANCINGS_READ - FINANCINGS_SCHEDULED_INSTALMENTS_READ - FINANCINGS_PAYMENTS_READ - FINANCINGS_WARRANTIES_READ - INVOICE_FINANCINGS_READ - INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ - INVOICE_FINANCINGS_PAYMENTS_READ - INVOICE_FINANCINGS_WARRANTIES_READ - LOANS_READ - LOANS_SCHEDULED_INSTALMENTS_READ - LOANS_PAYMENTS_READ - LOANS_WARRANTIES_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ - RESOURCES_READ - BANK_FIXED_INCOMES_READ - CREDIT_FIXED_INCOMES_READ - FUNDS_READ - VARIABLE_INCOMES_READ - TREASURE_TITLES_READ - EXCHANGES_READ example: - ACCOUNTS_READ - ACCOUNTS_OVERDRAFT_LIMITS_READ - RESOURCES_READ expirationDateTime: description: | Data e hora de expiração da permissão. Reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC (UTC time format). [Restrição] De preenchimento obrigatório nos casos em que houver validade determinada. Em casos de consentimento com prazo indeterminado o campo não deve ser enviado. Quando preenchido, o valor do campo não pode ultrapassar 12 meses. type: string format: date-time 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$' example: '2021-05-21T08:30:00Z' maxLength: 20 links: $ref: '#/components/schemas/LinksConsents' meta: $ref: '#/components/schemas/Meta' ResponseConsentExtensions: type: object required: - data properties: data: type: object required: - consentId - creationDateTime - status - statusUpdateDateTime - permissions properties: consentId: description: | O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name. Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/rfc8141) é um Uniform Resource Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN seja um identificador de recurso persistente e independente da localização. Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos: - o namespace(urn) - o identificador associado ao namespace da instituição transnmissora (bancoex) - o identificador específico dentro do namespace (C1DD33123). Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://tools.ietf.org/html/rfc8141). type: string pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$' maxLength: 256 example: 'urn:bancoex:C1DD33123' creationDateTime: description: Data e hora em que o recurso foi criado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format). type: string format: date-time example: '2021-05-21T08:30:00Z' maxLength: 20 status: description: Estado atual do consentimento cadastrado. type: string enum: - AUTHORISED - AWAITING_AUTHORISATION - REJECTED example: AWAITING_AUTHORISATION statusUpdateDateTime: description: Data e hora em que o recurso foi atualizado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format). type: string format: date-time example: '2021-05-21T08:30:00Z' maxLength: 20 permissions: type: array minItems: 1 description: Especifica os tipos de permissões de acesso às APIs no escopo do Open Finance Brasil - Dados cadastrais e transacionais, de acordo com os blocos de consentimento fornecidos pelo usuário e necessários ao acesso a cada endpoint das APIs. Esse array não deve ter duplicidade de itens. items: type: string enum: - ACCOUNTS_READ - ACCOUNTS_BALANCES_READ - ACCOUNTS_TRANSACTIONS_READ - ACCOUNTS_OVERDRAFT_LIMITS_READ - CREDIT_CARDS_ACCOUNTS_READ - CREDIT_CARDS_ACCOUNTS_BILLS_READ - CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ - CREDIT_CARDS_ACCOUNTS_LIMITS_READ - CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ - CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ - CUSTOMERS_PERSONAL_ADITTIONALINFO_READ - CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ - CUSTOMERS_BUSINESS_ADITTIONALINFO_READ - FINANCINGS_READ - FINANCINGS_SCHEDULED_INSTALMENTS_READ - FINANCINGS_PAYMENTS_READ - FINANCINGS_WARRANTIES_READ - INVOICE_FINANCINGS_READ - INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ - INVOICE_FINANCINGS_PAYMENTS_READ - INVOICE_FINANCINGS_WARRANTIES_READ - LOANS_READ - LOANS_SCHEDULED_INSTALMENTS_READ - LOANS_PAYMENTS_READ - LOANS_WARRANTIES_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ - RESOURCES_READ - BANK_FIXED_INCOMES_READ - CREDIT_FIXED_INCOMES_READ - FUNDS_READ - VARIABLE_INCOMES_READ - TREASURE_TITLES_READ example: - ACCOUNTS_READ - ACCOUNTS_OVERDRAFT_LIMITS_READ - RESOURCES_READ expirationDateTime: description: | Data e hora de expiração da permissão. Reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC (UTC time format). [Restrição] De preenchimento obrigatório nos casos em que houver validade determinada. Em casos de consentimento com prazo indeterminado o campo não deve ser enviado. Quando preenchido, o valor do campo não pode ultrapassar 12 meses. type: string format: date-time example: '2021-05-21T08:30:00Z' maxLength: 20 links: $ref: '#/components/schemas/LinksConsents' meta: $ref: '#/components/schemas/Meta' ResponseConsentRead: type: object required: - data properties: data: type: object required: - consentId - creationDateTime - status - statusUpdateDateTime - permissions x-regulatory-required: - permissions - expirationDateTime​ properties: consentId: description: | O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name. Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/rfc8141) é um Uniform Resource Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN seja um identificador de recurso persistente e independente da localização. Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos: - o namespace(urn) - o identificador associado ao namespace da instituição transnmissora (bancoex) - o identificador específico dentro do namespace (C1DD33123). Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://tools.ietf.org/html/rfc8141). type: string pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$' maxLength: 256 example: 'urn:bancoex:C1DD33123' creationDateTime: description: 'Data e hora em que o recurso foi criado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).' type: string format: date-time 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$' example: '2021-05-21T08:30:00Z' maxLength: 20 status: description: Estado atual do consentimento cadastrado. type: string enum: - AUTHORISED - AWAITING_AUTHORISATION - REJECTED example: AWAITING_AUTHORISATION statusUpdateDateTime: description: 'Data e hora em que o recurso foi atualizado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).' type: string format: date-time 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$' example: '2021-05-21T08:30:00Z' maxLength: 20 permissions: type: array minItems: 1 description: 'Especifica os tipos de permissões de acesso às APIs no escopo do Open Finance Brasil - Dados cadastrais e transacionais, de acordo com os blocos de consentimento fornecidos pelo usuário e necessários ao acesso a cada endpoint das APIs. Esse array não deve ter duplicidade de itens.' items: type: string enum: - ACCOUNTS_READ - ACCOUNTS_BALANCES_READ - ACCOUNTS_TRANSACTIONS_READ - ACCOUNTS_OVERDRAFT_LIMITS_READ - CREDIT_CARDS_ACCOUNTS_READ - CREDIT_CARDS_ACCOUNTS_BILLS_READ - CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ - CREDIT_CARDS_ACCOUNTS_LIMITS_READ - CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ - CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ - CUSTOMERS_PERSONAL_ADITTIONALINFO_READ - CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ - CUSTOMERS_BUSINESS_ADITTIONALINFO_READ - FINANCINGS_READ - FINANCINGS_SCHEDULED_INSTALMENTS_READ - FINANCINGS_PAYMENTS_READ - FINANCINGS_WARRANTIES_READ - INVOICE_FINANCINGS_READ - INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ - INVOICE_FINANCINGS_PAYMENTS_READ - INVOICE_FINANCINGS_WARRANTIES_READ - LOANS_READ - LOANS_SCHEDULED_INSTALMENTS_READ - LOANS_PAYMENTS_READ - LOANS_WARRANTIES_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ - UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ - RESOURCES_READ - BANK_FIXED_INCOMES_READ - CREDIT_FIXED_INCOMES_READ - FUNDS_READ - VARIABLE_INCOMES_READ - TREASURE_TITLES_READ - EXCHANGES_READ example: - ACCOUNTS_READ - ACCOUNTS_OVERDRAFT_LIMITS_READ - RESOURCES_READ expirationDateTime: description: | Data e hora de expiração da permissão. Reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format). [Restrição] De preenchimento obrigatório nos casos em que houver validade determinada. Em casos de consentimento com prazo indeterminado o campo não deve ser preenchido. type: string format: date-time 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$' example: '2021-05-21T08:30:00Z' maxLength: 20 rejection: type: object description: Objeto a ser retornado caso o consentimento seja rejeitado. required: - rejectedBy - reason properties: rejectedBy: $ref: '#/components/schemas/EnumRejectedBy' reason: type: object description: Define a razão pela qual o consentimento foi rejeitado. required: - code properties: code: type: string description: | Define o código da razão pela qual o consentimento foi rejeitado. - CONSENT_EXPIRED – consentimento que ultrapassou o tempo limite para autorização. - CUSTOMER_MANUALLY_REJECTED – cliente efetuou a rejeição do consentimento manualmente através de interação nas instituições participantes. - CUSTOMER_MANUALLY_REVOKED – cliente efetuou a revogação após a autorização do consentimento. - CONSENT_MAX_DATE_REACHED – consentimento que ultrapassou o tempo limite de compartilhamento. - CONSENT_TECHNICAL_ISSUE – consentimento que foi rejeitado devido a um problema técnico que impossibilita seu uso pela instituição receptora, por exemplo: falha associada a troca do AuthCode pelo AccessToken, durante o processo de Hybrid Flow. - INTERNAL_SECURITY_REASON – consentimento que foi rejeitado devido as políticas de segurança aplicada pela instituição transmissora. enum: - CONSENT_EXPIRED - CUSTOMER_MANUALLY_REJECTED - CUSTOMER_MANUALLY_REVOKED - CONSENT_MAX_DATE_REACHED - CONSENT_TECHNICAL_ISSUE - INTERNAL_SECURITY_REASON example: CONSENT_EXPIRED additionalInformation: type: string description: Contém informações adicionais a critério da transmissora. maxLength: 140 pattern: '^(?!\s)[\w\W\s]*[^\s]$' example: Tempo de confirmação da múltipla alçada excedido. links: $ref: '#/components/schemas/LinksConsents' meta: $ref: '#/components/schemas/Meta' ResponseConsentReadExtensions: type: object required: - data properties: data: type: array minItems: 0 items: type: object required: - loggedUser - requestDateTime properties: expirationDateTime: description: | Data e hora de expiração da permissão. Reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format), utilizado apenas para consulta de alterações históricas de extensão do consentimento. [Restrição] De preenchimento obrigatório nos casos em que houver validade determinada. Em casos de consentimento com prazo indeterminada o campo não deve ser preenchido. type: string format: date-time 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: '2021-05-21T08:30:00Z' loggedUser: $ref: '#/components/schemas/LoggedUserExtensions' requestDateTime: description: Data e hora em que o recurso foi criado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format). type: string format: date-time example: '2021-05-21T08:30:00Z' maxLength: 20 previousExpirationDateTime: description: | Data e hora de expiração anteriores a renovação. Reflete a data limite anterior de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC (UTC time format). [Restrição] De preenchimento obrigatório nos casos em que houver validade determinada. Em casos de consentimento com prazo indeterminado, ou renovações feitas com a v2.2.0 em que não exista persistência dessa informação, o campo não deve ser preenchido. type: string format: date-time 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: '2023-10-18T18:30:00Z' xFapiCustomerIpAddress: description: | O endereço IP do usuário logado com o receptor que solicitou a renovação sem redirecionamento. [Restrição] De preenchimento obrigatório a partir da v3.0.0. Opcional para renovações feitas com a v2.2.0 quando não existir persistência dessa informação. type: string pattern: '^(?!\s)[\w\W\s]*[^\s]$' minLength: 1 maxLength: 100 example: '172.217.22.14' xCustomerUserAgent: description: | Indica o user-agent que o usuário utilizou quando solicitou a renovação sem redirecionamento. [Restrição] De preenchimento obrigatório a partir da v3.0.0. Opcional para renovações feitas com a v2.2.0 quando não existir persistência dessa informação. type: string pattern: '^(?!\s)[\w\W\s]*[^\s]$' minLength: 1 maxLength: 100 example: Mozilla/5.0 (iPhone14,6; U; CPU iPhone OS 15_4 like Mac OS X) links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/MetaExtensions' 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: $ref: '#/components/schemas/MetaError' ResponseErrorUnprocessableEntityDelete: type: object required: - errors properties: errors: type: array minItems: 1 maxItems: 13 items: type: object required: - code - title - detail properties: code: type: string enum: - CONSENTIMENTO_EM_STATUS_REJEITADO example: CONSENTIMENTO_EM_STATUS_REJEITADO description: | - CONSENTIMENTO_EM_STATUS_REJEITADO 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: $ref: '#/components/schemas/MetaError' ResponseErrorUnprocessableEntity: type: object required: - errors properties: errors: type: array minItems: 1 maxItems: 13 items: type: object required: - code - title - detail properties: code: type: string enum: - SEM_PERMISSOES_FUNCIONAIS_RESTANTES - INFORMACOES_PJ_NAO_INFORMADAS - PERMISSOES_PJ_INCORRETAS - PERMISSAO_PF_PJ_EM_CONJUNTO - COMBINACAO_PERMISSOES_INCORRETA - DATA_EXPIRACAO_INVALIDA - ERRO_NAO_MAPEADO example: SEM_PERMISSOES_FUNCIONAIS_RESTANTES description: | - SEM_PERMISSOES_FUNCIONAIS_RESTANTES - INFORMACOES_PJ_NAO_INFORMADAS - PERMISSOES_PJ_INCORRETAS - PERMISSAO_PF_PJ_EM_CONJUNTO - COMBINACAO_PERMISSOES_INCORRETA - DATA_EXPIRACAO_INVALIDA - ERRO_NAO_MAPEADO A opção “ERRO_NAO_MAPEADO” só deve ser utilizada caso não haja um code especifico mapeado para o erro. 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: $ref: '#/components/schemas/MetaError' 422ResponseErrorCreateConsent: type: object required: - errors properties: errors: type: array minItems: 1 maxItems: 3 items: type: object required: - code - title - detail properties: code: type: string enum: - DEPENDE_MULTIPLA_ALCADA - ESTADO_CONSENTIMENTO_INVALIDO - DATA_EXPIRACAO_INVALIDA - ERRO_NAO_MAPEADO example: DEPENDE_MULTIPLA_ALCADA description: | Códigos de erros previstos na durante o processo de extensão do consentimento: - DEPENDE_MULTIPLA_ALCADA: Necessário aprovação de múltipla alçada. - ESTADO_CONSENTIMENTO_INVALIDO: Estado inválido do consentimento. - DATA_EXPIRACAO_INVALIDA: Nova data para expiração do consentimento é inválida. - ERRO_NAO_MAPEADO: Utilizado quando não houver um code de erro definido. title: type: string maxLength: 255 pattern: '[\w\W\s]*' example: Necessário aprovação de múltipla alçada. description: | Título específico do erro reportado, de acordo com o código enviado: - DEPENDE_MULTIPLA_ALCADA: Necessário aprovação de múltipla alçada. - ESTADO_CONSENTIMENTO_INVALIDO: Estado inválido do consentimento. - DATA_EXPIRACAO_INVALIDA: Nova data para expiração do consentimento é inválida. - ERRO_NAO_MAPEADO: Utilizado quando não houver um code de erro definido. O texto deve deixar claro o motivo do erro ocorrido. detail: type: string maxLength: 2048 pattern: '[\w\W\s]*' example: O consentimento informado não pode ser renovado sem redirecionamento porque depende de múltipla alçada para aprovação. description: | Título específico do erro reportado, de acordo com o código enviado: - DEPENDE_MULTIPLA_ALCADA: O consentimento informado não pode ser renovado sem redirecionamento porque depende de múltipla alçada para aprovação. - ESTADO_CONSENTIMENTO_INVALIDO: O consentimento informado não pode ser renovado sem redirecionamento porque está em um estado que não permite a renovação. - DATA_EXPIRACAO_INVALIDA: O consentimento informado não pode ser renovado pois a nova data de expiração não segue a convenção do ecossistema. - ERRO_NAO_MAPEADO: Utilizado quando não houver um code de erro definido. O texto deve deixar claro o motivo do erro ocorrido. meta: $ref: '#/components/schemas/Meta' LoggedUser: type: object description: | Usuário (pessoa natural) que encontra-se logado na instituição receptora e que iniciará o processo de consentimento para compartilhamento de dados. É obrigatório que o número do documento utilizado seja um número válido e pertencente ao usuário logado. A transmissora pode utilizar algoritmos de validação de documento para garantir que se trata de um documento válido, como por exemplo: Cálculo de DV módulo 11 para o CPF. required: - document properties: document: $ref: '#/components/schemas/LoggedUserDocument' LoggedUserExtensions: type: object description: | Usuário (pessoa natural) que encontra-se logado na instituição receptora e que iniciará o processo de consentimento para compartilhamento de dados. Deve ser armazenado como novo usuário logado responsável pela renovação do consentimento atual. required: - document properties: document: $ref: '#/components/schemas/LoggedUserDocumentExtensions' LoggedUserDocument: type: object required: - identification - rel x-regulatory-required: - identification properties: identification: type: string maxLength: 11 description: Número do documento de identificação oficial do usuário. example: '11111111111' pattern: '^\d{11}$' rel: type: string maxLength: 3 description: Tipo do documento de identificação oficial do usuário. example: CPF pattern: '^[A-Z]{3}$' LoggedUserDocumentExtensions: type: object required: - identification - rel properties: identification: type: string maxLength: 11 description: Número do documento de identificação oficial do usuário. example: '11111111111' pattern: '^\d{11}$' rel: type: string maxLength: 3 description: Tipo do documento de identificação oficial do usuário. example: CPF pattern: '^[A-Z]{3}$' BusinessEntity: type: object description: | Titular, pessoa jurídica a quem se referem os dados que são objeto de compartilhamento. É obrigatório que o número do CNPJ utilizado seja um número válido. A transmissora pode utilizar algoritmos de validação de documento para garantir que se trata de um documento válido, como por exemplo: Cálculo de DV módulo 11 para o CNPJ. required: - document properties: document: $ref: '#/components/schemas/BusinessEntityDocument' BusinessEntityExtensions: type: object description: | Titular, pessoa jurídica a quem se referem os dados que são objeto de compartilhamento. Deve ser informado apenas para casos de consentimento pessoa jurídica. Não precisa ser armazenado separadamente. Para fins de renovação de consentimento, será utilizado apenas para verificação do consentimento vigente, pois é um atributo imutável. required: - document properties: document: $ref: '#/components/schemas/BusinessEntityDocumentExtensions' BusinessEntityDocument: type: object required: - identification - rel x-regulatory-required: - identification properties: identification: type: string maxLength: 14 description: Número do documento de identificação oficial do titular pessoa jurídica. example: '11111111111111' pattern: '^\d{14}$' rel: type: string maxLength: 4 description: Tipo do documento de identificação oficial do titular pessoa jurídica. example: CNPJ pattern: '^[A-Z]{4}$' BusinessEntityDocumentExtensions: type: object required: - identification - rel properties: identification: type: string maxLength: 14 description: Número do documento de identificação oficial do titular pessoa jurídica. example: '11111111111111' pattern: '^\d{14}$' rel: type: string maxLength: 4 description: Tipo do documento de identificação oficial do titular pessoa jurídica. example: CNPJ pattern: '^[A-Z]{4}$' parameters: ConsentId: name: consentId in: path description: | O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name. Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/rfc8141) é um Uniform Resource Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN seja um identificador de recurso persistente e independente da localização. Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos: - o namespace(urn) - o identificador associado ao namespace da instituição transnmissora (bancoex) - o identificador específico dentro do namespace (C1DD33123). Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://tools.ietf.org/html/rfc8141). required: true schema: type: string pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$' minLength: 6 maxLength: 256 Authorization: name: Authorization in: header description: Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado required: true schema: type: string pattern: '[\w\W\s]*' minLength: 1 maxLength: 2048 AuthorizationExtensions: name: Authorization in: header description: Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado required: true schema: type: string pattern: '[^\s][\w\W\s][^\s]*' minLength: 1 maxLength: 2048 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. A transmissora deve considerar entrada como 25, caso seja informado algum valor menor pela receptora. Enquanto houver mais que 25 registros a enviar, a transmissora deve considerar o mínimo por página como 25. Somente a última página retornada (ou primeira, no caso de página única) pode conter menos de 25 registros. Mais informações, acesse Especificações de APIs > Padrões > Paginação. schema: type: integer default: 25 minimum: 25 format: int32 maximum: 1000 xCustomerUserAgent: name: x-customer-user-agent in: header description: Indica o user-agent que o usuário utiliza. required: false schema: type: string pattern: '[\w\W\s]*' minLength: 1 maxLength: 100 xCustomerUserAgentExtensions: name: x-customer-user-agent in: header description: Indica o user-agent que o usuário utiliza. required: true schema: type: string pattern: '[\w\W\s]*' minLength: 1 maxLength: 100 xFapiAuthDate: name: x-fapi-auth-date in: header description: 'Data em que o usuário logou pela última vez com o receptor. Representada de acordo com a [RFC7231](https://tools.ietf.org/html/rfc7231).Exemplo: Sun, 10 Sep 2017 19:43:31 UTC' required: false schema: type: string pattern: '^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$' minLength: 29 maxLength: 29 xFapiCustomerIpAddress: name: x-fapi-customer-ip-address in: header description: O endereço IP do usuário se estiver atualmente logado com o receptor. required: false schema: type: string pattern: '[\w\W\s]*' minLength: 1 maxLength: 100 xFapiCustomerIpAddressExtensions: name: x-fapi-customer-ip-address in: header description: O endereço IP do usuário se estiver atualmente logado com o receptor. required: true schema: type: string pattern: '[\w\W\s]*' minLength: 1 maxLength: 100 xFapiInteractionId: name: x-fapi-interaction-id in: header description: Um UUID RFC4122 usado como um ID de correlação entre request e response. Campo de geração e envio obrigatório pela receptora (client) e o seu valor deve ser “espelhado” pela transmissora (server) no cabeçalho de resposta. Caso não seja recebido ou se for recebido um valor inválido, a transmissora deve gerar um x-fapi-interaction-id e retorná-lo na resposta com o HTTP Status Code 400. A receptora deve acatar o valor recebido da transmissora. required: true schema: type: string pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' minLength: 1 maxLength: 36 format: uuid example: d78fc4e5-37ca-4da3-adf2-9b082bf92280 securitySchemes: OAuth2Security: type: oauth2 flows: clientCredentials: tokenUrl: 'https://authserver.example/token' scopes: consents: Criação do consentimento. OAuth2AuthorizationCode: type: oauth2 description: Fluxo OAuthnecessário para que a receptora tenha acesso aos endpoints de consentimento na instituição transmissora. Requer o processo de redirecionamento e autenticação do usuário. flows: authorizationCode: authorizationUrl: 'https://authserver.example/code' tokenUrl: 'https://authserver.example/token' scopes: openid: Indica que a autorização está sendo realizada utilizando o protocolo definido pela openid. 'consent:consentId': Escopo contendo o identificador único do consentimento criado para compartilhamento de dados solicitada. responses: UnsupportedMediaType: description: O formato do payload não é um formato suportado. 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' 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' 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' UnprocessableEntity: description: 'A sintaxe da requisição esta correta, mas não foi possível processar as instruções presentes.' content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseErrorUnprocessableEntity' UnprocessableEntityDelete: description: 'A sintaxe da requisição esta correta, mas não foi possível processar as instruções presentes.' content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ResponseErrorUnprocessableEntityDelete' UnprocessableEntityConsents: description: 'A sintaxe da requisição está correta, mas não foi possível processar as instruções presentes.' content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/422ResponseErrorCreateConsent' examples: Necessário aprovação de múltipla alçada: summary: Necessário aprovação de múltipla alçada value: errors: - code: DEPENDE_MULTIPLA_ALCADA title: Necessário aprovação de múltipla alçada. detail: 'O consentimento informado não pode ser renovado sem redirecionamento porque depende de múltipla alçada para aprovação' meta: requestDateTime: '2021-05-21T08:30:00Z' totalPages: 1 totalRecords: 1 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' 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 additionalProperties: false meta: type: object description: Meta informações referente a 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' additionalProperties: false additionalProperties: false 201ConsentsCreated: description: Consentimento criado com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação entre request e response. Campo de geração e envio obrigatório pela receptora (client) e o seu valor deve ser “espelhado” pela transmissora (server) no cabeçalho de resposta. Caso não seja recebido ou se for recebido um valor inválido, a transmissora deve gerar um x-fapi-interaction-id e retorná-lo na resposta com o HTTP Status Code 400. A receptora deve acatar o valor recebido da transmissora. schema: type: string pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' minLength: 1 maxLength: 36 example: d78fc4e5-37ca-4da3-adf2-9b082bf92280 format: uuid content: application/json: schema: $ref: '#/components/schemas/ResponseConsent' 201ConsentsCreatedExtensions: description: Renovação do consentimento finalizada com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação entre request e response. Campo de geração e envio obrigatório pela receptora (client) e o seu valor deve ser “espelhado” pela transmissora (server) no cabeçalho de resposta. Caso não seja recebido ou se for recebido um valor inválido, a transmissora deve gerar um x-fapi-interaction-id e retorná-lo na resposta com o HTTP Status Code 400. A receptora deve acatar o valor recebido da transmissora. schema: type: string pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' minLength: 1 maxLength: 36 example: d78fc4e5-37ca-4da3-adf2-9b082bf92280 format: uuid content: application/json: schema: $ref: '#/components/schemas/ResponseConsentExtensions' 200ConsentsConsentIdRead: description: Consentimento consultado com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação entre request e response. Campo de geração e envio obrigatório pela receptora (client) e o seu valor deve ser “espelhado” pela transmissora (server) no cabeçalho de resposta. Caso não seja recebido ou se for recebido um valor inválido, a transmissora deve gerar um x-fapi-interaction-id e retorná-lo na resposta com o HTTP Status Code 400. A receptora deve acatar o valor recebido da transmissora. schema: type: string pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' minLength: 1 maxLength: 36 example: d78fc4e5-37ca-4da3-adf2-9b082bf92280 format: uuid content: application/json: schema: $ref: '#/components/schemas/ResponseConsentRead' 200ConsentsConsentIdReadExtensions: description: Renovações de consentimento consultado com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação entre request e response. Campo de geração e envio obrigatório pela receptora (client) e o seu valor deve ser “espelhado” pela transmissora (server) no cabeçalho de resposta. Caso não seja recebido ou se for recebido um valor inválido, a transmissora deve gerar um x-fapi-interaction-id e retorná-lo na resposta com o HTTP Status Code 400. A receptora deve acatar o valor recebido da transmissora. schema: type: string pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' minLength: 1 maxLength: 36 example: d78fc4e5-37ca-4da3-adf2-9b082bf92280 format: uuid content: application/json: schema: $ref: '#/components/schemas/ResponseConsentReadExtensions' 204ConsentsConsentIdDeleted: description: Consentimento revogado com sucesso. headers: x-fapi-interaction-id: description: | Um UUID RFC4122 usado como um ID de correlação entre request e response. Campo de geração e envio obrigatório pela receptora (client) e o seu valor deve ser “espelhado” pela transmissora (server) no cabeçalho de resposta. Caso não seja recebido ou se for recebido um valor inválido, a transmissora deve gerar um x-fapi-interaction-id e retorná-lo na resposta com o HTTP Status Code 400. A receptora deve acatar o valor recebido da transmissora. schema: type: string pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' minLength: 1 maxLength: 36 example: d78fc4e5-37ca-4da3-adf2-9b082bf92280 format: uuid