Esta seção do padrão descreve as estruturas padrões de requisição e resposta para todos os endpoints das APIs, assim como as convenções de nomenclatura para os atributos.
Estrutura de requisição
Cada requisição deve ser um objeto JSON contendo um objeto data para armazenar os dados primários da requisição.
No mesmo nível do objeto data, poderá existir um objeto meta se assim for especificado pelo endpoint. O objeto meta é usado para fornecer informações adicionais ao endpoint, como parâmetros de paginação, contagens de paginação ou outros propósitos complementares ao funcionamento da API.
A definição do conteúdo para o objeto data será definida separadamente para cada endpoint.
Estrutura da requisição
{
"data": {
"..."
}
}
Estrutura de resposta
Cada endpoint retornará um objeto JSON contendo os atributos abaixo.
Se a resposta for bem-sucedida (200 OK), o objeto JSON irá conter:
obrigatoriamente um objeto
data;obrigatoriamente um objeto
links;opcionalmente um objeto
meta, se necessário pela definição do endpoint requisitado.
Se a resposta for malsucedida (não 200 OK), o objeto JSON poderá conter:
um objeto
errors(conforme a definição específica do endpoint).
A definição do conteúdo para os objetos data e meta será definida separadamente para cada endpoint.
O objeto links irá conter hypermedia (referências para recursos relacionados) para outros recursos da API requisitada.
O objeto de links sempre irá conter o atributo self que irá apontar para a URI da solicitação atual.
O objeto
errorsserá um array de zero ou mais objetos. Os atributos deste objeto serão os descritos abaixo:obrigatoriamente o atributo
codecontendo um código de erro específico do endpoint;obrigatoriamente o atributo
titlecontendo um título legível por humanos do erro deste erro específico;obrigatoriamente o atributo
detailcontendo uma descrição legível por humanos deste erro específico;opcionalmente o objeto
metacontendo dados adicionais sobre o endpoint que seja relevante para o erro.
Estrutura de resposta
{
"data": {
"..."
},
"links":{
"..."
},
"meta": {
"..."
}
}
Estrutura de resposta de erros
{
"errors": [
{
"code": "...",
"title": "...",
"detail": "..."
}
],
"meta":{
"..."
}
}
Convenções de nomenclatura de atributos
Caracteres válidos em nomes de atributos
Todos os nomes de objetos e atributos definidos nos objetos JSON de requisição e resposta devem ser nomeados seguindo o padrão camelCase, tendo seu nome composto apenas por letras (a-z, A-Z) e números (0-9).
Qualquer outro caractere não deve ser usado nos nomes dos objetos e atributos, com exceção do caractere - (hífen), que poderá ser utilizado apenas conforme descrito na seção Extensibilidade.
Estilo de nomeação de atributos
Os nomes dos objetos e atributos devem ser nomes significativos e em língua inglesa. Quando houver diferença entre inglês americano e inglês britânico no termo a ser utilizado, deverá ser utilizado o termo em inglês britânico. P. ex: utilizar o termo Post Code (Reino Unido) ao invés de Zip Code (Estados Unidos).
Arrays devem ser nomeados no plural. Demais atributos deverão ser nomeados no singular.
Convenções de propriedade dos atributos
Tipos de dados dos atributos
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.