diff --git a/changelog.md b/changelog.md index 0a9aad2..33f26e2 100644 --- a/changelog.md +++ b/changelog.md @@ -2,12 +2,17 @@ Mudanças relevantes na API Pix serão documentadas aqui neste documento. -## [2.4.0-rc.0] +## [2.5.0] * Inclusão do atributo `retirada` como campo opcional do objeto `valor` nos endpoints de consulta, criação e revisão da cobrança imediata. O campo pode ser preenchido com os atributos `saque` ou `troco` exclusivamente, detalhados pelos atributos `valor` e `modalidadeAlteracao`. Se apresentarem o campo `modalidadeAlteracao` como valor 1, significa que o usuário pagador pode alterar o valor do saque ou troco. Em sua ausência, assume-se o valor 0, que significa que o valor do saque ou troco não pode ser alterado. * Inclusão do atributo `componentesValor` como campo opcional nos endpoints de consulta Pix para informações da composição do valor final do Pix, este será detalhado por um array de objetos compostos por `tipo` e `valor`. * Formatações gerais de referências a campos, objetos e schemas. +* Inclusão do domínio `natureza` nas devoluções para diferenciamento de devoluções de Pix comuns, ou oriundos de Saque/Troco. +* Referências a https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos trocadas por https://www.bcb.gov.br/estabilidadefinanceira/pix. +## [2.4.0] +* Não houve mudança. Versão seguiu para 2.5.0 para acompanhar o Manual de Iniciação. + ## [2.3.0] * `modalidadeAlteracao` agora é um campo opcional do objeto `valor` no payload da cobrança imediata e nos endpoints de criação e revisão da cobrança imediata. diff --git a/openapi.yaml b/openapi.yaml index 8319434..e767b78 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: title: API Pix - version: "2.4.0.rc-0" + version: "2.5.0" license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0 @@ -1410,7 +1410,7 @@ paths: ``` Este objeto JWS assinado deve ser validado pelo devedor. Maiores detalhes técnicos a respeito da especificação - de segurança encontram-se no __[Manual de Segurança do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos)__. + de segurança encontram-se no __[Manual de Segurança do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pix)__. Conforme pode-se verificar no exemplo acima, o objeto JWS apresenta três fragmentos separados pelo caractere `.` (ponto). São eles: `header`, `payload` e `signature`. @@ -1486,7 +1486,7 @@ paths: ``` Este objeto JWS assinado deve ser validado pelo devedor. Maiores detalhes técnicos a respeito da especificação - de segurança encontram-se no __[Manual de Segurança do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos)__. + de segurança encontram-se no __[Manual de Segurança do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pix)__. Conforme pode-se verificar no exemplo acima, o objeto JWS apresenta três fragmentos separados pelo caractere `.` (ponto). São eles: `header`, `payload` e `signature`. @@ -1760,6 +1760,8 @@ components: saque: valor: "5.00" modalidadeAlteracao: 0 + modalidadeAgente: "AGPSS" + prestadorDoServicoDeSaque: "12345678" chave: "7d9f0335-8dcc-4054-9bf9-0dbd61d36906" cobBody7: summary: "Exemplo de revisão de cobrança com vencimento 1" @@ -1789,6 +1791,8 @@ components: saque: valor: "20.00" modalidadeAlteracao: 1 + modalidadeAgente: "AGPSS" + prestadorDoServicoDeSaque: "12345678" chave: "7d9f0335-8dcc-4054-9bf9-0dbd61d36906" cobBody9: summary: "Exemplo de criação de cobrança imediata com Saque Pix 3" @@ -1803,6 +1807,8 @@ components: troco: valor: "0.00" modalidadeAlteracao: 1 + modalidadeAgente: "AGPSS" + prestadorDoServicoDeSaque: "12345678" chave: "7d9f0335-8dcc-4054-9bf9-0dbd61d36906" loteCobVBody1: summary: "Exemplo de criação de lote de cobranças com vencimento 1" @@ -1996,6 +2002,8 @@ components: saque: valor: "5.00" modalidadeAlteracao: 0 + modalidadeAgente: "AGPSS" + prestadorDoServicoDeSaque: "12345678" chave: "7d9f0335-8dcc-4054-9bf9-0dbd61d36906" cobResponse6: summary: "Exemplo de cobrança imediata com Saque Pix 2" @@ -2021,6 +2029,8 @@ components: saque: valor: "20.00" modalidadeAlteracao: 1 + modalidadeAgente: "AGPSS" + prestadorDoServicoDeSaque: "12345678" chave: "7d9f0335-8dcc-4054-9bf9-0dbd61d36906" cobResponse7: summary: "Exemplo de cobrança imediata com Saque Pix 3" @@ -2046,6 +2056,8 @@ components: troco: valor: "0.00" modalidadeAlteracao: 1 + modalidadeAgente: "AGPSS" + prestadorDoServicoDeSaque: "12345678" chave: "7d9f0335-8dcc-4054-9bf9-0dbd61d36906" loteCobVResponse1: summary: "Exemplo de lote de cobranças com vencimento 1" @@ -2161,10 +2173,12 @@ components: txid: "82433415910c47e5adb6ac3527cca160" valor: "200.00" componentesValor: - - tipo: "ORIGINAL" + original: valor: "180.00" - - tipo: "SAQUE" + saque: valor: "20.00" + modalidadeAgente: "AGPSS" + prestadorDeServicoDeSaque: "12345678" horario: "2020-09-10T13:03:33.902Z" infoPagador: "Saque Pix" webhookBody1: @@ -2665,6 +2679,19 @@ components: title: "Id da Devolução" description: "Id gerado pelo cliente para representar unicamente uma devolução." pattern: "[a-zA-Z0-9]{1,35}" + DevolucaoNatureza: + type: "string" + title: "Natureza da Devolução" + description: | + Indica qual é a natureza da devolução. Uma devolução pode ser relacionada a um Pix comum, ou a um Pix + de Saque ou Troco. Na ausência deste campo a natureza deve ser interpretada como sendo de um Pix comum (ORIGINAL). + + As naturezas são assim definidas: + - `ORIGINAL`: quando a devolução se refere a um Pix comum ou ao valor da compra em um Pix Troco; + - `RETIRADA`: quando a devolução se refere a um Pix Saque ou ao valor do troco em um Pix Troco. + enum: + - "ORIGINAL" + - "RETIRADA" PayloadLocationId: type: "integer" format: "int64" @@ -2806,7 +2833,7 @@ components: * O campo chave determina a chave Pix registrada no DICT que será utilizada para a cobrança. Essa chave será lida pelo aplicativo do PSP do pagador para consulta ao DICT, que retornará a informação que identificará o recebedor da cobrança. * Os tipos de chave podem ser: telefone, e-mail, cpf/cnpj ou EVP. - * O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do [Manual de Padrões para iniciação do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos). + * O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do [Manual de Padrões para iniciação do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pix). maxLength: 77 criacao: type: "string" @@ -2845,14 +2872,15 @@ components: Trata-se da quantidade de dias corridos após calendario.dataDeVencimento, em que a cobrança poderá ser paga. - Aplica-se este campo sobre o vencimento original da cobrança acrescentando-se o - número de dias corridos nos quais a cobrança ainda poderá ser paga, após vencida. - Este valor não se sobrepõe à possibilidade de pagamento em data posterior ao vencimento - original por [força de lei](http://www.planalto.gov.br/ccivil_03/LEIS/L7089.htm). - Nesse sentido, um vencimento determinado para um dia não útil deverá ser acatado - no primeiro dia útil subsequente mesmo que exceda o número de dias definido neste campo. + Sempre que a data de vencimento cair em um fim de semana ou em um feriado para o usuário pagador, + ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente. Todos os campos + que façam referência a esta data (`validadeAposVencimento`; `desconto`; `juros` e `multa`) devem assumir + essa prorrogação, quando for o caso. - Para ilustrar o funcionamento, seguem alguns exemplos: + Para ilustrar o funcionamento, seguem alguns exemplos, onde: + - ``(#)`` representa a data de vencimento; + - ``(*)`` representa a data ajustada em função de dias não úteis; + - os ``()`` correspondem aos dias adicionais de validade para o pagamento. Exemplo A: @@ -2860,9 +2888,14 @@ components: dataDeVencimento: 2020-10-20, terça-feira. validadeAposVencimento: 4 - Tenta-se pagar no dia 2020-10-23, sexta: aceito. - Tenta-se pagar no dia 2020-10-24, sábado: aceito. - Tenta-se pagar no dia 2020-10-25, domingo: negado. + Tenta-se pagar no dia 2020-10-20, terça: aceito. (#)(*) + Tenta-se pagar no dia 2020-10-21, quarta: aceito. (1) + Tenta-se pagar no dia 2020-10-22, quinta: aceito. (2) + Tenta-se pagar no dia 2020-10-23, sexta: aceito. (3) + Tenta-se pagar no dia 2020-10-24, sábado: aceito. + Tenta-se pagar no dia 2020-10-25, domingo: aceito. (Feriado) + Tenta-se pagar no dia 2020-10-26, segunda: aceito. (4) + Tenta-se pagar no dia 2020-10-27, terça: negado. ``` Exemplo B: @@ -2871,10 +2904,10 @@ components: dataDeVencimento: 2020-12-25, sexta-feira, feriado. validadeAposVencimento: 0 - Tenta-se pagar no dia 2020-12-25, sexta: aceito. + Tenta-se pagar no dia 2020-12-25, sexta: aceito. (#)(Feriado) Tenta-se pagar no dia 2020-12-26, sábado: aceito. Tenta-se pagar no dia 2020-12-27, domingo: aceito. - Tenta-se pagar no dia 2020-12-28, segunda: aceito. + Tenta-se pagar no dia 2020-12-28, segunda: aceito. (*) Tenta-se pagar no dia 2020-12-29, terça: negado. ``` @@ -2884,11 +2917,12 @@ components: dataDeVencimento: 2020-12-25, sexta-feira, feriado. validadeAposVencimento: 1 - Tenta-se pagar no dia 2020-12-25, sexta: aceito. + Tenta-se pagar no dia 2020-12-25, sexta: aceito. (#)(Feriado) Tenta-se pagar no dia 2020-12-26, sábado: aceito. Tenta-se pagar no dia 2020-12-27, domingo: aceito. - Tenta-se pagar no dia 2020-12-28, segunda: aceito. - Tenta-se pagar no dia 2020-12-29, terça: negado. + Tenta-se pagar no dia 2020-12-28, segunda: aceito. (*) + Tenta-se pagar no dia 2020-12-29, terça: aceito. (1) + Tenta-se pagar no dia 2020-12-30, quarta: negado. ``` Exemplo D: @@ -2897,28 +2931,68 @@ components: dataDeVencimento: 2020-12-25, sexta-feira, feriado. validadeAposVencimento: 3 - Tenta-se pagar no dia 2020-12-25, sexta: aceito. + Tenta-se pagar no dia 2020-12-25, sexta: aceito. (#)(Feriado) Tenta-se pagar no dia 2020-12-26, sábado: aceito. Tenta-se pagar no dia 2020-12-27, domingo: aceito. - Tenta-se pagar no dia 2020-12-28, segunda: aceito. - Tenta-se pagar no dia 2020-12-29, terça: negado. + Tenta-se pagar no dia 2020-12-28, segunda: aceito. (*) + Tenta-se pagar no dia 2020-12-29, terça: aceito. (1) + Tenta-se pagar no dia 2020-12-30, quarta: aceito. (2) + Tenta-se pagar no dia 2020-12-31, quinta: aceito. (3) + Tenta-se pagar no dia 2021-01-01, sexta: negado. ``` Exemplo E: - ```txt dataDeVencimento: 2020-12-25, sexta-feira, feriado. validadeAposVencimento: 4 - Tenta-se pagar no dia 2020-12-25, sexta: aceito. + Tenta-se pagar no dia 2020-12-25, sexta: aceito. (#)(Feriado) Tenta-se pagar no dia 2020-12-26, sábado: aceito. Tenta-se pagar no dia 2020-12-27, domingo: aceito. - Tenta-se pagar no dia 2020-12-28, segunda: aceito. - Tenta-se pagar no dia 2020-12-29, terça: aceito. - Tenta-se pagar no dia 2020-12-30, quarta: negado. + Tenta-se pagar no dia 2020-12-28, segunda: aceito. (*) + Tenta-se pagar no dia 2020-12-29, terça: aceito. (1) + Tenta-se pagar no dia 2020-12-30, quarta: aceito. (2) + Tenta-se pagar no dia 2020-12-31, quinta: aceito. (3) + Tenta-se pagar no dia 2021-01-01, sexta: aceito. (Feriado) + Tenta-se pagar no dia 2021-01-02, sábado: aceito. + Tenta-se pagar no dia 2021-01-03, domingo: aceito. + Tenta-se pagar no dia 2021-01-04, segunda: aceito. (4) + Tenta-se pagar no dia 2021-01-05, terça: negado. ``` + Exemplo F: + + ```txt + dataDeVencimento: 2021-08-27, sexta-feira. + validadeAposVencimento: 5 + + Tenta-se pagar no dia 2020-08-27, sexta: aceito. (#)(*) + Tenta-se pagar no dia 2020-08-28, sábado: aceito. (1) + Tenta-se pagar no dia 2020-08-29, domingo: aceito. (2) + Tenta-se pagar no dia 2020-08-30, segunda: aceito. (3) + Tenta-se pagar no dia 2020-12-31, terça: aceito. (4) + Tenta-se pagar no dia 2020-12-01, quarta: aceito. (5) + Tenta-se pagar no dia 2020-12-02, quinta: negado. + ``` + + Exemplo G: + + ```txt + dataDeVencimento: 2021-08-28, sábado. + validadeAposVencimento: 5 + + Tenta-se pagar no dia 2020-08-28, sábado: aceito. (#) + Tenta-se pagar no dia 2020-08-29, domingo: aceito. + Tenta-se pagar no dia 2020-08-30, segunda: aceito. (*) + Tenta-se pagar no dia 2020-08-31, terça: aceito. (1) + Tenta-se pagar no dia 2020-09-01, quarta: aceito. (2) + Tenta-se pagar no dia 2020-09-02, quinta: aceito. (3) + Tenta-se pagar no dia 2020-09-03, sexta: aceito. (4) + Tenta-se pagar no dia 2020-09-04, sabado: aceito. + Tenta-se pagar no dia 2020-09-05, domingo: aceito. + Tenta-se pagar no dia 2020-09-06, segunda: aceito. (5) + ``` default: 30 CobApresentacao: type: "object" @@ -3084,6 +3158,7 @@ components: Quando uma cobrança imediata tem uma estrutura de `retirada` ela deixa de ser considerada Pix comum e passa à categoria de Saque Pix. Para que o preenchimento do objeto `retirada` seja considerado válido as seguintes regras se aplicam: + - os campos `modalidadeAgente` e `prestadorDoServicoDeSaque` são de **preenchimento obrigatório**; - quando o `saque` estiver presente a cobrança deve respeitar as seguintes condições: - O campo `valor.original` deve ser preenchido com **valor igual a 0.00 (zero)**; - O campo `valor.modalidadeAlteracao` deve possuir o valor 0 (zero) explicitamente, ou implicitamente (pelo não preenchimento). @@ -3118,7 +3193,9 @@ components: "original": "0.00", "retirada": { "saque": { - "valor": "5.00" + "valor": "5.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } } }, @@ -3130,9 +3207,11 @@ components: "valor": { "original": "0.00", "retirada": { - "saque": { + "saque": { "valor": "5.00", "modalidadeAlteracao": 1, + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } } }, @@ -3145,7 +3224,9 @@ components: "original": "10.00", "retirada": { "troco": { - "valor": "5.00" + "valor": "5.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } } }, @@ -3158,13 +3239,28 @@ components: "original": "10.00", "troco": { "valor": "0.00", - "modalidadeAlteracao": 1 + "modalidadeAlteracao": 1, + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } }, ... ``` #### Exemplos inválidos: Abaixo alguns exemplos que **não são válidos**. Convém observar que esta listagem não tem pretensão de ser completa, sendo tão somente uma referência para alguns erros possíveis. + - **saque sem `modalidadeAgente` e `prestadorDoServicoDeSaque`** + ``` + ... + "valor": { + "original": "0.00", + "retirada": { + "saque": { + "valor": "5.00" + } + } + }, + ... + ``` - **cobrança com saque e troco juntos** (não pode ter os dois ao mesmo tempo) ``` ... @@ -3172,10 +3268,14 @@ components: "original": "100.00", "retirada": { "saque": { - "valor": "50.00" + "valor": "50.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" }, "troco": { - "valor": "30.00" + "valor": "30.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } } }, @@ -3188,7 +3288,9 @@ components: "original": "10.00", "retirada": { "saque": { - "valor": "5.00" + "valor": "5.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } } }, @@ -3201,7 +3303,9 @@ components: "original": "0.00", "retirada": { "troco": { - "valor": "5.00" + "valor": "5.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } } }, @@ -3214,9 +3318,11 @@ components: "original": "0.00", "modalidadeAlteracao": 1, "retirada": { - "saque": { + "saque": { "valor": "5.00", "modalidadeAlteracao": 1, + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } } }, @@ -3229,9 +3335,11 @@ components: "original": "0.00", "modalidadeAlteracao": 1, "retirada": { - "saque": { + "saque": { "valor": "5.00", "modalidadeAlteracao": 1, + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" } } }, @@ -3245,7 +3353,8 @@ components: saque: type: "object" title: "Saque" - required: ["valor"] + required: + ["valor", "modalidadeAgente", "prestadorDoServicoDeSaque"] description: "Informações relacionadas ao saque" properties: valor: @@ -3261,12 +3370,28 @@ components: default: 0 title: "Modalidade de alteração do saque" description: "Modalidade de alteração de valor do saque. Quando não preenchido o valor assumido é o 0 (zero)." + modalidadeAgente: + type: "string" + title: "Modalidade do Agente" + description: | + ##### Modalidade do Agente +
SIGLADescrição
AGTECAgente Estabelecimento Comercial
AGTOTAgente Outra Espécie de Pessoa Jurídica
AGPSSAgente Prestador de Serviço de Saque
+ enum: + - "AGTEC" + - "AGTOT" + - "AGPSS" + prestadorDoServicoDeSaque: + type: "string" + title: "Prestador do Serviço de Saque" + pattern: "\\d{8}" + description: "ISPB do Prestador do Serviço de Saque" - type: "object" properties: troco: type: "object" title: "Troco" - required: ["valor"] + required: + ["valor", "modalidadeAgente", "prestadorDoServicoDeSaque"] description: "Informações relacionadas ao troco" properties: valor: @@ -3282,6 +3407,21 @@ components: default: 0 title: "Modalidade de alteração do troco" description: "Modalidade de alteração de valor do troco. Quando não preenchido o valor assumido é o 0 (zero)." + modalidadeAgente: + type: "string" + title: "Modalidade do Agente" + description: | + ##### Modalidade do Agente +
SIGLADescrição
AGTECAgente Estabelecimento Comercial
AGTOTAgente Outra Espécie de Pessoa Jurídica
AGPSSAgente Prestador de Serviço de Saque
+ enum: + - "AGTEC" + - "AGTOT" + - "AGPSS" + prestadorDoServicoDeSaque: + type: "string" + title: "Prestador do Serviço de Saque" + pattern: "\\d{8}" + description: "ISPB do Prestador do Serviço de Saque" CobPayloadValor: type: "object" title: "Valor da cobrança imediata retornada pelo payload" @@ -3307,6 +3447,7 @@ components: Quando uma cobrança imediata tem uma estrutura de `retirada` ela deixa de ser considerada Pix comum e passa à categoria de Saque Pix. Para que o preenchimento do objeto `retirada` seja considerado válido as seguintes regras se aplicam: + - os campos `modalidadeAgente` e `prestadorDoServicoDeSaque` são de **preenchimento obrigatório**; - quando o `saque` estiver presente a cobrança deve respeitar as seguintes condições: - O campo `valor.original` deve ser preenchido com **valor igual a 0.00 (zero)**; - O campo `valor.modalidadeAlteracao` deve possuir o valor 0 (zero) explicitamente, ou implicitamente (pelo não preenchimento). @@ -3318,148 +3459,181 @@ components: #### Exemplos válidos: Considerando os campos da estrutura `valor` e o predicado 'presente' cujo resultado é verdade quando a estrutura apontada é encontrada temos: - - 1 - **uma cobrança com valor fixo** (condições: valor.original > 0 && valor.modalidadeAlteração = 0 && !presente(valor.retirada)) - ``` - ... - "valor": { - "original": "10.00" - }, - ... - ``` - - 2 - **uma cobrança com valor alterável** (condições: valor.original >= 0.00 && modalidadeAlteração = 1 && !presente(valor.retirada)) - ``` - ... - "valor": { - "original": "10.00", - "modalidadeAlteracao": 1 - }, - ``` - - 3 - **saque com valor fixo** (condições: valor.original = 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.saque) && valor.retirada.saque.valor > 0 && valor.retirada.saque.modalidadeAlteracao = 0) - ``` - ... - "valor": { - "original": "0.00", - "retirada": { - "saque": { - "valor": "5.00" - } - } - }, - ... - ``` - - 4 - **saque com valor alterável** (condições: valor.original = 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.saque) && valor.retirada.saque.valor >= 0 && valor.retirada.saque.modalidadeAlteracao = 1) - ``` - ... - "valor": { - "original": "0.00", - "retirada": { - "saque": { - "valor": "5.00", - "modalidadeAlteracao": 1, + - **uma cobrança com valor fixo** (condições: valor.original > 0 && valor.modalidadeAlteração = 0 && !presente(valor.retirada)) + ``` + ... + "valor": { + "original": "10.00" + }, + ... + ``` + - **uma cobrança com valor alterável** (condições: valor.original >= 0.00 && modalidadeAlteração = 1 && !presente(valor.retirada)) + ``` + ... + "valor": { + "original": "10.00", + "modalidadeAlteracao": 1 + }, + ``` + - **saque com valor fixo** (condições: valor.original = 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.saque) && valor.retirada.saque.valor > 0 && valor.retirada.saque.modalidadeAlteracao = 0) + ``` + ... + "valor": { + "original": "0.00", + "retirada": { + "saque": { + "valor": "5.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } } - } - }, - ... - ``` - - 5 - **cobrança com troco fixo** (condições: valor.original > 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.troco) && valor.retirada.troco.valor > 0 && valor.retirada.troco.modalidadeAlteracao = 0) - ``` - ... - "valor": { - "original": "10.00", - "retirada": { - "troco": { - "valor": "5.00" + }, + ... + ``` + - **saque com valor alterável** (condições: valor.original = 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.saque) && valor.retirada.saque.valor >= 0 && valor.retirada.saque.modalidadeAlteracao = 1) + ``` + ... + "valor": { + "original": "0.00", + "retirada": { + "saque": { + "valor": "5.00", + "modalidadeAlteracao": 1, + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } } - } - }, - ... - ``` - - 6 - **cobrança com troco alterável** (condições: valor.original > 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.troco) && valor.retirada.troco.valor >= 0 && valor.retirada.troco.modalidadeAlteracao = 1) - ``` - ... + }, + ... + ``` + - **cobrança com troco fixo** (condições: valor.original > 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.troco) && valor.retirada.troco.valor > 0 && valor.retirada.troco.modalidadeAlteracao = 0) + ``` + ... "valor": { "original": "10.00", - "troco": { - "valor": "0.00", - "modalidadeAlteracao": 1 + "retirada": { + "troco": { + "valor": "5.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } } }, - ... - ``` + ... + ``` + - **cobrança com troco alterável** (condições: valor.original > 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.troco) && valor.retirada.troco.valor >= 0 && valor.retirada.troco.modalidadeAlteracao = 1) + ``` + ... + "valor": { + "original": "10.00", + "troco": { + "valor": "0.00", + "modalidadeAlteracao": 1, + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } + }, + ... + ``` #### Exemplos inválidos: Abaixo alguns exemplos que **não são válidos**. Convém observar que esta listagem não tem pretensão de ser completa, sendo tão somente uma referência para alguns erros possíveis. - - 1 - **cobrança com saque e troco juntos** (não pode ter os dois ao mesmo tempo) - ``` - ... - "valor": { - "original": "100.00", - "retirada": { - "saque": { - "valor": "50.00" - }, - "troco": { - "valor": "30.00" - } - } - }, - ... - ``` - - 2 - **saque com valor.original maior que 0.00 (zero)** (saque requer valor.original = 0.00) - ``` - ... - "valor": { - "original": "10.00", - "retirada": { - "saque": { - "valor": "5.00" - } - } - }, - ... - ``` - - 3 - **troco com valor.original igual a 0.00 (zero)** (para haver troco tem que haver valor.original > 0.00) - ``` - ... - "valor": { - "original": "0.00", - "retirada": { - "troco": { - "valor": "5.00" - } - } - }, - ... - ``` - - 4 - **saque com valor.original alterável** (não se pode alterar o valor.original na presença do saque) - ``` - ... - "valor": { - "original": "0.00", - "modalidadeAlteracao": 1, - "retirada": { - "saque": { - "valor": "5.00", - "modalidadeAlteracao": 1, + - **saque sem `modalidadeAgente` e `prestadorDoServicoDeSaque`** + ``` + ... + "valor": { + "original": "0.00", + "retirada": { + "saque": { + "valor": "5.00" + } } - } - }, - ... - ``` - - 5 - **troco com valor.original alterável** (não se pode alterar o valor.original na presença do troco) - ``` - ... - "valor": { - "original": "0.00", - "modalidadeAlteracao": 1, - "retirada": { - "saque": { - "valor": "5.00", - "modalidadeAlteracao": 1, + }, + ... + ``` + - **cobrança com saque e troco juntos** (não pode ter os dois ao mesmo tempo) + ``` + ... + "valor": { + "original": "100.00", + "retirada": { + "saque": { + "valor": "50.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + }, + "troco": { + "valor": "30.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } } - } - }, - ... - ``` + }, + ... + ``` + - **saque com valor.original maior que 0.00 (zero)** (saque requer valor.original = 0.00) + ``` + ... + "valor": { + "original": "10.00", + "retirada": { + "saque": { + "valor": "5.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } + } + }, + ... + ``` + - **troco com valor.original igual a 0.00 (zero)** (para haver troco tem que haver valor.original > 0.00) + ``` + ... + "valor": { + "original": "0.00", + "retirada": { + "troco": { + "valor": "5.00", + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } + } + }, + ... + ``` + - **saque com valor.original alterável** (não se pode alterar o valor.original na presença do saque) + ``` + ... + "valor": { + "original": "0.00", + "modalidadeAlteracao": 1, + "retirada": { + "saque": { + "valor": "5.00", + "modalidadeAlteracao": 1, + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } + } + }, + ... + ``` + - **troco com valor.original alterável** (não se pode alterar o valor.original na presença do troco) + ``` + ... + "valor": { + "original": "0.00", + "modalidadeAlteracao": 1, + "retirada": { + "saque": { + "valor": "5.00", + "modalidadeAlteracao": 1, + "modalidadeAgente": "AGPSS", + "prestadorDoServicoDeSaque": "12345678" + } + } + }, + ... + ``` title: "Informações de retirada" type: "object" oneOf: @@ -3468,7 +3642,8 @@ components: saque: type: "object" title: "Saque" - required: ["valor"] + required: + ["valor", "modalidadeAgente", "prestadorDoServicoDeSaque"] description: "Informações relacionadas ao saque" properties: valor: @@ -3484,12 +3659,28 @@ components: default: 0 title: "Modalidade de alteração do saque" description: "Modalidade de alteração de valor do saque. Quando não preenchido o valor assumido é o 0 (zero)." + modalidadeAgente: + type: "string" + title: "Modalidade do Agente" + description: | + ##### Modalidade do Agente +
SIGLADescrição
AGTECAgente Estabelecimento Comercial
AGTOTAgente Outra Espécie de Pessoa Jurídica
AGPSSAgente Prestador de Serviço de Saque
+ enum: + - "AGTEC" + - "AGTOT" + - "AGPSS" + prestadorDoServicoDeSaque: + type: "string" + title: "Prestador do Serviço de Saque" + pattern: "\\d{8}" + description: "ISPB do Prestador do Serviço de Saque" - type: "object" properties: troco: type: "object" title: "Troco" - required: ["valor"] + required: + ["valor", "modalidadeAgente", "prestadorDoServicoDeSaque"] description: "Informações relacionadas ao troco" properties: valor: @@ -3505,6 +3696,21 @@ components: default: 0 title: "Modalidade de alteração do troco" description: "Modalidade de alteração de valor do troco. Quando não preenchido o valor assumido é o 0 (zero)." + modalidadeAgente: + type: "string" + title: "Modalidade do Agente" + description: | + ##### Modalidade do Agente +
SIGLADescrição
AGTECAgente Estabelecimento Comercial
AGTOTAgente Outra Espécie de Pessoa Jurídica
AGPSSAgente Prestador de Serviço de Saque
+ enum: + - "AGTEC" + - "AGTOT" + - "AGPSS" + prestadorDoServicoDeSaque: + type: "string" + title: "Prestador do Serviço de Saque" + pattern: "\\d{8}" + description: "ISPB do Prestador do Serviço de Saque" CobVPayloadValor: type: "object" title: "Valor da cobrança com vencimento calculada retornada pelo payload" @@ -3554,7 +3760,7 @@ components: * O campo chave determina a chave Pix registrada no DICT que será utilizada para a cobrança. Essa chave será lida pelo aplicativo do PSP do pagador para consulta ao DICT, que retornará a informação que identificará o recebedor da cobrança. * Os tipos de chave podem ser: telefone, e-mail, cpf/cnpj ou EVP. - * O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do [Manual de Padrões para iniciação do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos). + * O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do [Manual de Padrões para iniciação do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pix). maxLength: 77 solicitacaoPagador: type: "string" @@ -4229,20 +4435,19 @@ components: pattern: "\\d{1,10}\\.\\d{2}" description: "Valor do Pix." componentesValor: - type: "array" + type: "object" title: "Informações sobre o valor do Pix" description: |- O objetivo dessa estrutura é explicar os elementos de composição do valor do Pix. - Regras da listagem: - - O `valor` do Pix é igual ao somatório dos campos `valor` dos elementos dessa listagem; - - Não pode haver dois elementos com o mesmo tipo; - - Não pode haver simultaneamente um elemento do tipo `SAQUE` e outro elemento do tipo `TROCO`; - - Não há restrição na ordem dos elementos. + Regras da estrutura: + - O `valor` do Pix é igual ao somatório dos campos `valor` das subestruturas que compõem essa estrutura; + - Não pode haver simultaneamente uma subsestrutura do tipo `saque` e outra do tipo `troco`; + - Não há restrição na ordem das subestruturas. Para o caso de uma retirada com saque pode-se retornar - um elemento de tipo=`ORIGINAL` com valor=0.00 (zero) uma vez que a soma será respeitada, ou pode-se omitir - o elemento com tipo=`ORIGINAL`. No caso de um troco o elemento com tipo=`ORIGINAL` vai sempre estar presente. + `original` com valor=0.00 (zero) uma vez que a soma será respeitada, ou pode-se omitir + a subestrutura `original`. No caso de um troco a subsestrutura `original` vai sempre estar presente. #### Exemplos válidos: Exemplo de preenchimentos válidos. @@ -4250,139 +4455,128 @@ components: - **cobrança imediata (sem saque ou troco)** ``` ... - "componentesValor": [ - { - "tipo": "ORIGINAL", + "componentesValor": { + "original": { "valor": "100.00" } - ] + } ... ``` - **cobrança imediata com saque** ``` ... - "componentesValor": [ - { - "tipo": "SAQUE", - "valor": "100.00" + "componentesValor": { + "saque": { + "valor": "100.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" } - ] + } ... ``` - - **cobrança imediata com saque (pode vir tipo=ORIGINAL e valor=0.00)** + - **cobrança imediata com saque (pode vir original.valor=0.00)** ``` ... - "componentesValor": [ - { - "tipo": "ORIGINAL", + "componentesValor": { + "original": { "valor": "0.00" }, - { - "tipo": "SAQUE", - "valor": "100.00" + "saque": { + "valor": "100.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" } - ] + } ... ``` - **cobrança imediata com troco** ``` ... - "componentesValor": [ - { - "tipo": "ORIGINAL", + "componentesValor": { + "original": { "valor": "80.00" }, - { - "tipo": "TROCO", - "valor": "20.00" + "troco": { + "valor": "20.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" } - ] + } ... ``` - **cobrança imediata com troco (ordem não importa)** ``` ... - "componentesValor": [ - { - "tipo": "TROCO", - "valor": "20.00" + "componentesValor": { + "troco": { + "valor": "20.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" }, - { - "tipo": "ORIGINAL", + "original": { "valor": "80.00" } - ] + } ... ``` #### Exemplos inválidos: Exemplos, não exaustivos, de preenchimentos inválidos. - - **`ORIGINAL` com valor maior que 0.00 (zero) e `SAQUE` juntos** + - **`original.valor` maior que 0.00 (zero) e `saque` juntos** ``` ... - "componentesValor": [ - { - "tipo": "ORIGINAL", + "componentesValor": { + "original": { "valor": "80.00" }, - { - "tipo": "SAQUE", - "valor": "20.00" + "saque": { + "valor": "20.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" } - ] + } ... ``` - - **dois elementos de `SAQUE`** + - **dois elementos de `saque`** ``` ... "componentesValor": [ - { - "tipo": "SAQUE", - "valor": "20.00" + "saque": { + "valor": "20.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" }, - { - "tipo": "SAQUE", - "valor": "10.00" + "saque": { + "valor": "10.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" } ] ... ``` - - **cobrança imediata com `SAQUE` e `TROCO`** + - **cobrança imediata com `saque` e `troco`** ``` ... - "componentesValor": [ - { - "tipo": "ORIGINAL", + "componentesValor": { + "original": { "valor": "60.00" }, - { - "tipo": "SAQUE", - "valor": "20.00" + "saque": { + "valor": "20.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" }, - { - "tipo": "TROCO", - "valor": "20.00" + "troco": { + "valor": "20.00", + "modalidadeAgente": "AGPSS", + "prestadorDeServicoDeSaque": "12345678" } - ] + } ... ``` - maximum: 50 - items: - type: "object" - required: ["tipo", "valor"] - properties: - tipo: - type: "string" - title: "Tipo" - description: "Tipo do elemento de composição do valor do Pix." - enum: - - "ORIGINAL" - - "SAQUE" - - "TROCO" - valor: - type: "string" - title: "Valor" - description: "Valor do elemento de composição do Pix." - pattern: "\\d{1,10}\\.\\d{2}" + anyOf: + - $ref: "#/components/schemas/PixValorOriginal" + - $ref: "#/components/schemas/PixValorSaque" + - $ref: "#/components/schemas/PixValorTroco" chave: type: "string" title: "Chave DICT do recebedor" @@ -4391,7 +4585,7 @@ components: * Campo chave do recebedor conforme atribuído na respectiva PACS008. * Os tipos de chave podem ser: telefone, e-mail, cpf/cnpj ou EVP. - * O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do [Manual de Padrões para iniciação do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos). + * O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do [Manual de Padrões para iniciação do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pix). maxLength: 77 horario: type: "string" @@ -4407,6 +4601,72 @@ components: title: "Devoluções" items: $ref: "#/components/schemas/Devolucao" + PixValorOriginal: + type: "object" + properties: + original: + type: "object" + required: ["valor"] + properties: + valor: + type: "string" + title: "Valor original" + description: "Valor original do Pix." + pattern: "\\d{1,10}\\.\\d{2}" + PixValorSaque: + type: "object" + properties: + saque: + type: "object" + required: ["valor", "modalidadeAgente", "prestadorDoServicoDeSaque"] + properties: + valor: + type: "string" + title: "Valor do Saque Pix" + description: "Valor do Saque Pix." + pattern: "\\d{1,10}\\.\\d{2}" + modalidadeAgente: + type: "string" + title: "Modalidade do Agente" + description: | + ##### Modalidade do Agente +
SIGLADescrição
AGTECAgente Estabelecimento Comercial
AGTOTAgente Outra Espécie de Pessoa Jurídica
AGPSSAgente Prestador de Serviço de Saque
+ enum: + - "AGTEC" + - "AGTOT" + - "AGPSS" + prestadorDoServicoDeSaque: + type: "string" + title: "Prestador do Serviço de Saque" + pattern: "\\d{8}" + description: "ISPB do Prestador do Serviço de Saque" + PixValorTroco: + type: "object" + properties: + troco: + type: "object" + required: ["valor", "modalidadeAgente", "prestadorDoServicoDeSaque"] + properties: + valor: + type: "string" + title: "Valor do Troco Pix" + description: "Valor do Troco Pix." + pattern: "\\d{1,10}\\.\\d{2}" + modalidadeAgente: + type: "string" + title: "Modalidade do Agente" + description: | + ##### Modalidade do Agente +
SIGLADescrição
AGTECAgente Estabelecimento Comercial
AGTOTAgente Outra Espécie de Pessoa Jurídica
AGPSSAgente Prestador de Serviço de Saque
+ enum: + - "AGTEC" + - "AGTOT" + - "AGPSS" + prestadorDoServicoDeSaque: + type: "string" + title: "Prestador do Serviço de Saque" + pattern: "\\d{8}" + description: "ISPB do Prestador do Serviço de Saque" Devolucao: type: "object" title: "Devolução" @@ -4427,6 +4687,8 @@ components: title: "Valor a devolver." pattern: "\\d{1,10}\\.\\d{2}" description: "Valor a devolver." + natureza: + $ref: "#/components/schemas/DevolucaoNatureza" horario: type: "object" properties: @@ -4464,6 +4726,8 @@ components: title: "Valor" pattern: "\\d{1,10}\\.\\d{2}" description: "Valor solicitado para devolução. A soma dos valores de todas as devolucões não podem ultrapassar o valor total do Pix." + natureza: + $ref: "#/components/schemas/DevolucaoNatureza" ParametrosConsultaPayloadLocation: type: "object" title: "Parâmetros de consulta de locations" diff --git a/readme.md b/readme.md index 2a32ceb..4c543d5 100644 --- a/readme.md +++ b/readme.md @@ -10,6 +10,6 @@ O branch `master` da API pode ser visualizado __[aqui](https://bacen.github.io/pix-api/index.html)__. -# Release atual: 2.4.0 +# Release atual: 2.5.0 -* A release atual da API Pix pode ser encontrada neste __[link](https://github.com/bacen/pix-api/releases/tag/2.4.0)__. +* A release atual da API Pix pode ser encontrada neste __[link](https://github.com/bacen/pix-api/releases/tag/2.5.0)__.