...
Cada atributo deverá estar associado a um tipo de dado. A lista de tipos de dados válidos está definida na seção tipos de dados comuns. Se um tipo de dado personalizado é necessário para um atributo, o mesmo deverá ser classificado como uma string com uma descrição clara de como o valor da propriedade deve ser interpretado.
Atributos obrigatórios/opcionais
Segundo a Instrução Normativa nº 34, BCB de 2020: ‘Todos os elementos que compõem as especificações das APIs (endpoints, operações, parâmetros, propriedades de respostas, etc.) devem ser explicitamente declarados como “Obrigatório”, “Opcional” ou “Condicional”, caso sejam obrigatórios apenas em certas condições’.
Os atributos obrigatórios devem estar presentes e ter um valor não nulo, seja em uma requisição ou resposta, para que payload seja considerado válido.
Os atributos condicionais devem ter uma marcação de restrição vinculada a eles na documentação da API (Swagger), no campo 'description'. Esses atributos terão a coluna 'Mandatoriedade' preenchida como 'Condicional', além de terem a situação descrita na coluna 'Restrições' do dicionário de dados.
Importante → A Instrução Normativa BCB n° 184 de 12/11/2021 e suas eventuais atualizações, estabelece, quais campos são obrigatórios por definição da regulação e quais são opcionais definidos. Desta forma, mesmo que um campo esteja especificado como opcional, caso ele exista, ele deve ser enviado seguindo a definição da regulação.
A opcionalidade dos campos é especificada para tratar situações de negócio em que um campo deixe de fazer sentido (por exemplo: 'o campo só deve ser preenchido se o produto for do tipo x') ou, para comportar cenários de exceções quando uma instituição não possuir o dado.
Atributos vazios/nulos
Para a Fase 1
Um atributo omitido (ou seja, um atributo que não está presente no payload) será considerado equivalente a um atributo que esteja presente com o valor null.
Uma string vazia (“”) não será considerada equivalente a null.
O valor booleano false não será considerado equivalente a null. Os atributos booleanos opcionais, por definição, possuirão três valores possíveis: verdadeiro (true), falso (false) e indeterminado (null).
Na situação onde o campo a ser informado no payload seja obrigatório e a Instituição, seja consumidora no envio ou transmissora no retorno, não a possuir, deve-se implementar o valor padronizado: “NA” - Não se Aplica, com exceção dos campos declarados como ENUM que deverão ser sempre preenchidos com os valores válidos para o ENUM correspondente.
Para as Fases 2 e 3
As "transmissoras" e "detentoras de conta" devem omitir do payload das APIs os campos com conteúdo nulo, conforme a especificação do Open API
Adicionalmente, não devem ser enviadas Strings vazias, "NA" ou valores que não se adequem ao domínio em questão.