09. Cadastrando recursos de uma API

Esta seção explica as etapas para cadastrar os endpoints de recursos de uma API.

Cadastramento de Recursos - Fase 1

Para cada uma das famílias de APIs devem ser adicionadas todos os endpoints disponíveis. Supondo que a instituição tenha disponibilizado dados em todos os endpoints da fase 1, a publicação deveria ser:

Cadastramento de Recursos - Fase 2

Na Fase 2 o padrão de cadastramento continua como na Fase 1, segue alguns pontos de atenção:

Para a API de consentimento é necessário apenas o cadastramento de uma entrada para o GET e o DELETE;
A API de customers foi dividida em duas famílias para facilitar o consumo pelos receptores. Customers-business onde é cadastrado os Endpoints PJ e customers-personal onde será cadastrado os endpoints PF. Cabendo aqui o cadastramento conforme a disponibilização do produto pela instituição;
O cadastramento de recursos deve respeitar a tabela de etapas da implementação assistida, conforme IN BCB n° 136 de 29/7/2021;
Para as APIs v2 da Fase 2 será necessário adicionar novos Family tipes informando a versão 2 e sua certificação.

Exemplo de preenchimento, levando em consideração que a instituição disponibilize tanto PF e PJ e o inicio da implementação assistida.

Cadastramento de Recursos - Fase 3

Na Fase 3 o padrão de segue alguns pontos de atenção:

A API de payments foi dividida para facilitar o consumo pelos iniciadores.
Na família de payments-consents devem ser declarados os endpoints de consentimento.
Na família de payments-pix devem ser declarado sos endpoints da forma de pagamento PIX.
Demais formas de pagamentos devem ser cadastradas conforme as especificações avancem.

Tabela Exemplo de Recursos - Fase 1

API	Diretório (Family Type)	Recursos (resources)
`discovery`	`discovery`	https://api.banco.com.br/open-banking/discovery/v1/status https://api.banco.com.br/open-banking/discovery/v1/outages
`channels`	`channels`	https://api.banco.com.br/open-banking/channels/v1/branches https://api.banco.com.br/open-banking/channels/v1/electronic-channels https://api.banco.com.br/open-banking/channels/v1/phone-channels https://api.banco.com.br/open-banking/channels/v1/banking-agents https://api.banco.com.br/open-banking/channels/v1/shared-automated-teller-machines
`products-services`	`products-services`	https://api.banco.com.br/open-banking/products-services/v1/personal-accounts https://api.banco.com.br/open-banking/products-services/v1/business-accounts https://api.banco.com.br/open-banking/products-services/v1/personal-loans https://api.banco.com.br/open-banking/products-services/v1/business-loans https://api.banco.com.br/open-banking/products-services/v1/personal-financings https://api.banco.com.br/open-banking/products-services/v1/business-financings https://api.banco.com.br/open-banking/products-services/v1/personal-invoice-financings https://api.banco.com.br/open-banking/products-services/v1/business-invoice-financings https://api.banco.com.br/open-banking/products-services/v1/personal-credit-cards https://api.banco.com.br/open-banking/products-services/v1/business-credit-cards https://api.banco.com.br/open-banking/products-services/v1/personal-unarranged-account-overdraft https://api.banco.com.br/open-banking/products-services/v1/business-unarranged-account-overdraft
`admin`	`admin`	https://api.banco.com.br/open-banking/admin/v1/metrics

Tabela Exemplo de Recursos - Fase 2

