├── .github └── workflows │ └── swagger-ui.yml ├── .gitignore ├── changelog.md ├── openapi.yaml └── readme.md /.github/workflows/swagger-ui.yml: -------------------------------------------------------------------------------- 1 | name: Swagger UI -> GitHub Pages 2 | on: 3 | push: 4 | branches: 5 | - master 6 | jobs: 7 | deploy: 8 | runs-on: ubuntu-latest 9 | steps: 10 | - name: Checkout 11 | uses: actions/checkout@v2 12 | - name: Generate Swagger UI 13 | uses: Legion2/swagger-ui-action@v1 14 | with: 15 | github_token: ${{ secrets.GITHUB_TOKEN }} 16 | output: swagger-ui 17 | spec-file: openapi.yaml 18 | - name: Deploy to GitHub Pages 19 | uses: peaceiris/actions-gh-pages@v3 20 | with: 21 | github_token: ${{ secrets.GITHUB_TOKEN }} 22 | publish_dir: swagger-ui 23 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .vscode/ 2 | -------------------------------------------------------------------------------- /changelog.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | Mudanças relevantes na API Pix serão documentadas aqui neste documento. 4 | 5 | ## [2.8.1] 6 | 7 | - Inclusão do campo não obrigatório `rec.recebedor.convenio` no request do `POST /rec` e response do `GET /rec`, `GET /rec/{idRec}` e `POST /rec`. 8 | - Inclusão do parâmetro de busca não obrigatório `convenio` no `GET /rec`, `GET /cobr` e `GET /locrec`. 9 | - Inclusão de exemplo de uso do campo `convenio` no response do `GET /rec/{idRec}`. 10 | - Inclusão da obrigatoriedade do campo `rec.recebedor` no response do GET `/rec` e GET `/rec/{idRec}` . 11 | - Inclusão do campo não obrigatório `cobr.tentativas.rejeicao` no response do `GET /cobr`, `GET /cobr/{txid}` e `POST /cobr/{txid}/retentativa/{data}`. 12 | - Ajuste na descrição dos campos `cobr.ajusteDiaUtil` e `cobr.calendario.dataDeVencimento`. 13 | - Pequenos ajustes de texto na seção `Tratamento de Erros`. 14 | - Inclusão de violações para o endpoint `GET /rec/{idRec}`. 15 | - Ajuste nas violações do endpoint `PATCH /solicrec/{idSolicRec}`. 16 | - Remoção do campo `tipoCob` do response do DELETE `/locrec/{id}/idrec`. 17 | - Ajuste no exemplo do response do DELETE `/locrec/{id}/idrec`. 18 | 19 | ## [2.8.0] 20 | 21 | - Correção do campo `destinatario` de opcional para obrigatório no schema da `Solicitação de Recorrência` do `POST /solicRec`. 22 | - Remoção do campo `recebedor`, desnecessário, do exemplo em `POST /rec`. 23 | - Incluída a obrigatoriedade dos campos `parametros` e `cobrs` no `GET /cobr` para seguir o comportamento similar ao existente para as demais consultas de outras entidades. 24 | - Incluída a obrigatoriedade dos campos `parametros` e `recs` no `GET /rec` para seguir o comportamento similar ao existente para as demais consultas de outras entidades. 25 | - Pequenos ajustes de texto na seção `Tratamento de Erros`. 26 | - Ajuste do exemplo na retentativa quando a política não permite, lançando erro 400. 27 | - Ajuste nas descrições dos identificadores de recorrência e solicitação de recorrência. 28 | 29 | ## [2.7.0] 30 | 31 | - Inclusão do campo `rec.dadosQR` contendo os campos `pixCopiaECola` e `jornada` referentes ao response do GET `/rec/{idRec}?txid={txid}` fornecendo informações complementares relacionadas a respectiva jornada e QRCode com exemplos. 32 | - Remoção do campo `rec.pagador` no response do POST `/rec` e PATCH `/rec/{idRec}`. 33 | - Remoção do campo `rec.cobr` no response do GET `/rec` e GET `/rec/{idRec}` e inserido `idRec` como parâmetro de busca em GET `/cobr`. 34 | - Ajuste no campo `cobr.dadosDevedor` substituído por `cobr.devedor`. 35 | - Ajuste no campo `cobr.contaRecebedor` substituido por `cobr.recebedor`. 36 | - Ajuste no campo `cobr.valor` substituido por `cobr.valor.original`. 37 | - Ajuste no campo `cobr.ajusteDiaUtil` para valor default `true`. 38 | - Inclusão do campo `cobr.vinculo.devedor.nome` no request do PATCH `/cobr/{txid}`. 39 | 40 | 41 | ## [2.7.0-RC1] 42 | 43 | - Inclusão das tags relacionadas ao Pix Automático: 44 | - `RecPayload`: que reúne os endpoints (locations) utilizados pelo software do PSP pagador para recuperar o payload JSON que representa uma recorrência; 45 | - `Rec`: que reúne os endpoints destinados a lidar com o gerenciamento de recorrências; 46 | - `SolicRec`: que reúne os endpoints destinados a lidar com o gerenciamento de solicitações de confirmação de recorrências; 47 | - `CobR`: que reúne os endpoints destinados a lidar com o gerenciamento de cobranças associadas a uma recorrência; 48 | - `PayloadLocationRec`: que reúne os endpoints destinados a lidar com a configuração e a remoção de locations para uso dos payloads de recorrências; 49 | - `WebhookRec`: que reúne os endpoints para o gerenciamento de notificações de recorrências por parte do PSP recebedor ao usuário recebedor; e 50 | - `WebhookCobR`: que reúne os endpoints para o gerenciamento de notificações de cobranças recorrentes por parte do PSP recebedor ao usuário recebedor. 51 | 52 | ## [2.6.3] 53 | 54 | - Inclusão de esclarecimento referente ao domínio `AGPSS` do campo `modalidadeAgente` para Pix Saque e Pix Troco, dispondo que ele deve ser convertido para `AGFSS` na elaboração da mensagem `pacs.008`. Optou-se pela não alteração desse domínio (para `AGFSS`) na API Pix neste momento, ficando a uniformização com o Catálogo de Mensagens do SPI reservada para a próxima *major version* da API Pix. 55 | - Descontos em cobranças com vencimento agora podem ser aplicados para datas **menores ou iguais** à data de vencimento. 56 | - Correção dos exemplos `F` e `G` conforme apontado na issue [[#485](https://github.com/bacen/pix-api/issues/485)]. 57 | - Uniformização das descrições dos campos `/lotecobv/{id}` do request e `id` no response do GET `/lotecobv/{id}` que semânticamente são o mesmo valor. 58 | - Remoção do 'pagador' como campo obrigatório do 'Pix' no *seu respectivo schema*. 59 | 60 | ## [2.6.2] 61 | 62 | - Inclusão do valor `AGTOT` no domínio do campo `valor.retirada.troco.modalidadeAgente`. 63 | - Ajuste da descrição do valor domínio `AGTOT` de 'Agente Outra Espécie de Pessoa Jurídica' para 'Agente Outra Espécie de Pessoa Jurídica ou Correspondente no País'. 64 | - Exclusão do valor `AGPSS` dos domínios dos campos `PixValorTroco.troco.modalidadeAgente` e `CobPayload.valor.retirada.troco.modalidadeAgente`. 65 | - Substituição da expressão 'Prestador de Serviços de Saque' por 'Facilitador de Serviço de Saque' em linha com a nova instrução normativa. 66 | - Correção do exemplo '*cobrança com troco alterável*' para inclusão da estrutura `retirada`. 67 | - Correção do exemplo '*troco com valor.original alterável*', estrutura `retirada.troco` com `AGTOT`. 68 | 69 | ## [2.6.1] 70 | 71 | - Restrição da `modalidadeAgente` do Pix Troco para aceitar somente `AGTEC`. 72 | - Ajustes nos endpoints de Devolução para os diferentes tipos de natureza relacionados aos códigos `BE08` e `FR01`. 73 | - Indicação tamanho máximo do campo `pixCopiaECola` [[#457](https://github.com/bacen/pix-api/issues/457)]. 74 | 75 | ## [2.6.0] 76 | 77 | - Inclusão e referenciamento de "Status do registro de cobrança" onde lia-se "Status da Cobrança" com a descrição da semântica de cada estado. 78 | - Inclusão do campo `pixCopiaECola` (opcional) correspondente às cobranças. 79 | - Na listagem `componentesValor` do objeto `Pix` foram incluídas as informações relativas aos juros, multas, descontos e abatimentos quando o Pix se refere a um pagamento de cobrança com vencimento. Tendo assim o detalhamento em caso de antecipações ou atrasos no pagamento. 80 | - Inclusão do campo `descricao` nos objetos que tratam de Devoluções. 81 | - Ajuste na descrição do campo `natureza` nas Devoluções. 82 | 83 | ## [2.5.0] 84 | 85 | - 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. 86 | Em sua ausência, assume-se o valor 0, que significa que o valor do saque ou troco não pode ser alterado. 87 | - 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`. 88 | - Formatações gerais de referências a campos, objetos e schemas. 89 | - Inclusão do domínio `natureza` nas devoluções para diferenciamento de devoluções de Pix comuns, ou oriundos de Saque/Troco. 90 | - Referências a https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos trocadas por https://www.bcb.gov.br/estabilidadefinanceira/pix. 91 | 92 | ## [2.4.0] 93 | 94 | - Não houve mudança. Versão seguiu para 2.5.0 para acompanhar o Manual de Iniciação. 95 | 96 | ## [2.3.0] 97 | 98 | - `modalidadeAlteracao` agora é um campo opcional do objeto `valor` 99 | no payload da cobrança imediata e nos endpoints de criação e revisão da cobrança imediata. 100 | Se apresentado como valor 1, significa que o usuário pagador pode alterar o valor da cobrança. 101 | Em sua ausência, assume-se o valor 0, que significa que a cobrança não pode ser alterada. 102 | - Não é mais obrigatório que o fragmento de versão v2 esteja presente na _location_. 103 | Não há problema em manter o fragmento; este será considerado como parte integrante da _location_. 104 | - [[#348](https://github.com/bacen/pix-api/issues/348)]: corrige case do padrão de datas de `yyyy-mm-dd` -> `YYYY-MM-DD`. 105 | - [[#354](https://github.com/bacen/pix-api/issues/354)]: Aprimora a descrição do webhook detalhando 106 | a ativação em caso de devolução de um pix. O callback deve ser ativado, também, no caso de serem atingidos 107 | os status finais da devolução: "devolvido" e "não realizado". 108 | - [[#356](https://github.com/bacen/pix-api/issues/356)]: Adiciona dois cenários de erro para o endpoint 109 | `PUT /pix/{e2eid}/devolucao/{id}` na seção de tratamentos de erros. 110 | - [[#357](https://github.com/bacen/pix-api/issues/357)]: aprimora a descrição do campo "motivo" no retorno do endpoint 111 | `​/pix​/{e2eid}​/devolucao​/{id}`. 112 | 113 | ## [2.2.2] 114 | 115 | - [[#331](https://github.com/bacen/pix-api/issues/331)]: O campo `validadeAposVencimento` estava constando como `opcional`, na resposta da criação da cobrança, um efeito colateral da correção correlata ocorrida na release 2.2.1. 116 | - [[#334](https://github.com/bacen/pix-api/issues/334)]: adicionados detalhes a respeito da manipulação da revisão da cobrança em cenário de alteração do _location_. 117 | - [[#342](https://github.com/bacen/pix-api/issues/342)]: removidos trechos duplicados na seção de tratamento de erros. 118 | 119 | ## [2.2.1] 120 | 121 | ### Corrigido: 122 | 123 | - Os campos no objeto "devedor" no request do endpoint `PUT /cobv/{txid}` passam a ser opcionais. 124 | Nem sempre o usuário recebedor tem a posse de todas as informações que constavam como obrigatórias. 125 | - [[#307](https://github.com/bacen/pix-api/issues/307)]: Detalhada a semântica do campo `validadeAposVencimento`. Passa a apresentar redação 126 | detalhando o que ocorre em casos de exceção em que o vencimento da cobrança seja um final de semana 127 | ou um feriado juntamente com a atribuição de um valor pequeno para `validadeAposVencimento`. 128 | - O campo `validadeAposVencimento` estava constando como `required`, o que estava incorreto. 129 | Quando não preenchido, o PSP recebedor assume o valor deste campo como 30, então não há motivos para 130 | o campo ser obrigatório. 131 | - [[#269](https://github.com/bacen/pix-api/issues/269)]. A regex do txid, na parte concernente ao tamanho, nos endpoints /pix e no callback webhook, 132 | estava errada. Corrigida de `{26,35}` para `{1,35}` porque pode haver a presença de pagamentos de QRs 133 | estáticos nesses locais. 134 | - [[#270](https://github.com/bacen/pix-api/issues/270)]: O id do objeto `location` estava especificado como `int32`. De fato, apenas cerca de 2 bilhões 135 | de possibilidades pode acabar muito rápido para grandes emissores de cobranças. Entendemos que o identificador do objeto `lotecobv` 136 | se encaixa na mesma situação. Nesse sentido, alteramos de `int32` para `int64`, 137 | o que não deve causar maiores problemas no momento. 138 | - [[#249](github.com/bacen/pix-api/issues/249)], [[#250](github.com/bacen/pix-api/issues/250)]: Com a entrada do campo "chave" como identificador do webhook, toda a parte referente à paginação 139 | em GET /webhook perde a razão de existir. Nesse sentido, os parâmetros de busca "inicio" e "fim" passam 140 | a ser opcionais. O objeto de paginação "parametros", também torna-se opcional. 141 | - [[#239](github.com/bacen/pix-api/issues/239)]: Conforme relatado nesta discussão, entendemos que 142 | seria interessante, tanto sob o aspecto de segurança quanto sob o aspecto de funcionalidade, que o 143 | objeto pix agregue o atributo "chave", opcional. 144 | - [[#241](https://github.com/bacen/pix-api/issues/241)]: Acrescentamos detalhes em relação à questão do acionamento do webhook por parte do PSP recebedor. 145 | - [[#294](https://github.com/bacen/pix-api/issues/294)]: Erro de ortografia. Na documentação, onde se lê `pixUrlAcessToken` deveria estar escrito `pixUrlAccessToken`. 146 | - [[#273](https://github.com/bacen/pix-api/issues/273)]: O texto do response 202 do endpoint `PATCH lotecobv/{id}` estava erroneamente induzindo o 147 | leitor a pensar que o lote já estava revisado quando, na verdade, estaria apenas em processamento 148 | - [[#273](https://github.com/bacen/pix-api/issues/273)]: Na lista de violações em lotecobv, havia indicações do endpoint `/lotecobv/{txid}`, o que inexiste. O correto é `/lotecobv/{id}`. 149 | - [[#316](https://github.com/bacen/pix-api/issues/316)]: Duas violações específicas foram removidas por questões de performance. 150 | 151 | ## [2.2.0-rc.0] 152 | 153 | ### Adicionado: 154 | 155 | - A API Pix agora estabelece uma série de erros padronizados seguindo a [RFC 7807](https://tools.ietf.org/html/rfc7807) reunidos na seção 156 | "Tratamento de erros". Procuramos ser exaustivos com relação aos possíveis erros semânticos. 157 | - Adicionado o endpoint `PATCH /lotecobv/{id}`. Este endpoint pode ser utilizado quando a intenção do 158 | usuário recebedor for alterar cobranças específicas dentro do conjunto de cobranças criadas no lote em 159 | questão. O endpoint `PUT /lotecobv/{id}` também pode ser utilizado para alterar cobranças, mas deve 160 | ser atribuído na requisição o array exatamente como especificado na requisição originária, o que torna 161 | este endpoint ineficiente no caso em que quer se alterar uma cobrança específica ou poucas dentro de um 162 | array com grande quantidade de cobranças. 163 | 164 | - Incorporadas melhorias de redação em alguns endpoints específicos. 165 | 166 | ### Corrigido: 167 | 168 | - adiciona o atributo `problema` no array `cobsv` no response do endpoint `GET /lotecobv/{id}` 169 | - corrige os status `REMOVIDA_*`, que erroneamente vieram como `REMOVIDO_*` no branch 2.1.X. [#222](https://github.com/bacen/pix-api/issues/222) 170 | 171 | ## [2.1.2] 172 | 173 | - Readme: corrige informações sobre os Manuais 174 | - [#172](https://github.com/bacen/pix-api/issues/172): corrige campos de cobv.devedor na exibição do Payload JSON que não estavam aderentes com o Manual de Iniciação 175 | - [#171](https://github.com/bacen/pix-api/issues/171): corrige descrição do campo cobsv[n].criacao 176 | 177 | ## [2.1.1] 178 | 179 | ### Corrigido: 180 | 181 | - Readme: adiciona menção ao Manual de Padrões para iniciação do Pix. 182 | - [#168](https://github.com/bacen/pix-api/issues/168): corrige descrição do endpoint webhook. 183 | 184 | ## [2.1.0-rc.5, 2.1.1] 185 | 186 | ### Adicionado 187 | 188 | - A API agora apresenta Endpoints para gerenciamento de _Cobranças com Vencimento_ 189 | - Cobranças com vencimento dispõem de seu próprio endpoint 190 | - A API agora apresenta Endpoints para gerenciamento de Lotes de _Cobranças com Vencimento_ 191 | - Adicionado um endpoint para criação de cobrança imediata com txid criado pelo PSP recebedor 192 | - Adicionados Endpoints para o gerenciamento de _Locations_, habilitando o caso de uso "Reuso de Locations". 193 | - Adicionado campo para descrição complementar do status da devolucão [#148](https://github.com/bacen/pix-api/issues/148) 194 | 195 | ### Correções 196 | 197 | - removido o objeto **opcional** pix.pagador [#153](https://github.com/bacen/pix-api/issues/153) 198 | - os webhooks agora são associados a uma chave pix [#120](https://github.com/bacen/pix-api/issues/120) 199 | - os endereços dos endpoints agora apresentam corretamente o fragmento `v2` [#3](https://github.com/bacen/pix-api/issues/3) 200 | 201 | ## [2.1.0-rc.4] 202 | 203 | ### Correções 204 | 205 | - removido endpoint `DELETE /cob/{txid}/loc`, uma vez que o endpoint PATCH cobre a situação. [#108](https://github.com/bacen/pix-api/issues/108) 206 | 207 | ## [2.1.0-rc.3] 208 | 209 | ### Correções 210 | 211 | - removido txid opcional no response do endpoint `POST /loc` [#104](https://github.com/bacen/pix-api/issues/104),[#106](https://github.com/bacen/pix-api/issues/106) 212 | 213 | ## [2.1.0-rc.2] 214 | 215 | ### Correções 216 | 217 | - corrigido array _required_ de CobSolicitada [#100](https://github.com/bacen/pix-api/issues/100) 218 | 219 | ## [2.1.0-rc.1] 220 | 221 | ### Correções 222 | 223 | - corrigido exemplo JWS da tag cobPayload 224 | 225 | ## [2.1.0-rc.0] 226 | 227 | ### Novidades 228 | 229 | - Endpoint para criação de "Locations"; os locations, denotados por `fdqnPSPRecebedor/pixEndpoint/pixUrlAccessToken`, podem ser utilizados para exibir cobranças, de acordo com a vontade do usuário recebedor, mas apenas uma por vez. O location em `PUT /cob/{txid}` é um objeto que pode ser atribuído pelo usuário recebedor. 230 | - A cobrança agora suporta o conceito de "Vencimento", juntamente com as funcionalidades correlatas: juros, multa, descontos, abatimentos e afins. 231 | - O formato do txid foi revisado: o tamanho do txid do estático é diferente do tamanho do txid dinâmico. 232 | 233 | ### Correções 234 | 235 | - Endpoints que criam recursos deveriam retornar 201 created. [#85](https://github.com/bacen/pix-api/issues/85) 236 | - Removidas menções ao o endpoint /refresh. [#48](https://github.com/bacen/pix-api/issues/48) 237 | - API começa em v2 e acompanha a major version [#3](https://github.com/bacen/pix-api/issues/3) 238 | - revisados exemplos inconsistentes. 239 | 240 | ## [2.0.0] 241 | 242 | ### Adicionado 243 | 244 | - Endpoint para criação de Cobranças 245 | - Endpoint para gerenciamento de Cobranças 246 | - Endpoint para consulta parametrizada de Cobranças 247 | - Endpoint para gerenciamento de Pix 248 | - Endpoint para consulta parametrizada de Pix 249 | - Endpoint para solicitar devolução de Pix 250 | - Endpoint para consultar devolução de Pix 251 | - Endpoint para configurar Webhooks 252 | - Endpoint para exibir informações de Webhooks 253 | - Endpoint para cancelar Webhooks 254 | - Endpoint para acesso ao Payload JSON de Cobrança 255 | - Autenticação e Autorização baseada em OAuth2 256 | 257 | ### Removido 258 | 259 | - Recursos para gerenciamento de Documentos 260 | - Configuração de vencimento em calendário 261 | - Configuração de juros, multa e desconto em valor 262 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | [![https://img.shields.io/badge/OpenAPI-valid-brightgreen.svg](https://img.shields.io/badge/OpenAPI-valid-brightgreen.svg)](http://online.swagger.io/validator?url=https://raw.githubusercontent.com/bacen/pix-api/master/openapi.yaml) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) 2 | 3 | # [Especificação da API Pix](https://bacen.github.io/pix-api/index.html) 4 | 5 | * O presente repositório define as especificações funcionais em formato OpenAPI 3.0 referentes à API Pix. 6 | 7 | * Os aspectos de segurança da API Pix transcendem o escopo deste repositório. Maiores detalhes sobre segurança podem ser encontrados no __[Manual de Padrões Para Iniciação do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pix?modalAberto=regulamentacao_pix)__ e no __[Manual de Segurança do Pix](https://www.bcb.gov.br/estabilidadefinanceira/pix?modalAberto=regulamentacao_pix)__. 8 | 9 | # Link para visualização da API Pix 10 | 11 | O branch `master` da API pode ser visualizado __[aqui](https://bacen.github.io/pix-api/index.html)__. 12 | 13 | # Release atual: 2.8.1 14 | 15 | * A release atual da API Pix pode ser encontrada neste __[link](https://github.com/bacen/pix-api/releases/tag/2.8.1)__. 16 | --------------------------------------------------------------------------------