O DICT utiliza autenticação mútua TLS.

As definições de autenticação para essa API estão especificados no manual de segurança PIX

Requisições que incluam ou alterem informações no DICT devem ser assinadas com XML Digital Signature pelo participante que envia a requisição. Requisições de consulta não precisam ser assinadas. Respostas retornadas pelo DICT serão assinadas digitalmente. As assinaturas devem ser validadas pelos clientes da API.

A assinatura será colocada no elemento Signature das requisições e respostas. O Signature será envelopado pelo XML que está sendo assinado (assinatura é um elemento filho).

Para mais detalhes sobre a forma de construir a assinatura, consulte o manual de segurança PIX.

Para previnir ataques de enumeração, há mecanismo de limitação da quantidade de consultas que podem ser feitas num espaço de tempo (rate-limiting). A limitação atua em dois níveis, para usuários individuais e para um participante como um todo.

Para cada um desses níveis, há limite para o número de consultas que não resultam em pagamento.

Quando algum desses limites for atingido, o serviço retornará status 429, especificando a causa. Cabeçalhos indicando os parâmetros de rate-limiting serão retornados nas requisições. Ver, por exemplo, os cabeçalhos retornados ao consultar vínculo.

As seguintes mudanças são esperadas e consideradas retro-compatíveis (backwards-compatibility):

• Adição de novos recursos na API.
• Adição de novos parâmetros opcionais a requisições.
• Adição de novos campos em respostas da API.
• Alteração da ordem de campos.
• Adição de novos elementos em enumerações

Mudanças compatíveis não geram nova versão da API. Clientes devem estar preparados para lidar com essas mudanças sem quebrar.

Mudanças incompatíveis geram nova versão da API.

O DICT retorna códigos de status HTTP para indicar sucesso ou falhas das requisições. Códigos 2xx indicam sucesso. Códigos 4xx indicam falhas causadas pelas informações enviadas pelo cliente ou pelo estado atual das entidades. Códigos 5xx indicam problemas no serviço no lado do DICT.

As respostas de erro incluem no corpo detalhes do erro seguindo o schema da RFC Problem Details for HTTP APIs. O campo type identifica o tipo de erro e no DICT segue o padrão: https://dict.pi.rsfn.net.br/api/v1/error/<TipoErro>

Abaixo estão listados os tipos de erro do DICT.

Gerais

• Forbidden

  • Requisição de participante autenticado que viola alguma regra de autorização. Ver rfc7231.

• BadRequest

  • Requisição com formato inválido. Ver rfc7231

• NotFound

  • Entidade não encontrada. Ver rfc7231

• RateLimited

  • Limite de requisições foi atingido. Ver seção sobre limitação de requisições

• ServiceUnavailable

  • Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.

• RequestSignatureInvalid

  • Assinatura digital da requisição enviada é inválida.

• RequestOnBehalfUnauthorized

  • Participante direto envia requisição em nome de participante indireto para o qual não tem autorização.

• RequestIdAlreadyUsed

  • Requisição foi feita com mesmo RequestId de requisição feita anteriormente, mas com parâmetros diferentes.

Vínculos

• EntryInvalid

  • Existem campos inválidos ao tentar criar novo vínculo.

• EntryLimitExceeded

  • Número de vínculos associados a conta transacional excedeu o limite máximo.

• EntryAlreadyExists

  • Já existe vínculo para essa chave com o mesmo participante e dono.

• EntryCannotBeQueriedForBookTransfer

  • Vínculo consultado está custodiado no mesmo PSP do usuário pagador para quem está sendo feita a consulta. Quando o pagador e o recebedor estão no mesmo PSP, não deve ser feita consulta ao DICT.

• EntryKeyOwnedByDifferentPerson

  • Já existe vínculo para essa chave mas ela é possuída por outra pessoa. Indica-se que seja feita uma reivindicação de posse.

• EntryKeyInCustodyOfDifferentParticipant

  • Já existe vínculo para essa chave com o mesmo dono, mas ela encontra-se associada a outro participante. Indica-se que seja feita uma reivindicação de portabilidade.

• EntryLockedByClaim

  • Existe uma reivindicação com status diferente de concluída ou cancelada para a chave do vínculo. Enquanto estiver nessa situação, o vínculo não pode ser excluído.

