diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f57ad0..55af45a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,19 @@ Mudanças relevantes na API do DICT serão documentadas aqui. +## [1.0.0] - 2020-09-16 +### Adicionado +- Seção com recomendações de desempenho +- URL de produção +- Possibilidade de cancelar reivindicação de posse pelo reivindicador com razão DEFAULT_OPERATION +- Tipo de erro InfractionReportTransactionNotSettled + +### Alterado +- Atualizadas referências para manual de segurança + +### Removido +- Tipo de erro RequestOnBehalfUnauthorized + ## [1.0.0-RC6] - 2020-08-24 ### Adicionado - _Endpoints_ de InfractionReport diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 09c6fcf..f8d42b5 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: title: DICT API - version: '1.0.0-RC6' + version: '1.0.0' license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0 @@ -10,19 +10,21 @@ info: 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 + 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 especificados no - [manual de segurança PIX](https://www.bcb.gov.br/content/estabilidadefinanceira/forumpireunioes/Anexo%20IV%20-%20Manual%20de%20Seguranca%20PIX%20v2.0.pdf) + 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.0.pdf). ## Assinatura digital Requisições que incluam ou alterem informações no DICT devem ser assinadas com @@ -35,7 +37,7 @@ info: sendo assinado (assinatura é um elemento filho). Para mais detalhes sobre a forma de construir a assinatura, consulte o - [manual de segurança PIX](https://www.bcb.gov.br/content/estabilidadefinanceira/forumpireunioes/Anexo%20IV%20-%20Manual%20de%20Seguranca%20PIX%20v2.0.pdf). + [manual de segurança do Pix](https://www.bcb.gov.br/content/estabilidadefinanceira/cedsfn/Manual%20de%20Seguranca%20do%20PIX%20v3.0.pdf). ## Limitação de requisições @@ -49,6 +51,17 @@ info: 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](#operation/getEntry). + # 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 retro-compatíveis (_backwards-compatibility_): @@ -108,9 +121,6 @@ info: - `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. @@ -184,7 +194,10 @@ info: - Status atual do relato não permite que operação seja feita. - `InfractionReportTransactionNotFound` - - A transação listada no relato de infração não foi encontrada. + - 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. @@ -194,10 +207,12 @@ info: - `InfractionReportPeriodExpired` - O prazo para o relato de infração sobre a transação expirou. - + servers: - - url: https://dict-h.pi.rsfn.net.br:16522/api/v1-rc6/ - description: Servidor de Homologação + - 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 @@ -266,7 +281,7 @@ tags: **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. + das definições de nível de serviço. Consulte o [Manual de Tempos do Pix](https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/IX.ManualdeTemposdoPix-versao1.1.pdf). - name: Reconciliation @@ -350,23 +365,24 @@ tags: x-displayName: Relatos de Infração description: |- Relatos de infração servem para reportar transações sob suspeita de fraude (FRAUD) ou PLD/FT - (AML_CFT). Podem ser feitas tanto pelo participante debitado quanto pelo creditado na + (AML_CFT). 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. + 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 + 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 regulamento do DICT. - Cada participante deve realizar _polling_ periódico na lista de relatos para verificar se + 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. - O tempo máximo de análise também está descrito no regulamento. + 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](https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/IX.ManualdeTemposdoPix-versao1.1.pdf). - As relatos por motivo de fraude e PLD/FT são contabilizadas e retornadas ao - [consultar vínculo](#operation/getEntry). Se for cancelado, o relato deixa de ser contabilizado + As relatos por motivo de fraude e PLD/FT são contabilizadas e retornadas ao + [consultar vínculo](#operation/getEntry). Se for cancelado, o relato deixa de ser contabilizado entre os REPORTED_FRAUDS e REPORTED_AML_CFT durante a consulta de vínculos. paths: @@ -454,7 +470,7 @@ paths: 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 ... + 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 @@ -511,12 +527,12 @@ paths: type: integer example: 30 PI-RateLimit-ParticipantRemaining: - description: Número de requisições disponíveis para que limite associado ao `PI-PayerAccountServicer` seja atingido. + description: Número de requisições disponíveis para que limite associado ao `PI-RequestingParticipant` seja atingido. schema: type: integer example: 100 PI-RateLimit-ParticipantReset: - description: Segundos até que limite associado ao `PI-PayerAccountServicer` seja renovado. + description: Segundos até que limite associado ao `PI-RequestingParticipant` seja renovado. schema: type: integer example: 30 @@ -942,7 +958,9 @@ paths: description: |- Cancela reivindicação. - Para reivindicação de posse, status deve ser `WAITING_RESOLUTION` ou `CONFIRMED`. + 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 deve ser `WAITING_RESOLUTION`. Se razão de cancelamento for `DEFAULT_OPERATION`, prazo definido pelo campo `ResolutionPeriodEnd` deve ter passado. @@ -989,7 +1007,7 @@ paths: DEFAULT_OPERATION - + ✓ ✓ @@ -1271,7 +1289,7 @@ paths: schema: type: string pattern: '^[0-9]{8}$' - example: '12345678' + example: '12345678' in: header description: 'Identificador SPB do participante (direto ou indireto) que faz a requisição.' required: true @@ -1299,12 +1317,12 @@ paths: $ref: "#/components/responses/Forbidden" ####################################################################################################################### -## INFRACTION-REPORT +## INFRACTION-REPORT ####################################################################################################################### '/infraction-reports/': post: - summary: Criar um relato de infração - description: |- + 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: @@ -1464,11 +1482,11 @@ paths: summary: Receber Relato de Infração operationId: acknowledgeInfractionReport description: |- - Notifica recebimento pelo participante. Se o relato foi criado pelo Debitado, o - Creditado deve realizar o acknowledge e vice-versa. + Notifica recebimento pelo participante. Se o relato foi criado pelo participante debitado, o + creditado deve realizar o recebimento e vice-versa. ### Idempotência - A operação é idempotente. Caso o relato já tenha sido recebido e esteja ainda com + 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 @@ -1513,7 +1531,7 @@ paths: 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, + A operação é idempotente. Caso o relato já tenha sido cancelado com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição. tags: @@ -1556,11 +1574,11 @@ paths: summary: Fechar Relato de Infração operationId: closeInfractionReport description: |- - Fecha o relato de Infração. Se o relato foi criado pelo Debitado, o - Creditado deve realizar o acknowledge e vice-versa. + Fecha o relato de infração. Se o relato foi criado pelo participante debitado, o + creditado deve realizar o fechamento e vice-versa. ### Idempotência - A operação é idempotente. Caso o relato já tenha sido fechado com os mesmos parâmetros, + A operação é idempotente. Caso o relato já tenha sido fechado com os mesmos parâmetros, será retornada resposta equivalente à primeira requisição. tags: diff --git a/openapi/schemas.yaml b/openapi/schemas.yaml index 8c2eb6a..3f97137 100644 --- a/openapi/schemas.yaml +++ b/openapi/schemas.yaml @@ -31,7 +31,7 @@ OpeningDate: type: string description: 'Data de abertura da conta. Para o horário, caso não seja conhecido, convenciona-se o início do dia em BRT' - format: date-time + format: date-time required: - Participant - AccountNumber @@ -39,9 +39,9 @@ - OpeningDate Key: type: string - description: Chave de endereçamento + description: Chave de endereçamento maxLength: 77 - example: '12345678901' + example: '12345678901' KeyType: type: string description: Tipo de chave. _Novos tipos podem surgir_. @@ -56,10 +56,10 @@ type: object properties: Type: - type: string + type: string default: NATURAL_PERSON TaxIdNumber: - type: string + type: string description: CPF - Cadastro de Pessoa Física pattern: '^[0-9]{11}$' example: '11122233300' @@ -70,29 +70,29 @@ maxLength: 100 pattern: ^(?=[\u000A\u000D\u0020-\u007E\u0085\u00A0-\u00FF])[\p{L}\- ]+$ required: - - Type + - Type - TaxIdNumber - Name LegalPerson: - type: object + type: object properties: Type: - type: string + type: string default: LEGAL_PERSON TaxIdNumber: - type: string + type: string description: CNPJ - Cadastro Nacional de Pessoa Jurídica example: '11222333000150' pattern: '[0-9]{14}' Name: - type: string + type: string description: Razão social. maxLength: 100 example: Padaria Tres Irmãos Ltda pattern: ^(?=[\u000A\u000D\u0020-\u007E\u0085\u00A0-\u00FF])[\p{L}\d\'\-\&\.\,\/\\ ]+$ TradeName: - type: string - description: Nome fantasia. + type: string + description: Nome fantasia. maxLength: 100 example: Padaria 3 Irmãos pattern: ^(?=[\u000A\u000D\u0020-\u007E\u0085\u00A0-\u00FF])[\p{L}\d\'\-\&\.\,\/\\ ]+$ @@ -107,9 +107,9 @@ KeyOwnershipDate: type: string format: date-time - description: |- - Data a partir da qual o dono tem posse ininterrupta da chave de endereçamento. - Posse da chave aqui é definida pela existência de um vínculo associando a chave ao dono, + description: |- + Data a partir da qual o dono tem posse ininterrupta da chave de endereçamento. + Posse da chave aqui é definida pela existência de um vínculo associando a chave ao dono, possivelmente com contas distintas. EntryCreationDate: type: string @@ -153,7 +153,7 @@ type: string format: date-time description: |- - Caso a chave esteja, no momento, em processo de reivindicação de posse ou portabilidade, + Caso a chave esteja, no momento, em processo de reivindicação de posse ou portabilidade, este campo informa quando o processo começou. required: - Key @@ -643,13 +643,13 @@ RequestId: allOf: - $ref: '#/RequestId' - - description: RequestId utilizado na criação do vínculo + - description: RequestId utilizado na criação do vínculo required: - Cid - Entry - RequestId -##### CLAIM REQ-RESP ##### +##### CLAIM REQ-RESP ##### CreateClaimRequest: type: object @@ -838,7 +838,7 @@ items: $ref: '#/ExtendedClaim' -##### ENTRY REQ-RESP ##### +##### ENTRY REQ-RESP ##### CreateEntryRequest: type: object @@ -949,13 +949,13 @@ Entry: $ref: '#/ExtendedEntry' Statistics: - $ref: '#/Statistics' + $ref: '#/Statistics' required: - Entry - Statistics ##### INFRACTION-REPORT REQ-RESP #### - + CreateInfractionReportRequest: type: object properties: @@ -1110,7 +1110,7 @@ $ref: '#/ExtendedInfractionReport' required: - InfractionReport - + ################# Problem: