openapi: 3.0.0 info: title: DICT API version: '1.8.0' license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0 contact: name: Suporte TI BCB email: suporte.ti@bcb.gov.br url: https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos description: |- O Diretório de Identificadores de Contas Transacionais - DICT - é o serviço do arranjo Pix que permite buscar detalhes de contas transacionais com chaves de endereçamento mais convenientes para quem faz um pagamento. Entre os tipos de chave atualmente disponíveis estão CPF, CNPJ, telefone, e-mail e EVP. As informações retornadas pelo DICT permitem ao pagador confirmar a identidade do recebedor, proporcionando uma experiência mais fácil e segura. Permitem também ao PSP do pagador criar a mensagem de instrução de pagamento a ser enviada para o sistema de liquidação com os detalhes de conta do recebedor. Para informações adicionais, consulte a [página do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos). # Segurança ## Autenticação O DICT utiliza autenticação mútua TLS. As definições de autenticação para essa API estão especificadas no [manual de segurança do Pix](https://www.bcb.gov.br/content/estabilidadefinanceira/cedsfn/Manual%20de%20Seguranca%20do%20PIX%20v3.4.pdf). ## Assinatura digital Requisições que incluam ou alterem informações no DICT devem ser assinadas com [XML Digital Signature](https://www.w3.org/2000/09/xmldsig) 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](https://www.w3.org/TR/xmldsig-core1/#def-SignatureEnveloped) 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 do Pix](https://www.bcb.gov.br/content/estabilidadefinanceira/cedsfn/Manual%20de%20Seguranca%20do%20PIX%20v3.4.pdf). ## Limitação de requisições Para preservar a estabilidade do serviço, as operações da API do DICT estão sujeitas a políticas de limitação de requisições. Especificamente para a operação de consulta de vínculo, há também limitação de requisições com a finalidade de prevenir ataques de varredura de dados. O algoritmo usado para implementar as políticas de limitação é o [token bucket](https://en.wikipedia.org/wiki/Token_bucket). Uma política de limitação tem associado a ela um escopo, que pode ser o usuário final ou o participante. Cada política possui uma taxa de reposição de "fichas", um tamanho de "balde" e uma regra de contagem. A tabela abaixo define as políticas aplicáveis a cada operação da API. | Política | Escopo | Operações | Taxa de reposição | Tamanho do balde | |--------------------------------------|----------|------------------------------------------------------------------------------------------------------|-------------------|------------------| | ENTRIES_READ_USER_ANTISCAN | USER | getEntry | 2/min | (*) | | ENTRIES_READ_USER_ANTISCAN_V2 | USER | getEntry | 2/min | (*) | | ENTRIES_READ_PARTICIPANT_ANTISCAN | PSP | getEntry | (**) | (**) | | ENTRIES_WRITE | PSP | createEntry, deleteEntry | 1200/min | 36000 | | ENTRIES_UPDATE | PSP | updateEntry | 600/min | 600 | | CLAIMS_READ | PSP | getClaim | 600/min | 18000 | | CLAIMS_WRITE | PSP | createClaim, acknowledgeClaim, cancelClaim, confirmClaim, completeClaim | 1200/min | 36000 | | CLAIMS_LIST_WITH_ROLE | PSP | listClaims | 40/min | 200 | | CLAIMS_LIST_WITHOUT_ROLE | PSP | listClaims | 10/min | 50 | | SYNC_VERIFICATIONS_WRITE | PSP | createSyncVerification | 10/min | 50 | | CIDS_FILES_WRITE | PSP | createCidSetFile | 40/dia | 200 | | CIDS_FILES_READ | PSP | getCidSetFile | 10/min | 50 | | CIDS_EVENTS_LIST | PSP | listCidSetEvents | 20/min | 100 | | CIDS_ENTRIES_READ | PSP | getEntryByCid | 1200/min | 36000 | | INFRACTION_REPORTS_READ | PSP | getInfractionReport | 600/min | 18000 | | INFRACTION_REPORTS_WRITE | PSP | createInfractionReport, acknowledgeInfractionReport, cancelInfractionReport, closeInfractionReport | 1200/min | 36000 | | INFRACTION_REPORTS_LIST_WITH_ROLE | PSP | listInfractionReports | 40/min | 200 | | INFRACTION_REPORTS_LIST_WITHOUT_ROLE | PSP | listInfractionReports | 10/min | 50 | | KEYS_CHECK | PSP | checkKeys | 70/min | 70 | | REFUNDS_READ | PSP | getRefund | 1200/min | 36000 | | REFUNDS_WRITE | PSP | createRefund, cancelRefund, closeRefund | 2400/min | 72000 | | REFUND_LIST_WITH_ROLE | PSP | listRefunds | 40/min | 200 | | REFUND_LIST_WITHOUT_ROLE | PSP | listRefunds | 10/min | 50 | | STATISTICS_READ | PSP | getOwnerStatistics | 500/min | 500 | | POLICIES_READ | PSP | getBucketState | 60/min | 200 | | POLICIES_LIST | PSP | listBucketStates | 6/min | 20 | ### Regras de contagem das políticas - `ENTRIES_READ_USER_ANTISCAN` - Aplicável somente para chaves do tipo EMAIL e PHONE - status 200: subtrai 1 - status 404: subtrai 20 - ordem de pagamento enviada: adiciona 1 - `ENTRIES_READ_USER_ANTISCAN_V2` - Aplicável somente para chaves do tipo CPF, CNPJ e EVP - status 200: subtrai 1 - status 404: subtrai 20 - ordem de pagamento enviada: adiciona 1 (*) O tamanho do balde das políticas ENTRIES_READ_USER_ANTISCAN e ENTRIES_READ_USER_ANTISCAN_V2 é categorizado de acordo com o tipo de usuário final realizando a consulta, Pessoa Física (PF) ou Pessoa Jurídica (PJ): | Categoria | Tamanho do balde | |--------------|-------------------| | PF | 100 | | PJ | 1.000 | - `ENTRIES_READ_PARTICIPANT_ANTISCAN` - Aplicável para todos os tipos de chaves (EMAIL, PHONE, CPF, CNPJ e EVP) - status 200: subtrai 1 - status 404: subtrai 3 - ordem de pagamento enviada: adiciona 1 (**) O tamanho do balde nesta política depende da categoria em que se enquadra do participante. As seguintes categorias são possíveis: | Categoria | Taxa de reposição | Tamanho do balde | |--------------|-------------------|------------------| | A | 12.000/min | 20.000 | | B | 8.000/min | 15.000 | | C | 2.000/min | 8.000 | | D | 500/min | 4.000 | | E | 50/min | 3.000 | | F | 2/min | 1.000 | - `CLAIMS_LIST_WITH_ROLE` - Aplicável quando há filtragem por doador/reivindicador - status diferente de 500: subtrai 1 - `CLAIMS_LIST_WITHOUT_ROLE` - Aplicável quando não há filtragem por doador/reivindicador - status diferente de 500: subtrai 1 - `REFUND_LIST_WITH_ROLE` - Aplicável quando há filtragem por requisitante/contestado - status diferente de 500: subtrai 1 - `REFUND_LIST_WITHOUT_ROLE` - Aplicável quando não há filtragem por requisitante/contestado - status diferente de 500: subtrai 1 - Demais políticas - status diferente de 500: subtrai 1 ### Violação de limites Caso o limite de uma política seja excedido, o que acontece quando a quantidade de fichas chega a zero, será retornada uma resposta de erro com status `429`. # Recomendações de desempenho É altamente recomendável que as conexões HTTP para a comunicação com a API sejam reutilizadas, pois o custo de estabelecimento de uma conexão mTLS é muito alto em termos de latência. O uso de um _pool_ de conexões HTTP é uma alternativa efetiva para reutilização de conexões. A API retorna o header [`Keep-Alive`](https://tools.ietf.org/html/rfc2068#section-19.7.1.1) com o parâmetro `timeout`. Nele é informado o tempo em segundos que o servidor esperará antes de fechar a conexão caso não ocorram requisições adicionais. É recomendável também que se utilize compressão. Para que as respostas da API utilizem compressão, adicione nas requisições o header `Accept-Encoding: gzip`. O envio de requisições com compressão não é suportado. # Evolução da API As seguintes mudanças são esperadas e consideradas compatíveis: - 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 ## Versionamento A versão da API é composta por 4 elementos: _major_, _minor_, _patch_ e _release candidate_. A versão que consta no _path_ da URL é o elemento _major_ da versão da API. A evolução da versão se dá seguinte forma: - *Major*: alterações incompatíveis, com quebra de contrato (v1.0.0 → v2.0.0) - *Minor*: alterações compatíveis, sem quebra de contrato (v1.1.0 → v1.2.0) - *Patch*: esclarecimentos às especificações, sem alterações funcionais (v1.1.1 → v1.1.2) - *Release candidate*: versões de pré-lançamento de qualquer patch futuro, minor ou major (v1.0.0-rc1 → v1.0.0-rc2) Não serão feitas mais que uma evolução _major_ em um período de 6 meses, ressalvado motivo de força maior. Quando houver uma evolução _major_, a versão anterior ficará disponível por no mínimo 1 mês. Alterações sem quebra de contrato e esclarecimentos às especificações podem ocorrer a qualquer momento. Clientes devem estar preparados para lidar com essas mudanças sem quebrar. # Tratamento de erros 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](https://tools.ietf.org/html/rfc7807). O campo `type` identifica o tipo de erro e no DICT segue o padrão: `https://dict.pi.rsfn.net.br/api/v1/error/` 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](https://tools.ietf.org/html/rfc7231#section-6.5.3). - `BadRequest` - Requisição com formato inválido. Ver [rfc7231](https://tools.ietf.org/html/rfc7231#section-6.5.1) - `NotFound` - Entidade não encontrada. Ver [rfc7231](https://tools.ietf.org/html/rfc7231#section-6.5.4) - `RateLimited` - Limite de requisições foi atingido. Ver seção sobre [limitação de requisições](#section/Seguranca/Limitacao-de-requisicoes) - `InternalServerError` - Condição inesperada ao processar requisição. Ver [rfc7231](https://tools.ietf.org/html/rfc7231#section-6.6.1) - `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. - `RequestIdAlreadyUsed` - Requisição foi feita com mesmo `RequestId` de requisição feita anteriormente, mas com parâmetros diferentes. - `InvalidReason` - Requisição foi feita com uma razão inválida para a operação. **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. - `EntryTaxIdNumberByDifferentOwner` - CPF ou CNPJ do vínculo diferente do CPF ou CNPJ do dono da chave. **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. **Relatos de Infração** - `InfractionReportInvalid` - Existem campos inválidos ao tentar criar o relato de infração. - `InfractionReportOperationInvalid` - Status atual do relato não permite que operação seja feita. - `InfractionReportTransactionNotFound` - A transação definida no relato de infração não foi encontrada. - `InfractionReportTransactionNotSettled` - A transação definida no relato de infração não foi liquidada. - `InfractionReportAlreadyBeingProcessedForTransaction` - Já existe um relato de infração em andamento para a transação informada. - `InfractionReportAlreadyProcessedForTransaction` - Já existe um relato de infração fechado para a transação informada. - `InfractionReportPeriodExpired` - O prazo para o relato de infração sobre a transação expirou. **Devoluções** - `RefundOperationInvalid` - Status atual da devolução não permite que operação seja feita. - `RefundTransactionNotFound` - A transação definida na requisição de devolução não foi encontrada. - `RefundTransactionNotSettled` - A transação definida na requisição de devolução não foi liquidada. - `RefundAlreadyProcessedForTransaction` - Já existe uma requisição de devolução processada para a transação informada. - `RefundAlreadyBeingProcessedForTransaction` - Já existe uma requisição de devolução em processamento para a transação informada. - `RefundPeriodExpired` - O prazo para requerer devolução para a transação expirou. - `TransactionNotRefundable` - A transação informada na requisição não permite devolução. - `RefundInfractionReportNotFound` - Um relato de infração correspondente à transação informada não foi encontrado. servers: - url: https://dict-h.pi.rsfn.net.br:16522/api/v1/ description: Homologação - url: https://dict.pi.rsfn.net.br:16422/api/v1/ description: Produção tags: - name: Directory x-displayName: Diretório description: |- 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 para identificar unicamente um vínculo. Exemplo de vínculo: | Chave | Conta | Dono | |-----------------|---------------------------------------|-----------------------------------| | +5510998765432 | Banco Fictício/Ag.7263-4/Cc.748627-1 | José João da Silva | - name: Key x-displayName: Chave description: |- Uma chave transacional é uma sequência de caracteres que identifica um vínculo de forma única no diretório de identificadores. A existência de uma determinada chave no diretório implica diretamente na existência de um vínculo. Os tipos de chave suportadas atualmente são as seguintes: | Tipo | Exp. regular | Exemplo | Comentário | |---------------|--------------------------------------------------------------------------------------------------------------------|--------------------------------------|---------------------------------------------------------------------------| | CPF | ^\[0-9\]{11}$ | 12345678901 | | | CNPJ | ^\[0-9\]{14}$ | 12345678901234 | | | PHONE | ^\\+\[1-9\]\[0-9\]\d{1,14}$ | +5510998765432 | | | EMAIL | ^[a-z0-9.!#$&'*+\\/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$ | pix@bcb.gov.br | E-mail deve possuir no máximo 77 caracteres e deve ser em minúsculo | | EVP | [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} | 123e4567-e89b-12d3-a456-426655440000 | Endereço Virtual de Pagamento é um tipo de chave é gerado pelo DICT | 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. Apesar da existência de uma chave estar sempre relacionada a um vínculo, é possível a realização de consultas de existência de chaves. - name: Claim x-displayName: Reivindicação description: |- 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. - `COMPLETED` - Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo. **Diagrama de estados** ``` ( OPEN )------->( WAITING_RESOLUTION )------->( CONFIRMED )------->( COMPLETED ) | / | / | / | / v / ( CANCELLED )<------------v ``` **Importante!** Os participantes deverão monitorar as reivindicações fazendo _polling_ períodico no _endpoint_ de [listar reivindicações](#operation/listClaims). A periodicidade adequada dependerá das definições de nível de serviço. Consulte o **Manual de Tempos do Pix**. - name: Reconciliation x-displayName: Reconciliação description: |- A reconciliação permite que o participante identifique inconsistências nos vínculos da sua base de dados interna e o DICT. É possível fazer a verificação de forma agregada, sobre todo o conjunto de vínculos, e a verificação de um vínculo individual. Para permitir que a reconciliação seja feita de forma eficiente e segura, toda operação realizada em cima de um vínculo gera um identificador de conteúdo, ou CID (_content identifier_). O CID é um número de 256 bits que identifica de forma única o vínculo e todos os seus atributos essenciais (ver seção sobre cálculo do CID). Modifições dos dados essenciais do vínculo implicam na modificação do CID associado a ele. A verificação agregada dos vínculos é feita com base no _verificador de sincronismo_ (VSync). O participante pode aferir a igualdade do conjunto de vínculos em seu domínio gerando o VSync (ver seção sobre cálculo do VSync) da sua base e criando uma [verificação de sincronismo](#operation/createSyncVerification). A igualdade dos VSyncs do DICT e do PSP implica, com altíssima probabilidade, que o conjunto de CIDs é igual. Caso os VSyncs sejam diferentes, o conjunto de CIDs é necessariamente diferente, o que significa que há divergências no conjunto de dados de vínculos naquele momento. Ao identificar divergências, PSP poderá [consultar pelo CID](#operation/getEntryByCid), [alterar](#operation/updateEntry), [remover](#operation/deleteEntry) ou [criar](#operation/createEntry) vínculos colocando no campo `Reason` das requisições o valor `RECONCILIATION`. As operações feitas no conjunto de vínculos sob domínio do PSP podem ser acompanhadas de forma contínua no [log de eventos de CIDs](#operation/listCidSetEvents). Para obter uma lista completa dos CIDs no DICT relativos a um tipo de chave, um PSP poderá solicitar a [criação de um arquivo de CIDs](#operation/createCidSetFile). ## Cálculo de CID O CID é calculado da seguinte forma: ``` entryAttributes = keyType "&" key "&" ownerTaxIdNumber "&" ownerName "&" ownerTradeName "&" participant "&" branch "&" accountNumber "&" accountType cidBytes = hmacSha256(requestIdBytes, entryAttributes) cid = lowercase-hexadecimal(cidBytes) ``` Observações: - `entryAttributes` é uma string construída pela junção dos atributos essenciais do vínculo, separados por `&`. Todos atributos são strings codificadas em UTF-8. Atributos nulos são codificados com string em branco, "". - `hmacSha256` é a função HMAC baseada na função de hash SHA-256. - `requestIdBytes` são 16 bytes aleatórios, gerados para identificar a requisição que cria o vínculo, usado como chave na função hmacSha256. - `cid` é a representação hexadecimal, em lowercase, do resultado da função hmacSha256. Exemplo: ``` entryAttributes = 'PHONE&+5511987654321&11122233300&João Silva&&12345678&00001&0007654321&CACC' requestIdBytes = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] cid = '28c06eb41c4dc9c3ae114831efcac7446c8747777fca8b145ecd31ff8480ae88' ``` ## Cálculo do VSync O VSync é resultado da aplicação de bitwise-XOR ('OU' exclusivo bit-a-bit) sobre todos os CIDs de um determinado tipo de chave. Exemplo: ``` cids = ['28c06eb41c4dc9c3ae114831efcac7446c8747777fca8b145ecd31ff8480ae88', '4d4abb9168114e349672b934d16ed201a919cb49e28b7f66a240e62c92ee007f', 'fce514f84f37934bc8aa0f861e4f7392273d71b9d18e8209d21e4192a7842058'] vsync = xor(xor(cids[0], cids[1]), cids[2]) = '996fc1dd3b6b14bcf0c9fe8320eb66d7e2a3fd874ccf767b2e939641b1ea8eaf' ```` Observações: - VSync para um conjunto vazio de CIDs é definido como '0000000000000000000000000000000000000000000000000000000000000000'. - Há três CIDs no exemplo acima, representados em hexadecimal. A operação bitwise-XOR é feita com os CIDs em formato binário. - bitwise-XOR é comutativo, não importa a ordem da sua aplicação. - Para calcular o novo VSync resultante da adição de um CID ao conjunto, basta calcular o XOR desse CID com o VSync atual. O novo VSync resultante da remoção de um CID é calculado da mesma forma. - name: InfractionReport x-displayName: Relatos de Infração description: |- Relatos de infração servem para reportar transações sob suspeita de fraude (FRAUD). Podem ser feitas tanto pelo participante debitado quanto pelo creditado na transação. Depois de criado, o relato deve ser reconhecido pela outra parte da transação (acknowledge) e, após análise, fechado (close) concordando (AGREED) ou discordando (DISAGREED) da infração. O criador do relato pode cancelá-lo a qualquer momento, mesmo depois de fechado. Relatos de infração são criados a partir do identificador da transação realizada no SPI (EndToEndId). O prazo máximo para relatar infração em uma transação está no Manual Operacional do DICT Cada participante deve realizar _polling_ periódico na lista de relatos para verificar se existem novos relatos em que é parte. O recebimento do relato não implica em concordância. Os níveis de serviço exigidos para as operações com relatos de infração estão definidos no **Manual de Tempos do Pix**. Os relatos por motivo de fraude são contabilizados e retornados ao [consultar vínculo](#operation/getEntry). Se for cancelado, o relato deixa de ser contabilizado em REPORTED_FRAUDS durante a consulta de vínculos. - name: Refund x-displayName: Devolução description: |- A solicitação de devolução pode ser realizada pelo PSP do usuário pagador, por iniciativa própria ou a pedido do usuário, nos casos em que exista fundada suspeita do uso do arranjo para a prática de fraude e naqueles em que se verifique falha operacional no sistema de tecnologia da informação de qualquer dos participantes envolvidos na transação. Uma solicitação de devolução pode ter os seguintes estados no DICT: - aberta: a devolução foi solicitada pelo PSP do usuário pagador; - analisada: a solicitação de devolução foi analisada pelo PSP do usuário recebedor e o resultado dessa análise está disponível; ou - cancelada: enquanto a solicitação não estiver no estado “analisada”, o PSP do pagador pode cancelar a solicitação. - name: Statistics x-displayName: Estatísticas description: |- O DICT fornece dados estatísticos de usuários finais, que podem ser consultados através do `TaxIdNumber` (CPF ou CNPJ). As informações providas detalham o total de liquidações, fraudes reportadas e fraudes confirmadas do respectivo usuário consultado. Assim como nos dados estatísticos de chaves, esses totais são consolidados para os últimos 3 dias, 30 dias e 6 meses anteriores ao momento da consulta. - name: Policies x-displayName: Política de Limitação description: |- O controle do fluxo de acesso aos serviços do DICT é realizado por meio de políticas de limitação de requisições, utilizando o algoritmo de [token bucket](https://en.wikipedia.org/wiki/Token_bucket). Para cada política de limitação, existe um balde com configurações específicas, de acordo com a seção [limitação de requisições](#section/Seguranca/Limitacao-de-requisicoes). É possível, a qualquer momento, consultar da lista de políticas de limitação e o estado dos baldes. paths: ######################################################################################################################## ## ENTRIES ######################################################################################################################## '/entries/': post: summary: Criar Vínculo description: |- Cria um novo vínculo de chave com conta transacional. ### Idempotência A operação de criação de vínculo é idempotente. Isso significa que é seguro realizar uma nova tentativa em caso de falhas temporárias, como erros de conexão ou término abrupto de processos. A resposta retornada para uma requisição repetida é equivalente à resposta dada à primeira requisição processada. Para garantir a idempotência da operação, a requisição tem um campo `RequestId`. Esse campo é um [UUID versão 4](https://tools.ietf.org/html/rfc4122#section-4.4) e deve ser único no contexto de um mesmo participante. O `RequestId` fica associado ao vínculo criado e é usado no cálculo do seu CID (ver seção de reconciliação). Uma requisição de criação é considerada repetida quando o CID do vínculo contido na requisição já existe no DICT. Caso seja feita uma requisição com um `RequestId` previamente usado, mas com parâmetros diferentes para o vínculo, será retornado o erro `RequestIdAlreadyUsed`. operationId: createEntry tags: - Directory requestBody: content: application/xml: schema: $ref: '#/components/schemas/CreateEntryRequest' examples: phone: value: $ref: "./examples/entries/CreateEntryRequest.xml" responses: '201': description: Created content: application/xml: schema: $ref: '#/components/schemas/CreateEntryResponse' examples: example: value: $ref: "./examples/entries/CreateEntryResponse.xml" '400': $ref: "#/components/responses/EntryInvalid" '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" '/entries/{Key}': parameters: - schema: $ref: "#/components/schemas/Key" name: Key in: path required: true get: summary: Consultar Vínculo tags: - Directory description: |- Obtém um vínculo contendo os detalhes de conta transacional associados a uma chave de endereçamento. ### Dados anti-fraude A fim de permitir avaliação de risco de fraude, na consulta de vínculos são fornecidos contadores dos seguintes eventos: 1. transações realizadas 2. relatos de infrações 3. relatos de infrações com análise e concordância do creditado Os eventos são agregados por chave, titular (cpf ou cnpj) e conta transacional em 3 janelas temporais: - últimos 3 dias (d3) - últimos 30 dias (d30) - últimos 6 meses, sem contar o mês corrente (m6) Esses contadores tem ciclo de vida independente do vínculo. Eles não são zerados, mesmo que haja desativação da chave ou da conta. Se houver troca de titularidade, ou portabilidade, os dados são herdados pelo novo registro no que couber (titular, chave, ou conta). Os contadores de transações realizadas são quantizados. A escala usada é 0, 1, 5, 10, 50, 100, 500, 1000, 5000... Arrendonda-se o número para cima, por exemplo: 3 → 5, 190 → 500 . ### Limitação de requisições A consulta a chaves está sujeita à política de limitação (_rate-limiting_) de requisições. A limitação funciona com base em cabeçalhos enviados na requisição. Os cabeçalhos de requisição são obrigatórios para todos os tipos de chaves. O parâmetro `PI-PayerId` é o identificador único do usuário final, vinculado a um participante. Requisições vindas de um mesmo usuário, para um mesmo participante, devem usar o mesmo identificador. A partir da versão `1.5.0` da API DICT, este parâmetro deverá ser preenchido com o CPF do usuário final (11 dígitos), no caso de pessoa física, ou com o CNPJ (14 dígitos), no caso de pessoa jurídica. O valor **não deve ser pseudonimizado**, pois a informação passará a ser considerada no rastreamento de possíveis violações de limites. ### Cache Consultas a vínculos podem ter suas respostas _cacheadas_ no PSP, devendo seguir as diretivas contidas no header [`Cache-Control`](https://tools.ietf.org/html/rfc7234#section-5.2). _Importante_: Para fazer uso de cache, clientes HTTP geralmente precisam ser configurados. Não é comum que tenham essa funcionalidade habilitada por padrão. operationId: getEntry parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: |- Identificador único do requisitante, podendo ser: - ISPB do participante (direto ou indireto) que faz a requisição **OU** - 8 primeiros dígitos do CNPJ para Iniciadores de Pagamento required: true - schema: type: string pattern: '^([0-9]{11}|[0-9]{14})$' in: header name: PI-PayerId description: 'Identificador do pagador que originou a requisição. Usado para _rate-limiting_.' required: true - schema: type: string in: header name: PI-EndToEndId description: 'Identificador fim-a-fim do pagamento associado a essa requisição. Corresponde ao campo `EndToEndId` na mensagem pacs.008. Usado para _rate-limiting_.' required: true responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetEntryResponse' examples: example: value: $ref: './examples/entries/GetEntryResponse.xml' '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/RateLimited" put: summary: Atualizar Vínculo tags: - Directory description: |- Atualiza um vínculo. A ser utilizado no cenário de atualização da informação da conta, nome e nome fantasia de um cliente, permanecendo este no mesmo PSP. Somente podem ser atualizadas as informações de conta do vínculo, nome e nome fantasia do cliente. Outras atualizações do vínculo devem ser feitas por exclusão/inclusão do vínculo, portabilidade ou reivindicação de posse, a depender da situação. ### Restrições As seguintes restrições devem ser obedecidas na atualização de vínculo, de acordo com o tipo de chave: - Chaves `EVP` (aleatórias) - É permitida a alteração, porém, apenas com os motivos `BRANCH_TRANSFER` ou `RECONCILIATION`. - Demais chaves - É permitida a alteração com os motivos `USER_REQUESTED`, `BRANCH_TRANSFER` ou `RECONCILIATION`. operationId: updateEntry requestBody: content: application/xml: schema: $ref: '#/components/schemas/UpdateEntryRequest' examples: example: value: $ref: './examples/entries/UpdateEntryRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/UpdateEntryResponse' examples: example: value: $ref: './examples/entries/UpdateEntryResponse.xml' '403': $ref: "#/components/responses/Forbidden" '400': $ref: "#/components/responses/BadRequest" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" '/entries/{Key}/initiator': parameters: - schema: $ref: "#/components/schemas/Key" name: Key in: path required: true get: deprecated: true summary: Consultar Vínculo(PSP iniciador) tags: - Directory description: |- Somente para PSPs iniciadores. Obtém um vínculo contendo os detalhes de conta transacional associados a uma chave de endereçamento. ### Dados anti-fraude Aplica-se as mesmas regras da seção "Dados anti-fraude" de [consultar vínculo](#operation/getEntry). ### Limitação de requisições Assim como na consulta geral de chaves descrita na seção [consultar vínculo](#operation/getEntry), a consulta a chaves do tipo EMAIL e PHONE para PSP's iniciadores também está sujeita à política de limitação (_rate-limiting_) de requisições. A limitação funciona com base em cabeçalhos enviados na requisição, obrigatórios para todos os tipos de chaves, porém, diferentemente das políticas anti scan aplicadas à consulta geral de chaves, as "fichas" **não são** repostas nos "baldes" quando as ordens de pagamento são enviadas. Os baldes possuem apenas a reposição periódica, como descrito na seção [segurança](#section/Seguranca). ### Cache Aplica-se as mesmas recomendações da seção "Cache" de [consultar vínculo](#operation/getEntry). operationId: getEntryInitiator parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true - schema: type: string pattern: '^([0-9]{11}|[0-9]{14})$' in: header name: PI-PayerId description: 'Identificador do pagador que originou a requisição. Usado para _rate-limiting_.' required: true responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetEntryResponse' examples: example: value: $ref: './examples/entries/GetEntryResponseInitiator.xml' '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/RateLimited" '/entries/{Key}/delete': parameters: - schema: $ref: "#/components/schemas/Key" name: Key in: path required: true post: summary: Remover Vínculo operationId: deleteEntry description: Remove um vínculo de chave com conta. tags: - Directory requestBody: content: application/xml: schema: $ref: '#/components/schemas/DeleteEntryRequest' examples: example: value: $ref: './examples/entries/DeleteEntryRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/DeleteEntryResponse' examples: example: value: $ref: './examples/entries/DeleteEntryResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" ######################################################################################################################## ## KEYS ######################################################################################################################## '/keys/check': post: summary: Verificar existência de chaves operationId: checkKeys description: Consulta a existência de um conjunto de chaves no diretório de identificadores. tags: - Key requestBody: content: application/xml: schema: $ref: '#/components/schemas/CheckKeysRequest' examples: example: value: $ref: './examples/keys/CheckKeysRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/CheckKeysResponse' examples: example: value: $ref: './examples/keys/CheckKeysResponse.xml' '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" servers: - url: https://dict-np-h.pi.rsfn.net.br:16532/api-np/v1/ description: Homologação - url: https://dict-np.pi.rsfn.net.br:16432/api-np/v1/ description: Produção ####################################################################################################################### ## CLAIMS ######################################################################################################################## '/claims/': post: summary: Criar Reivindicação description: |- Cria uma nova reivindicação. Essa operação é feita pelo participante reivindicador a pedido do usuário final. O vínculo atual permanece inalterado, até que haja a confirmação pelo PSP doador. Nem todo tipo de chave pode ser reivindicado ou portado. A tabela abaixo define as possibilidades: | compatível? | OWNERSHIP | PORTABILITY | |---------------|:----------:|:------------:| | CPF | | ✓ | | CNPJ | | ✓ | | PHONE | ✓ | ✓ | | EMAIL | ✓ | ✓ | | EVP | | | operationId: createClaim tags: - Claim requestBody: content: application/xml: schema: $ref: '#/components/schemas/CreateClaimRequest' examples: phone-claim: value: $ref: './examples/claims/CreateClaimRequest.xml' responses: '201': description: Created content: application/xml: schema: $ref: '#/components/schemas/CreateClaimResponse' examples: example: value: $ref: './examples/claims/CreateClaimResponse.xml' '400': $ref: "#/components/responses/ClaimInvalid" '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" get: parameters: - description: ISPB do partipante direto ou indireto interessado schema: type: string pattern: '^[0-9]{8}' name: Participant in: query required: true - description: Inclui adicionalmente as reivindicações de participantes indiretos schema: type: boolean default: false name: IncludeIndirectParticipants in: query required: false - description: Restringe a reivindicações em que o participante é doador schema: type: boolean name: IsDonor in: query required: false - description: Restringe a reivindicações em que o participante é reivindicador schema: type: boolean name: IsClaimer in: query required: false - description: Lista de ClaimStatus a serem pesquisados schema: type: array items: $ref: "#/components/schemas/ClaimStatus" name: Status in: query required: false - description: Tipo de reivindicação schema: $ref: "#/components/schemas/ClaimType" name: Type in: query required: false - description: Filtra reivindicações com data-hora de modificação maior ou igual a `modifiedAfter` schema: type: string format: date-time name: ModifiedAfter in: query required: false - description: Filtra reivindicações com data-hora de modificação menor ou igual a `modifiedBefore` schema: type: string format: date-time name: ModifiedBefore in: query required: false - description: Número limite de reivindicações a retornar schema: type: integer default: 20 maximum: 200 name: Limit in: query required: false # - description: Cursor de deslocamento em consultas. Permite o escape linear de registros. # schema: # type: integer # default: 0 # name: Offset # in: query # required: false summary: Listar Reivindicações description: |- Obtém uma lista de reivindicações, ordenada de forma crescente pelo campo `LastModified`, de acordo com os filtros passados. Observações: - Ao percorrer a lista em intervalos de tempo fechados, recomendável para que não se pule nenhum elemento, alguns elementos retornados poderão se repetir. - O comportamento dos filtros `isDonor` e `isClaimer`, quando os valores passados são iguais, é disjuntivo: são retornadas reinvidicações em que o participante é doador OU reivindicador. - A atualização de informações de reinvindicações para listagens é _assíncrona_ em relação às operações de inclusão e atualização de registros, sendo assim, é possível haver um retardo de _5 segundos_ até que os dados incluídos ou alterados constem na consulta. operationId: listClaims tags: - Claim responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/ListClaimsResponse' examples: example: value: $ref: './examples/claims/ListClaimsResponse.xml' '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '/claims/{ClaimId}': parameters: - schema: type: string format: uuid name: ClaimId in: path required: true get: summary: Consultar Reivindicação operationId: getClaim parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true description: Obtém detalhes de uma reivindicação. tags: - Claim responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetClaimResponse' examples: example: value: $ref: './examples/claims/GetClaimResponse.xml' '404': $ref: "#/components/responses/NotFound" '/claims/{ClaimId}/acknowledge': parameters: - schema: type: string format: uuid name: ClaimId in: path required: true post: summary: Receber Reivindicação operationId: acknowledgeClaim description: |- Notifica recebimento pelo participante doador de reivindicação com status `OPEN`. ### Idempotência A operação é idempotente. Caso reivindicação já tenha sido recebida e ela esteja ainda com status `WAITING_RESOLUTION`, será retornada resposta equivalente à primeira requisição. tags: - Claim requestBody: content: application/xml: schema: $ref: '#/components/schemas/AcknowledgeClaimRequest' examples: example: value: $ref: './examples/claims/AcknowledgeClaimRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/AcknowledgeClaimResponse' examples: example: value: $ref: './examples/claims/AcknowledgeClaimResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" '/claims/{ClaimId}/confirm': parameters: - schema: type: string format: uuid name: ClaimId in: path required: true post: summary: Confirmar Reivindicação operationId: confirmClaim description: |- Confirma a operação de reivindicação. Como consequência, vínculo da chave com participante doador é removido. Status deve estar em `WAITING_RESOLUTION`. Para reivindicação de posse, caso razão seja `DEFAULT_OPERATION`, o prazo de resolução (`ResolutionPeriodEnd`) deve ter passado. Se a razão informada for `USER_REQUESTED`, o prazo de encerramento (`CompletionPeriodEnd`) será adiantado para permitir o encerramento imediato pelo reivindicador. A tabela abaixo define, a depender da razão e do tipo, quem pode confirmar.
OWNERSHIP PORTABILITY
Razão Doador Reivindicador Doador Reivindicador
USER_REQUESTED ✓ ✓
ACCOUNT_CLOSURE ✓
DEFAULT_OPERATION ✓
### Idempotência A operação é idempotente. Caso reivindicação já tenha sido confirmada com os mesmos parâmetros e esteja ainda com status `CONFIRMED`, será retornada resposta equivalente à primeira requisição. tags: - Claim requestBody: content: application/xml: schema: $ref: '#/components/schemas/ConfirmClaimRequest' examples: example: value: $ref: './examples/claims/ConfirmClaimRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/ConfirmClaimResponse' examples: example: value: $ref: './examples/claims/ConfirmClaimResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" '/claims/{ClaimId}/cancel': parameters: - schema: type: string format: uuid name: ClaimId in: path required: true post: summary: Cancelar Reivindicação operationId: cancelClaim description: |- Cancela reivindicação. Para reivindicação de posse, status deve ser `WAITING_RESOLUTION` ou `CONFIRMED`. Se razão de cancelamento for `DEFAULT_OPERATION`, prazo de validação de posse da chave do usuário reivindicador deve ter passado. Para portabilidade, status também deve ser `WAITING_RESOLUTION` ou `CONFIRMED`. Se razão de cancelamento for `DEFAULT_OPERATION`, prazo definido pelo campo `ResolutionPeriodEnd` deve ter passado. A tabela abaixo define, a depender da razão e do tipo, quem pode cancelar.
OWNERSHIP PORTABILITY
Razão Doador Reivindicador Doador Reivindicador
USER_REQUESTED ✓ ✓ ✓
ACCOUNT_CLOSURE ✓ ✓
FRAUD ✓ ✓ ✓ ✓
DEFAULT_OPERATION ✓ ✓
RECONCILIATION ✓
### Idempotência A operação é idempotente. Caso reivindicação já tenha sido cancelada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição. tags: - Claim requestBody: content: application/xml: schema: $ref: '#/components/schemas/CancelClaimRequest' examples: example: value: $ref: './examples/claims/CancelClaimRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/CancelClaimResponse' examples: example: value: $ref: './examples/claims/CancelClaimResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" '/claims/{ClaimId}/complete': parameters: - schema: type: string format: uuid name: ClaimId in: path required: true post: summary: Concluir Reivindicação operationId: completeClaim description: |- Conclui reivindicação pelo reivindicador. Como consequência, vínculo da chave com participante reivindicador é criado. Para reivindicação de posse, status deve ser `CONFIRMED` e prazo definido pelo campo `CompletionPeriodEnd` deve ter passado. Para portabilidade, status deve ser `CONFIRMED`. ### Idempotência A operação de conclusão de reivindicação é idempotente. Valem aqui as mesmas considerações feitas sobre esse tema na operação de [Criar Vínculo](#operation/createEntry). tags: - Claim requestBody: content: application/xml: schema: $ref: '#/components/schemas/CompleteClaimRequest' examples: example: value: $ref: './examples/claims/CompleteClaimRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/CompleteClaimResponse' examples: example: value: $ref: './examples/claims/CompleteClaimResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" ####################################################################################################################### ## RECONCILIATION ######################################################################################################################## '/sync-verifications/': post: summary: Verificar Sincronismo description: |- Cria uma verificação de sincronismo para um partipante e tipo de chave. operationId: createSyncVerification tags: - Reconciliation requestBody: content: application/xml: schema: $ref: '#/components/schemas/CreateSyncVerificationRequest' examples: example: value: $ref: './examples/reconciliation/CreateSyncVerificationRequest.xml' responses: '201': description: Created content: application/xml: schema: $ref: '#/components/schemas/CreateSyncVerificationResponse' examples: example: value: $ref: './examples/reconciliation/CreateSyncVerificationResponse.xml' '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" '/cids/files/': post: summary: Criar Arquivo de CIDs description: |- Cria um arquivo contendo todos os CIDs de um determinado tipo de chave do participante. O formato do arquivo é um CID por linha ('\n' como EOL), sem ordem definida. Geração do arquivo é feita assincronamente. operationId: createCidSetFile tags: - Reconciliation requestBody: content: application/xml: schema: $ref: '#/components/schemas/CreateCidSetFileRequest' examples: phone: value: $ref: './examples/reconciliation/CreateCidSetFileRequest.xml' responses: '201': description: Created content: application/xml: schema: $ref: '#/components/schemas/CreateCidSetFileResponse' examples: example: value: $ref: './examples/reconciliation/CreateCidSetFileResponse.xml' '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" '/cids/files/{Id}': parameters: - schema: type: integer name: Id in: path required: true get: summary: Consultar Arquivo de CIDs description: Obtém detalhes do arquivo de CIDs requisitado operationId: getCidSetFile parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true tags: - Reconciliation responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetCidSetFileResponse' examples: example: value: $ref: './examples/reconciliation/GetCidSetFileResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '/cids/events': get: parameters: - description: ISPB do partipante direto ou indireto interessado schema: type: string pattern: '^[0-9]{8}' name: Participant in: query required: true - description: Tipo de chave schema: $ref: "#/components/schemas/KeyType" name: KeyType in: query required: true - description: Filtra eventos com data-hora maior ou igual a `StartTime` schema: type: string format: date-time name: StartTime in: query required: false - description: Filtra eventos com data-hora menor ou igual a `EndTime` schema: type: string format: date-time name: EndTime in: query required: false - description: Número limite de eventos a retornar schema: type: integer name: Limit in: query required: false summary: Listar Eventos de CIDs description: |- Lista os eventos de CIDs para um tipo de chave do participante, ordenados de forma crescente por `Timestamp`. A tabela abaixo resume os eventos de CIDs gerados como conseqüência de cada operação. | Operação | Eventos de CID | |------------------------------------------------------|-----------------------------| | [Criar Vínculo](#operation/createEntry) | adiciona | | [Remover Vínculo](#operation/deleteEntry) | remove | | [Atualizar Vínculo](#operation/updateEntry) | remove e adiciona | | [Confirmar Reivindicação](#operation/confirmClaim) | remove (PSP doador) | | [Concluir Reivindicação](#operation/completeClaim) | adiciona (PSP reivindicador)| Observação: - A atualização de informações de eventos de CIDs para listagens é _assíncrona_ em relação às operações de inclusão e atualização de registros, sendo assim, é possível haver um retardo de _5 segundos_ até que os dados incluídos ou alterados constem na consulta. operationId: listCidSetEvents tags: - Reconciliation responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/ListCidSetEventsResponse' examples: example: value: $ref: './examples/reconciliation/ListCidSetEventsResponse.xml' '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '/cids/entries/{Cid}': parameters: - name: Cid schema: $ref: "#/components/schemas/Cid" in: path required: true - name: PI-RequestingParticipant schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true get: summary: Consultar Vínculo por CID tags: - Reconciliation description: |- Obtém detalhes de um vínculo ativo identificado pelo CID operationId: getEntryByCid responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetEntryByCidResponse' examples: example: value: $ref: './examples/reconciliation/GetEntryByCidResponse.xml' '404': $ref: "#/components/responses/NotFound" '403': $ref: "#/components/responses/Forbidden" ####################################################################################################################### ## INFRACTION-REPORT ####################################################################################################################### '/infraction-reports/': post: summary: Criar Relato de Infração description: |- Cria um relato de infração. Tanto o participante debitado quanto o creditado podem criar um relato de infração. operationId: createInfractionReport tags: - InfractionReport requestBody: content: application/xml: schema: $ref: '#/components/schemas/CreateInfractionReportRequest' examples: SPI - Settled: value: $ref: './examples/infractions/CreateInfractionReportRequest-SPISettled.xml' SPI - Rejected Payee: value: $ref: './examples/infractions/CreateInfractionReportRequest-SPIRejectedPayee.xml' SPI - Rejected Payer: value: $ref: './examples/infractions/CreateInfractionReportRequest-SPIRejectedPayer.xml' INTERNAL - Settled: value: $ref: './examples/infractions/CreateInfractionReportRequest-INTERNALSettled.xml' INTERNAL - Rejected Payee: value: $ref: './examples/infractions/CreateInfractionReportRequest-INTERNALRejectedPayee.xml' INTERNAL - Rejected Payer: value: $ref: './examples/infractions/CreateInfractionReportRequest-INTERNALRejectedPayer.xml' responses: '201': description: Created content: application/xml: schema: $ref: '#/components/schemas/CreateInfractionReportResponse' examples: SPI - Settled: value: $ref: './examples/infractions/CreateInfractionReportResponse-SPISettled.xml' SPI - Rejected Payee: value: $ref: './examples/infractions/CreateInfractionReportResponse-SPIRejectedPayee.xml' SPI - Rejected Payer: value: $ref: './examples/infractions/CreateInfractionReportResponse-SPIRejectedPayer.xml' INTERNAL - Settled: value: $ref: './examples/infractions/CreateInfractionReportResponse-INTERNALSettled.xml' INTERNAL - Rejected Payee: value: $ref: './examples/infractions/CreateInfractionReportResponse-INTERNALRejectedPayee.xml' INTERNAL - Rejected Payer: value: $ref: './examples/infractions/CreateInfractionReportResponse-INTERNALRejectedPayer.xml' '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" get: parameters: - description: ISPB do partipante direto ou indireto interessado schema: type: string pattern: '^[0-9]{8}$' name: Participant in: query required: true - description: Inclui adicionalmente os relatos de infração de participantes indiretos schema: type: boolean default: false name: IncludeIndirectParticipants in: query required: false - description: Restringe a relatos em que o participante é o debitado schema: type: boolean name: IsDebited in: query required: false - description: Restringe a relatos em que o participante é o creditado schema: type: boolean name: IsCredited in: query required: false - description: Lista de Status a serem pesquisados schema: type: array items: $ref: "#/components/schemas/InfractionReportStatus" name: Status in: query required: false - description: Inclui os detalhes do relato (campos Details) schema: type: boolean default: false name: IncludeDetails in: query required: false - description: Filtra relatos com data-hora de modificação maior ou igual a `modifiedAfter` schema: type: string format: date-time name: ModifiedAfter in: query required: false - description: Filtra relatos com data-hora de modificação menor ou igual a `modifiedBefore` schema: type: string format: date-time name: ModifiedBefore in: query required: false - description: Número limite de relatos a retornar schema: type: integer default: 20 maximum: 200 name: Limit in: query required: false # - description: Cursor de deslocamento em consultas. Permite o escape linear de registros. # schema: # type: integer # default: 0 # name: Offset # in: query # required: false summary: Listar Relatos de Infração description: |- Obtém lista de relatos de infração em que o participante é parte. Lista de relatos é ordenada de forma crescente pelo campo `LastModified`. Observação: - A atualização de informações de relatos de infração para listagens é _assíncrona_ em relação às operações de inclusão e atualização de registros, sendo assim, é possível haver um retardo de _5 segundos_ até que os dados incluídos ou alterados constem na consulta. operationId: listInfractionReport tags: - InfractionReport responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/ListInfractionReportsResponse' examples: example: value: $ref: './examples/infractions/ListInfractionReportsResponse.xml' '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '/infraction-reports/{InfractionReportId}': parameters: - schema: type: string format: uuid name: InfractionReportId in: path required: true get: summary: Consultar Relato de Infração operationId: getInfractionReport parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true description: Obtém detalhes de um relato de infração. tags: - InfractionReport responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetInfractionReportResponse' examples: example: value: $ref: './examples/infractions/GetInfractionReportResponse.xml' '404': $ref: "#/components/responses/NotFound" '/infraction-reports/{InfractionReportId}/acknowledge': parameters: - schema: type: string format: uuid name: InfractionReportId in: path required: true post: summary: Receber Relato de Infração operationId: acknowledgeInfractionReport description: |- Notifica recebimento pelo participante. Se o relato foi criado pelo participante debitado, o creditado deve realizar o recebimento. Por outro lado, se o relato foi criado pelo creditado, o debitado deve realizar o recebimento. ### Idempotência A operação é idempotente. Caso o relato já tenha sido recebido e esteja ainda com status `ACKNOWLEDGED`, será retornada resposta equivalente à primeira requisição. tags: - InfractionReport requestBody: content: application/xml: schema: $ref: '#/components/schemas/AcknowledgeInfractionReportRequest' examples: example: value: $ref: './examples/infractions/AcknowledgeInfractionReportRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/AcknowledgeInfractionReportResponse' examples: example: value: $ref: './examples/infractions/AcknowledgeInfractionReportResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" '/infraction-reports/{InfractionReportId}/cancel': parameters: - schema: type: string format: uuid name: InfractionReportId in: path required: true post: summary: Cancelar Relato de Infração operationId: cancelInfractionReport description: |- Cancela o relato de infração. Só pode ser realizada pelo participante que criou o relato. ### Idempotência A operação é idempotente. Caso o relato já tenha sido cancelado com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição. tags: - InfractionReport requestBody: content: application/xml: schema: $ref: '#/components/schemas/CancelInfractionReportRequest' examples: example: value: $ref: './examples/infractions/CancelInfractionReportRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/CancelInfractionReportResponse' examples: example: value: $ref: './examples/infractions/CancelInfractionReportResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" '/infraction-reports/{InfractionReportId}/close': parameters: - schema: type: string format: uuid name: InfractionReportId in: path required: true post: summary: Fechar Relato de Infração operationId: closeInfractionReport description: |- Fecha o relato de infração. Se o relato foi criado pelo participante debitado, o creditado deve realizar o fechamento. Por outro lado, se o relato foi criado pelo creditado, o debitado deve realizar o fechamento. Para fechamento, o status deve ser `ACKNOWLEDGED`. ### Idempotência A operação é idempotente. Caso o relato já tenha sido fechado com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição. tags: - InfractionReport requestBody: content: application/xml: schema: $ref: '#/components/schemas/CloseInfractionReportRequest' examples: example: value: $ref: './examples/infractions/CloseInfractionReportRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/CloseInfractionReportResponse' examples: example: value: $ref: './examples/infractions/CloseInfractionReportResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" ####################################################################################################################### ## REFUND ####################################################################################################################### '/refunds/': post: summary: Criar uma Solicitação de Devolução description: |- Cria uma Solicitação de devolução. Apenas o participante debitado pode criar uma Solicitação de devolução. operationId: createRefund tags: - Refund requestBody: content: application/xml: schema: $ref: '#/components/schemas/CreateRefundRequest' examples: example: value: $ref: './examples/refunds/CreateRefundRequest.xml' responses: '201': description: Created content: application/xml: schema: $ref: '#/components/schemas/CreateRefundResponse' examples: example: value: $ref: './examples/refunds/CreateRefundResponse.xml' '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" get: parameters: - description: ISPB do partipante direto ou indireto responsável schema: type: string pattern: '^[0-9]{8}$' name: Participant in: query required: true - description: Inclui adicionalmente as devoluções de participantes indiretos schema: type: boolean default: false name: IncludeIndirectParticipants in: query required: false - description: Papel do participante na devolução schema: $ref: "#/components/schemas/RefundRequestRole" name: ParticipantRole in: query required: true - description: Lista de Status a serem pesquisados schema: type: array items: $ref: "#/components/schemas/RefundStatus" name: Status in: query required: false - description: Inclui os detalhes da devolução (campos Details) schema: type: boolean default: false name: IncludeDetails in: query required: false - description: Filtra devoluções com data-hora de modificação maior ou igual a `modifiedAfter` schema: type: string format: date-time name: ModifiedAfter in: query required: false - description: Filtra devoluções com data-hora de modificação menor ou igual a `modifiedBefore` schema: type: string format: date-time name: ModifiedBefore in: query required: false - description: Número limite de devoluções a retornar schema: type: integer default: 20 maximum: 200 name: Limit in: query required: false summary: Listar Requisições de Devolução description: |- Obtém lista de requisições de devolução em que o participante é parte. Lista de devoluções é ordenada de forma crescente pelo campo `LastModified`. Observação: - Assim como nas demais listagens, a atualização de informações de requisições de devolução para listagens é _assíncrona_ em relação às operações de inclusão e atualização de registros, sendo assim, é possível haver um retardo de _5 segundos_ até que os dados incluídos ou alterados constem na consulta. operationId: listRefund tags: - Refund responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/ListRefundsResponse' examples: example: value: $ref: './examples/refunds/ListRefundsResponse.xml' '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '/refunds/{RefundId}': parameters: - schema: type: string format: uuid name: RefundId in: path required: true get: summary: Consultar solicitação de devolução operationId: getRefund parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true description: Obtém detalhes de uma solicitação de devolução. tags: - Refund responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetRefundResponse' examples: example: value: $ref: './examples/refunds/GetRefundResponse.xml' '404': $ref: "#/components/responses/NotFound" '/refunds/{RefundId}/cancel': parameters: - schema: type: string format: uuid name: RefundId in: path required: true post: summary: Cancelar solicitação de devolução operationId: cancelRefund description: |- Cancela a Solicitação de devolução. Só pode ser realizada pelo participante que criou a solicitação. ### Idempotência A operação é idempotente. Caso a solicitação já tenha sido cancelada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição. tags: - Refund requestBody: content: application/xml: schema: $ref: '#/components/schemas/CancelRefundRequest' examples: example: value: $ref: './examples/refunds/CancelRefundRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/CancelRefundResponse' examples: example: value: $ref: './examples/refunds/CancelRefundResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" '/refunds/{RefundId}/close': parameters: - schema: type: string format: uuid name: RefundId in: path required: true post: summary: Fechar solicitação de devolução operationId: closeRefund description: |- Fecha a solicitação de devolução. A solicitação só pode ser fechada pelo participante contestado. Para fechamento, o status deve ser `OPEN`. ### Idempotência A operação é idempotente. Caso a solicitação já tenha sido fechada com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição. tags: - Refund requestBody: content: application/xml: schema: $ref: '#/components/schemas/CloseRefundRequest' examples: example: value: $ref: './examples/refunds/CloseRefundRequest.xml' responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/CloseRefundResponse' examples: example: value: $ref: './examples/refunds/CloseRefundResponse.xml' '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '503': $ref: "#/components/responses/ServiceUnavailable" ####################################################################################################################### ## STATISTICS ####################################################################################################################### '/statistics/owner/{TaxIdNumber}': parameters: - schema: type: string pattern: '^[0-9]{11,14}$' example: '12345678901' name: TaxIdNumber in: path required: true get: summary: Consultar Estatísticas de usuário final description: Obtém dados estatísticos de perfil de uso do usuário (liquidações, fraudes reportadas e fraudes confirmadas) operationId: getOwnerStatistics parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true tags: - Statistics responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetOwnerStatisticsResponse' examples: example: value: $ref: './examples/statistics/GetOwnerStatisticsResponse.xml' '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" ####################################################################################################################### ## POLICIES ####################################################################################################################### '/policies/': get: summary: Listar Políticas description: |- Obtém a lista de políticas de limitação de acesso ao DICT para o participante requisitante. Além da lista de políticas, o serviço informa também a categoria em que o participante se encontra, de acordo com a tabela presente no item `ENTRIES_READ_PARTICIPANT_ANTISCAN` da seção [limitação de requisições](#section/Seguranca/Limitacao-de-requisicoes). Cada item da lista detém informações do estado do balde correspondente no momento da consulta. operationId: bucketStates parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true tags: - Policies responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/ListPoliciesResponse' examples: example: value: $ref: './examples/policies/ListPoliciesResponse.xml' '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" servers: - url: https://dict-ratelimit-h.pi.rsfn.net.br:16522/api/v1/ description: Homologação - url: https://dict-ratelimit.pi.rsfn.net.br:16422/api/v1/ description: Produção '/policies/{policy}': parameters: - schema: type: string example: 'ENTRIES_READ_PARTICIPANT_ANTISCAN' name: Policy in: path required: true get: summary: Consultar Política description: Obtém o estado atual do balde do participante para a política informada. operationId: getPolicy parameters: - schema: type: string pattern: '^[0-9]{8}$' example: '12345678' in: header name: PI-RequestingParticipant description: Identificador SPB do participante (direto ou indireto) que faz a requisição. required: true tags: - Policies responses: '200': description: OK content: application/xml: schema: $ref: '#/components/schemas/GetPolicyResponse' examples: example: value: $ref: './examples/policies/GetPolicyResponse.xml' '403': $ref: "#/components/responses/Forbidden" '503': $ref: "#/components/responses/ServiceUnavailable" servers: - url: https://dict-ratelimit-h.pi.rsfn.net.br:16522/api/v1/ description: Homologação - url: https://dict-ratelimit.pi.rsfn.net.br:16422/api/v1/ description: Produção components: schemas: $ref: './schemas.yaml' responses: $ref: './responses.yaml'