Reivindicações

• ClaimInvalid

  • Existem campos inválidos ao tentar criar nova reivindicação.

• ClaimTypeInconsistent

  • Tipo de reivindicação pedida é inconsistente. Esse erro ocorre nas situações em que se tenta criar a) reivindicação de posse, mas vínculo existente tem como dona a mesma pessoa que reivindica ou b) reinvidicação de portabilidade, mas vínculo existente tem como dona pessoa diferente da que reivindica.

• ClaimKeyNotFound

  • Não existe vínculo registrado com a chave que está sendo reivindicada.

• ClaimAlreadyExistsForKey

  • Existe uma reivindicação com status diferente de concluída ou cancelada para a chave reivindicada. Nova reivindicação para a chave só pode ser criada se a atual foi concluída ou cancelada.

• ClaimResultingEntryAlreadyExists

  • Vínculo que resultaria ao processar reivindicação já existe, com mesma chave, participante e dono.

• ClaimOperationInvalid

  • Status atual da reivindicação não permite que operação seja feita.

• ClaimResolutionPeriodNotEnded

  • Para reivindicação de posse, PSP doador não pode confirmar antes do término do período resolução. Para portabilidade, PSP doador não pode cancelar por fim de prazo antes do término do período resolução.

• ClaimCompletionPeriodNotEnded

  • Para reivindicação de posse, se PSP reivindicador tenta encerrar antes do término do período encerramento.

O diretório de identificadores de contas transacionais é um conjunto de vínculos. Um vínculo é uma associação entre uma chave de endereçamento, uma conta transacional e seu dono. O dono pode ser uma pessoa física ou uma pessoa jurídica. A chave de endereçamento é usada identificar um vínculo.

Os tipos de chave suportadas atualmente são as seguintes:

Novos tipos de chave poderão vir a ser adicionados no futuro. Logo, é importante que a implementação de clientes seja flexível, permitindo a adição de novos tipos de chave.

Conforme as chaves mudem de dono ou os usuários finais criem contas transacionais em outros PSPs, os seguintes cenários precisarão ser tratados:

1. Houve troca de posse de uma chave (telefone ou email) e o novo dono deseja criar um vínculo para uma conta sua mas o dono anterior já possui vínculo registrado no DICT com essa chave.
2. Um usuário deseja mudar a vinculação de uma chave sua para outra conta, que está domiciliada em um participante diferente do atual.

Para o cenário 1, deve ser criada uma reivindicação de posse. Já para o cenário 2, uma portabilidade. Em ambos cenários existirá a figura do PSP que irá ceder a chave (PSP Doador), e o PSP que irá receber a chave (PSP Reivindicador). No cenário de reivindicação de posse, o PSP doador e o reivindicador podem ser o mesmo.

Nessa especificação, reivindicação sem qualificador é usado como termo mais genérico para se referir tanto à reivindicação de posse quanto à (reivindicação de) portabilidade.

Os processos de reivindicação são sempre iniciados pelo PSP reivindicador. Uma reivindicação tem as seguintes situações:

• OPEN - Aberta pelo reivindicador, mas ainda não recebida pelo doador.
• WAITING_RESOLUTION - Já foi recebida pelo doador e está aguardando a resolução. Os critérios confirmação ou cancelamento da reivindicação seguem normas específicas a depender do tipo (posse ou portabilidade).
• CONFIRMED - O doador confirmou a reivindicação. Isso implica a remoção da chave do DICT e da base interna do PSP doador. Está aguardando o reivindicador encerrar o processo.
• CANCELLED - O doador ou reivindicador cancelou a reivindicação, mantendo o vínculo inalterado (conforme estava antes da reivindicação) tanto no DICT quanto na base interna do PSP.
• COMPLETED - Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo.

Diagrama de estados

( OPEN )------->( WAITING_RESOLUTION )------->( CONFIRMED )------->( COMPLETED )
                          |                        /                            
                          |                       /                             
                          |                      /                              
                          |                     /--Apenas para                  
                          v                    /   reivindicação                
                    ( CANCELLED )<------------v    de posse                      

Importante! Os participantes deverão monitorar as reivindicações fazendo polling períodico no endpoint de listar reivindicações. A periodicidade adequada dependerá das definições de nível de serviço.