API	Diretório (Family Type)	Recursos (resources)
`consents`	`consents`	https://api.banco.com.br/open-banking/consents/v1/consents https://api.banco.com.br/open-banking/consents/v1/consents/{consentId}
`resources`	`resources`	https://api.banco.com.br/open-banking/resources/v1/resources
`customers`	`customers-bussines` `customers-personal`	`customers-personal` https://api.banco.com.br/open-banking/customers/v1/personal/identifications https://api.banco.com.br/open-banking/customers/v1/personal/qualifications https://api.banco.com.br/open-banking/customers/v1/personal/financial-relations `customers-bussines` https://api.banco.com.br/open-banking/customers/v1/business/identifications https://api.banco.com.br/open-banking/customers/v1/business/qualifications https://api.banco.com.br/open-banking/customers/v1/business/financial-relations
`credit-cards-accounts`	`credit-cards-accounts`	https://api.banco.com.br/open-banking/credit-cards-accounts/v1/accounts https://api.banco.com.br/open-banking/credit-cards-accounts/v1/accounts/{creditCardAccountId} https://api.banco.com.br/open-banking/credit-cards-accounts/v1/accounts/{creditCardAccountId}/limits https://api.banco.com.br/open-banking/credit-cards-accounts/v1/accounts/{creditCardAccountId}/transactions https://api.banco.com.br/open-banking/credit-cards-accounts/v1/accounts/{creditCardAccountId}/bills https://api.banco.com.br/open-banking/credit-cards-accounts/v1/accounts/{creditCardAccountId}/bills/{billId}/transactions
`accounts`	`accounts`	https://api.banco.com.br/open-banking/accounts/v1/accounts https://api.banco.com.br/open-banking/accounts/v1/accounts/{accountId} https://api.banco.com.br/open-banking/accounts/v1/accounts/{accountId}/balances https://api.banco.com.br/open-banking/accounts/v1/accounts/{accountId}/transactions https://api.banco.com.br/open-banking/accounts/v1/accounts/{accountId}/overdraft-limits
`loans`	`loans`	https://api.banco.com.br/open-banking/loans/v1/contracts https://api.banco.com.br/open-banking/loans/v1/contracts/{contractId} https://api.banco.com.br/open-banking/loans/v1/contracts/{contractId}/warranties https://api.banco.com.br/open-banking/loans/v1/contracts/{contractId}/payments https://api.banco.com.br/open-banking/loans/v1/contracts/{contractId}/scheduled-instalments
`financings`	`financings`	https://api.banco.com.br/open-banking/financings/v1/contracts https://api.banco.com.br/open-banking/financings/v1/contracts/{contractId} https://api.banco.com.br/open-banking/financings/v1/contracts/{contractId}/warranties https://api.banco.com.br/open-banking/financings/v1/contracts/{contractId}/payments https://api.banco.com.br/open-banking/financings/v1/contracts/{contractId}/scheduled-instalment
`unarranged-accounts-overdraft`	`unarranged-accounts-overdraft`	https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v1/contracts https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId} https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/warranties https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/payments https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v1/contracts/{contractId}/scheduled-instalments
`invoice-financings`	`invoice-financings`	https://api.banco.com.br/open-banking/invoice-financings/v1/contracts https://api.banco.com.br/open-banking/invoice-financings/v1/contracts/{contractId} https://api.banco.com.br/open-banking/invoice-financings/v1/contracts/{contractId}/warranties https://api.banco.com.br/open-banking/invoice-financings/v1/contracts/{contractId}/payments https://api.banco.com.br/open-banking/invoice-financings/v1/contracts/{contractId}/scheduled-instalments

Tabela Exemplo de Recursos - Fase 2 v2

API	Diretório (Family Type)	Recursos (resources)
`consents`	`consents`	https://api.banco.com.br/open-banking/consents/v2/consents https://api.banco.com.br/open-banking/consents/v2/consents/{consentId}
`resources`	`resources`	https://api.banco.com.br/open-banking/resources/v2/resources
`customers`	`customers-bussines` `customers-personal`	`customers-personal` https://api.banco.com.br/open-banking/customers/v2/personal/identifications https://api.banco.com.br/open-banking/customers/v2/personal/qualifications https://api.banco.com.br/open-banking/customers/v2/personal/financial-relations `customers-bussines` https://api.banco.com.br/open-banking/customers/v2/business/identifications https://api.banco.com.br/open-banking/customers/v2/business/qualifications https://api.banco.com.br/open-banking/customers/v2/business/financial-relations
`credit-cards-accounts`	`credit-cards-accounts`	https://api.banco.com.br/open-banking/credit-cards-accounts/v2/accounts https://api.banco.com.br/open-banking/credit-cards-accounts/v2/accounts/{creditCardAccountId} https://api.banco.com.br/open-banking/credit-cards-accounts/v2/accounts/{creditCardAccountId}/limits https://api.banco.com.br/open-banking/credit-cards-accounts/v2/accounts/{creditCardAccountId}/transactions https://api.banco.com.br/open-banking/credit-cards-accounts/v2/accounts/{creditCardAccountId}/transactions-current https://api.banco.com.br/open-banking/credit-cards-accounts/v2/accounts/{creditCardAccountId}/bills https://api.banco.com.br/open-banking/credit-cards-accounts/v2/accounts/{creditCardAccountId}/bills/{billId}/transactions
`accounts`	`accounts`	https://api.banco.com.br/open-banking/accounts/v2/accounts https://api.banco.com.br/open-banking/accounts/v2/accounts/{accountId} https://api.banco.com.br/open-banking/accounts/v2/accounts/{accountId}/balances https://api.banco.com.br/open-banking/accounts/v2/accounts/{accountId}/transactions https://api.banco.com.br/open-banking/accounts/v2/accounts/{accountId}/transactions-current https://api.banco.com.br/open-banking/accounts/v2/accounts/{accountId}/overdraft-limits
`loans`	`loans`	https://api.banco.com.br/open-banking/loans/v2/contracts https://api.banco.com.br/open-banking/loans/v2/contracts/{contractId} https://api.banco.com.br/open-banking/loans/v2/contracts/{contractId}/warranties https://api.banco.com.br/open-banking/loans/v2/contracts/{contractId}/payments https://api.banco.com.br/open-banking/loans/v2/contracts/{contractId}/scheduled-instalments
`financings`	`financings`	https://api.banco.com.br/open-banking/financings/v2/contracts https://api.banco.com.br/open-banking/financings/v2/contracts/{contractId} https://api.banco.com.br/open-banking/financings/v2/contracts/{contractId}/warranties https://api.banco.com.br/open-banking/financings/v2/contracts/{contractId}/payments https://api.banco.com.br/open-banking/financings/v2/contracts/{contractId}/scheduled-instalment
`unarranged-accounts-overdraft`	`unarranged-accounts-overdraft`	https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v2/contracts https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v2/contracts/{contractId} https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v2/contracts/{contractId}/warranties https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v2/contracts/{contractId}/payments https://api.banco.com.br/open-banking/unarranged-accounts-overdraft/v2/contracts/{contractId}/scheduled-instalments
`invoice-financings`	`invoice-financings`	https://api.banco.com.br/open-banking/invoice-financings/v2/contracts https://api.banco.com.br/open-banking/invoice-financings/v2/contracts/{contractId} https://api.banco.com.br/open-banking/invoice-financings/v2/contracts/{contractId}/warranties https://api.banco.com.br/open-banking/invoice-financings/v2/contracts/{contractId}/payments https://api.banco.com.br/open-banking/invoice-financings/v2/contracts/{contractId}/scheduled-instalments

Tabela Exemplo de Recursos - Fase 3

API

Diretório (Family Type)

Recursos (resources)

payments

payments-consents

payments-pix

payments-consents

https://api.banco.com.br/open-banking/payments/v1/consents

https://api.banco.com.br/open-banking/payments/v1/consents/{consentId}

payments-pix

https://api.banco.com.br/open-banking/payments/v1/pix/payments

https://api.banco.com.br/open-banking/payments/v1/pix/payments/{paymentId}

Etapa 1: Cadastrando um Novo Recurso de uma API

Requisitos

1. No Diretório, localize e selecione a sua organização.

2. Selecione o menu Authorisation Servers e clique no link do servidor de autorização na qual se deseja cadastrar os recursos.

3. No canto superior esquerdo da página clique em API Resources.

4. Na página que será carregada clique no botão New API Resources para abrir a janela New API Resource.

5. Na janela New API Resource, clique na caixa de seleção API Family Type e selecione uma das opções disponíveis.

6. No campo ao lado, em Version especifique o valor apropriado utilizando versionamento semântico (major.minor.patch, exemplo 1.0.7)

7. No campo Certification URL é necessário informar a URL onde se encontra a localização do certificado publicado no GitHub. Esse preenchimento é obrigatório para famílias de API’s a partir da Fase 2 e clique no botão Save.

NOTA 1: A URL a ser informada deve ser a presente no GitHub no caminho: conformance > submissions/functional selecionando a API especifica e informar a URL com o artefato de certificação .zip.

Exemplo: https://openbanking-brasil.github.io/conformance/submissions/functional/<family-type>/<version>/<file-name>.zip

NOTA 2: No ambiente de Sandbox do Diretório, caso não exista uma certificação, é possível incluir um endereço para testes: https://openbanking-brasil.github.io/teste.zip

8. De volta a tela API Resources, informe URL principal no campo API Discovery Endpoints, e em seguida pressione a tecla Enter.

9. Para cada uma das famílias de APIs repita os passos 4 a 7.

NOTA: Todos os endpoints deverão ser preenchidos, incluindo os respectivos recursos. Para obter mais detalhes sobre o padrão do endpoints e versão consulte o Portal do Desenvolvedor do Open Finance.

Cadastramento de Recursos - Fase 4A

Na Fase 4A o padrão de cadastro segue alguns pontos de atenção:

O cadastro das APIs deve ser realizado individualmente, para cada um dos recursos/endpoints existirá um tipo de família (Family Type)
Diferente das outras famílias, ao requisitar o cadastro dessas APIs, será executado um teste de conformidade funcional que verificará a conformidade da API com a especificação do Swagger
O diretório só permitirá o cadastro da API caso o teste de conformidade seja bem sucedido
Semelhante a Fase 1, a publicação do recurso é condiciona a IF possuir tal produto, logo, não necessariamente todos os recursos precisam ser publicados

Cadastramento de Recursos - Fase 4A (1/2)

