-
Notifications
You must be signed in to change notification settings - Fork 59
/
openapi.yaml
2351 lines (2128 loc) · 96.1 KB
/
openapi.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
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/<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](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