Princípios

Os seguintes princípios técnicos não exaustivos constituem a base para o desenvolvimento e implementação das APIs para o Open Finance no Brasil.

Princípio 1: Segurança

A adoção de mecanismos de segurança no design e implementação das APIs do Open Finance no Brasil deverá considerar os padrões aplicáveis a cada uma de suas fases, visando a proteção e a disponibilidade do ecossistema como um todo, considerando clientes, participantes e os dados específicos compartilhados em cada fase.

Princípio 2: RESTful APIs

A API irá aderir aos conceitos de RESTful API sempre que for possível e sensato.

Princípio 3: Padrões existentes

Os padrões existentes serão adotados sempre que sua aplicação for relevante/apropriada e desde que não violem nenhum dos demais princípios, com foco na experiência do desenvolvedor e do usuário e, ainda, prevendo a extensibilidade, resiliência e a evolução do Open Finance no Brasil.

Princípio 4: ISO 20022

Os payloads das APIs serão desenvolvidos utilizando como base os elementos e componentes de mensagem ISO 20022, que poderão ser modificados, caso necessário, para deixar o payload mais simples e/ou atender às características locais, tal como implementado em diferentes jurisdições.

Princípio 5: Extensibilidade

Os fluxos das APIs serão estendidos para atender a casos de uso mais complexos em futuros releases e, portanto, esse princípio será mantido em mente durante o design, e os procedimentos serão detalhados durante a implementação.

Princípio 6: Códigos de status

A API usará dois códigos de status que atendem a dois propósitos diferentes: (i) o HTTP status code reflete o resultado da chamada da API e (ii) um campo status em alguns resource payloads reflete o status dos resources nos casos de acesso write (p. ex. iniciação de pagamento).

Princípio 7: Identificadores únicos

Um recurso REST deverá ter um identificador exclusivo que possa ser usado para identificar o recurso alvo da API. Esse identificador será usado para criar URLs que permitam endereçar recursos específicos, obedecendo aos padrões definidos nesta documentação, no item Formação e estabilidade do ID.

Princípio 8: Categorização dos requisitos de implementação

Quando um requisito estiver sendo implementado por um transmissor e/ou um receptor, uma categorização diferente será aplicada. As funcionalidades, endpoints e campos em cada recurso serão categorizados como 'Obrigatório', 'Condicional' ou 'Opcional'.

Princípio 9: Agnósticas

As APIs serão agnósticas à implementação onde elas poderão ser consumidas independente das tecnologias adotadas no ecossistema, porém com aderência aos princípios contidos nesta documentação.

Princípio 10: Idempotência

As APIs serão definidas como idempotentes para não causar uma experiência ruim ao consumidor ou aumentar os indicadores de risco falso positivo. Trata-se de recurso necessário para garantir que não haja duplicidade em caso de perda de comunicação e não deve se limitar aos verbos HTTP, devendo ser aplicado ao design completo da API.