API	Diretório (Family Type)	Recursos (resources)
`opendata-investments`	`opendata-investments_funds` `opendata-investments_bank-fixed-incomes` `opendata-investments_credit-fixed-incomes` `opendata-investments_variable-incomes` `opendata-investments_treasure-titles`	`opendata-investment-funds` https://api.banco.com.br/open-banking/opendata-investments/v1/funds `opendata-investments-bank-fixed-incomes` https://api.banco.com.br/open-banking/opendata-investments/v1/bank-fixed-incomes `opendata-investments-credit-fixed-incomes` https://api.banco.com.br/open-banking/opendata-investments/v1/credit-fixed-incomes `opendata-investments-variable-incomes` https://api.banco.com.br/open-banking/opendata-investments/v1/variable-incomes `opendata-investments-treasure-titles` https://api.banco.com.br/open-banking/opendata-investments/v1/treasure-titles
`opendata-capitalization`	`opendata-capitalization_bonds`	`opendata-capitalization-bonds` https://api.banco.com.br/open-banking/opendata-capitalization/v1/bonds
`opendata-exchange`	`opendata-exchange_online-rates` `opendata-exchange_vet-values`	`opendata-exchange-online-rates` https://api.banco.com.br/open-banking/opendata-exchange/v1/online-rates `opendata-exchange-vet-values` https://api.banco.com.br/open-banking/opendata-exchange/v1/vet-values

Cadastramento de Recursos - Fase 4A (2/2)

API	Diretório (Family Type)	Recursos (resources)
`opendata-acquiring-services`	`opendata-acquiring-services_personals` `opendata-acquiring-services_businesses`	`opendata-acquiring-services-personals` https://api.banco.com.br/open-banking/opendata-acquiring-services/v1/personals `opendata-acquiring-services-businesses` https://api.banco.com.br/open-banking/opendata-acquiring-services/v1/businesses
`opendata-pension`	`opendata-pension_risk-coverages` `opendata-pension_survival-coverages`	`opendata-pension-risk-coverages` https://api.banco.com.br/open-banking/opendata-pension/v1/risk-coverages `opendata-pension-survival-coverages` https://api.banco.com.br/open-banking/opendata-pension/v1/survival-coverages
`opendata-insurance`	`opendata-insurance_automotives` `opendata-insurance_homes` `opendata-insurance_personals`	`opendata-insurance-automotives` https://api.banco.com.br/open-banking/opendata-insurance/v1/automotives `opendata-insurance-homes` https://api.banco.com.br/open-banking/opendata-insurance/v1/homes `opendata-insurance-personals` https://api.banco.com.br/open-banking/opendata-insurance/v1/personals

Etapa 2: Cadastrando um Novo Recurso de uma API com Certificação Automática - Fase 4A

Requisitos

1. No Diretório, localize e selecione a sua organização.

2. Selecione o menu Authorisation Servers e clique no link do servidor de autorização na qual se deseja cadastrar os recursos.

3. No lado esquerdo da tela clique em API Resources

4. Clique no botão New API Resources para abrir a janela New API Resource

5. Na janela New API Resource, clique na caixa de seleção API Family Type e selecione uma das opções disponíveis que possuem certificação automática

6. No campo ao lado, em Version especifique o valor da versão da API conforme especificação

7. No campo THE URL FOR THE API é necessário informar a URL referente ao recurso da API a ser registrado

8. A URL da API deve seguir o formato especificado no portal do desenvolvedor, caso contrário o diretório irá retornar um erro, não permitindo a continuidade do cadastro

9. Ao selecionar Save uma janela irá aparecer informando que ao pressionar OK um teste de conformidade será executado contra o recurso preenchido acima

NOTA 1: O valor informado no campo THE URL FOR THE API é a URI contra a qual o teste será executado.

NOTA 2: Caso o teste de conformidade não seja bem sucedido é possível consultar os logs de execução do teste que impediu a publicação da API. Para isso basta copiar a URL apresentada na mensagem de erro e colar na barra do navegador.

10. Caso a execução seja mal sucedida, é possível consultar os detalhes que geraram a falha em View Logs.

11. Caso o teste seja bem sucedido, a nova API será adicionada automaticamente a tabela de recursos do Authorisation Server

12. A coluna referente a API CERTIFICATION URL também será preenchida automaticamente e apresentada na tabela.

13. Caso seja necessário atualizar a URL do recurso adicionado basta clicar no botão editar ou em apagar.

Etapa 3: Removendo um Recurso de uma API

Requisitos

1. No Diretório, localize e selecione a sua organização.

2. Selecione o menu Servidores de Autorização. Na tela ao lado, selecione o servidor de autorização no qual o recurso será removido.

3. De volta ao menu, selecione a opção Recursos do API, e na tela ao lado, localize o Tipo da Família da API (API Family Type) que será removido.

4. Clique no ícone Excluir para remover a família de recursos e suas APIs.