--- agentTools: projectIndex: https://voluti-pix.readme.io/llms.txt --- # Consultar devolução Use este endpoint para consultar uma devolução através de um `e2eid` do Pix e do `id` da devolução. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "2.6.3", "title": "Pix", "description": "A API Pix padroniza serviços oferecidos pelo PSP recebedor no contexto do arranjo Pix,\ncomo criação de cobrança, verificação de Pix recebidos, devolução e consultas.\nOs serviços expostos pelo PSP recebedor permitem ao usuário recebedor estabelecer integração\nde sua automação com os serviços Pix do PSP.\n\n# Evolução da API Pix\n\nA API Pix busca respeitar __[SemVer](https://semver.org/lang/pt-BR/)__. Nesse sentido,\nmudanças compatíveis não devem gerar nova versão _major_.\n\nA versão da API é composta por 4 elementos: _major_, _minor_, _patch_ e _release candidate_.\nA versão `v[x]`que consta no path da URL é o elemento _major_ da versão da API.\nA evolução da versão se dá seguinte forma:\n\n - Major: alterações incompatíveis, com quebra de contrato (v1.0.0 → v2.0.0)\n - Minor: alterações compatíveis, sem quebra de contrato (v1.1.0 → v1.2.0)\n - Patch: bugfixes, esclarecimentos às especificações, sem alterações funcionais (v1.1.1 → v1.1.2)\n - Release candidate: versões de pré-lançamento de qualquer patch futuro, minor ou major (v1.0.0-rc.1 → v1.0.0-rc.22)\n\nAlterações sem quebra de contrato e esclarecimentos às especificações podem ocorrer a qualquer momento.\nClientes devem estar preparados para lidar com essas mudanças sem quebrar.\n\nAs seguintes mudanças são esperadas e consideradas retrocompatíveis:\n\n- Adição de novos recursos na API Pix.\n- Adição de novos parâmetros opcionais a cobranças.\n- Adição de novos campos em respostas da API Pix.\n- Alteração da ordem de campos.\n- Adição de novos elementos em enumerações\n\n\n# Tratamento de erros\n\nA API Pix retorna códigos de status HTTP para indicar sucesso ou falhas das\nrequisições.\n\nCódigos `2xx` indicam sucesso. Códigos `4xx` indicam falhas causadas pelas\ninformações enviadas pelo cliente ou pelo estado atual das entidades. Códigos `5xx`\nindicam problemas no serviço no lado da API Pix.\n\nAs respostas de erro incluem no corpo detalhes do erro seguindo o\n_schema_ da [RFC 7807](https://tools.ietf.org/html/rfc7807).\n\nO campo `type` identifica o tipo de erro e na API Pix segue o padrão:\n\n`https://pix.bcb.gov.br/api/v2/error/`\n\nO padrão acima listado, referente ao campo `type`, não consiste, necessariamente, em uma\nURL que apresentará uma página web válida, ou um endpoint válido, embora possa, futuramente,\nser exatamente o caso. O objetivo primário é apenas e tão somente identificar o tipo de erro.\n\nAbaixo estão listados os tipos de erro e possíveis violações da API Pix.\n\n## Gerais\n\nEsta seção reúne erros que poderiam ser retornados por quaisquer endpoints listados na API Pix.\n\n### `RequisicaoInvalida`\n\n * __Significado__: Requisição inválida.\n * __HTTP Status Code__: [400 Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n\n### `AcessoNegado`\n\n * __Significado__: Requisição de participante autenticado que viola alguma regra de autorização.\n * __HTTP Status Code__: [403 Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3).\n\n### `NaoEncontrado`\n\n * __Significado__: Entidade não encontrada.\n * __HTTP Status Code__: [404 Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n\n### `PermanentementeRemovido`\n\n * __Significado__: Indica que a entidade existia, mas foi permanentemente removida.\n * __HTTP Status Code__: [410 Gone](https://tools.ietf.org/html/rfc7231#section-6.5.9).\n\n### `ErroInternoDoServidor`\n\n * __Significado__: Condição inesperada ao processar requisição.\n * __HTTP Status Code__: [500 Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1).\n\n### `ServicoIndisponivel`\n\n * __Significado__: Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.\n * __HTTP Status Code__: [503 Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4).\n\n### `IndisponibilidadePorTempoEsgotado`\n\n * __Significado__: Indica que o serviço demorou além do esperado para retornar.\n * __HTTP Status Code__: [504 Gateway Timeout](https://tools.ietf.org/html/rfc7231#section-6.6.5).\n\n\n\n## Tag CobPayload \n\nEsta seção reúne erros retornados pelos endpoints organizados sob a tag `CobPayload`.\nEstes erros indicam problemas na tentativa de recuperação, via _location_, do Payload JSON que representa a cobrança.\n\n### `CobPayloadNaoEncontrado`\n\n* __Significado__: a cobrança em questão não foi encontrada para a localização requisitada.\n* __HTTP Status Code__: [404](https://tools.ietf.org/html/rfc7231#section-6.5.4) ou [410](https://tools.ietf.org/html/rfc7231#section-6.5.9).\n* __endpoints__: `GET /{pixUrlAccessToken}`, `GET /cobv/{pixUrlAccessToken}`.\n\nSe a presente localização exibia uma cobrança, mas não a exibirá mais de maneira permanentemente,\npode-se aplicar o HTTP status code [410](https://tools.ietf.org/html/rfc7231#section-6.5.9). Se a presente localização não\nestá exibindo nenhuma cobrança, pode-se utilizar o HTTP status code [404](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n\nUma cobrança pode estar \"expirada\" (`calendario.expiracao`), \"vencida\", \"Concluida\",\nentre outros estados em que não poderia ser efetivamente paga. Nesses casos, é uma liberalidade\ndo PSP recebedor retornar o presente código de erro ou optar por servir o payload de qualquer maneira,\nobjetivando fornecer uma informação adicional ao usuário pagador final a respeito da cobrança.\n\n### `CobPayloadOperacaoInvalida`\n\n* __Significado__: a cobrança existe, mas a requisição é inválida.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `GET /cobv/{pixUrlAccessToken}`.\n\n__Violações__:\n - `codMun` não respeita o _schema_.\n - `codMun` não é um código válido segundo a __[tabela de municípios do IBGE](https://www.ibge.gov.br/explica/codigos-dos-municipios.php)__.\n - `DPP` não respeita o _schema_.\n - `DPP` anterior ao momento presente.\n - `DPP` superior à validade da cobrança em função dos parâmetros `calendario.dataDeVencimento`\n e `calendario.validadeAposVencimento`. Exemplo: `dataDeVencimento` => 2020-12-25,\n `validadeAposVencimento` => 10, `DPP` => 2021-01-05. Neste exemplo, o parâmetro `DPP` é\n inválido considerando o contexto apresentado porque é uma data em que a cobrança\n não poderá ser paga. A cobrança, neste exemplo, não será considerada válida\n a partir da data 2021-01-05.\n\n## Tag Cob\n\nEsta seção reúne erros retornados pelos endpoints organizados sob a tag `Cob`.\nEsses erros indicam problemas no gerenciamento de uma cobrança para pagamento imediato.\n\n### `CobNaoEncontrado`\n\n* __Significado__: Cobrança não encontrada para o txid informado.\n* __HTTP Status Code__: [404](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n* __endpoints__: `[GET|PATCH] /cob/{txid}`.\n\n### `CobOperacaoInvalida`\n\n* __Significado__: a requisição que busca alterar ou criar uma cobrança para pagamento imediato\nnão respeita o _schema_ ou está semanticamente errada.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `[POST|PUT|PATCH] /cob/{txid}`.\n\n__Violações__ para os endpoints `PUT|PATCH /cob/{txid}`:\n - O campo `cob.calendario.expiracao` é igual ou menor que `zero`.\n - O campo `cob.valor.original` não respeita o _schema_.\n - O campo `cob.valor.original` é `zero`.\n - O objeto `cob.devedor` não respeita o _schema_.\n - O campo `cob.chave` não respeita o _schema_.\n - O campo `cob.chave` corresponde a uma conta que não pertence a este usuário recebedor.\n - O campo `solicitacaoPagador` não respeita o _schema_.\n - O objeto `infoAdicionais` não respeita o _schema_.\n - O `location` referenciado por `loc.id` inexiste.\n - O `location` referenciado por `loc.id` já está sendo utilizado por outra cobrança.\n - O `location` referenciado por `cob.loc.id` apresenta tipo \"cobv\" (deveria ser \"cob\").\n\n__Violações__ específicas para o endpoint `PUT /cob/{txid}`:\n - A cobrança já existe, não está no status ATIVA, e a presente requisição busca alterá-la.\n\n__Violações__ específicas para o endpoint `PATCH /cob/{txid}`:\n - A cobrança não está ATIVA, e a presente requisição busca alterá-la.\n - A cobrança está ATIVA, e a presente requisição propõe alterar\n seu status para _REMOVIDA_PELO_USUARIO_RECEBEDOR_ juntamente com outras alterações\n (não faz sentido remover uma cobrança ao mesmo tempo em que se realizam\n alterações que não serão aproveitadas).\n - o campo `cob.status` não respeita o _schema_.\n\n### `CobConsultaInvalida`\n\n* __Significado__: os parâmetros de consulta à lista de cobranças para pagamento imediato\nnão respeitam o _schema_ ou não fazem sentido semanticamente.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `GET /cob` e `GET /cob/{txid}`.\n\n__Violações__ específicas para o endpoint `GET /cob`:\n - algum dos parâmetros informados para a consulta não respeita o _schema_.\n - o _timestamp_ representado pelo parâmetro `fim` é anterior ao timestamp\n representado pelo parâmetro `inicio`.\n - ambos os parâmetros `cpf` e `cnpj` estão preenchidos.\n - o parâmetro `paginacao.paginaAtual` é negativo.\n - o parâmetro `paginacao.itensPorPagina` é negativo.\n\n__Violações__ específicas para o endpoint `GET /cob/{txid}`:\n - o parâmetro `revisao` corresponde a uma revisão inexistente para a cobrança\n apontada pelo parâmetro `txid`.\n\n## Tag CobV\n\nEsta seção reúne erros retornados pelos endpoints organizados sob a tag `CobV`.\nEsses erros indicam problemas no gerenciamento de uma cobrança com vencimento.\n\n### `CobVNaoEncontrada`\n\n* __Significado__: Cobrança com vencimento não encontrada para o txid informado.\n* __HTTP Status Code__: [404](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n* __endpoints__: `[GET|PATCH] /cobv/{txid}`.\n\n### `CobVOperacaoInvalida`\n\n* __Significado__: a requisição que busca alterar ou criar uma cobrança com vencimento\nnão respeita o _schema_ ou está semanticamente errada.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `[PUT|PATCH] /cobv/{txid}`.\n\n__Violações__ para os endpoints `PUT|PATCH /cobv/{txid}`:\n - Este `txid` está associado a um lote e no referido lote, o status desta cobrança está atribuído como\n \"EM_PROCESSAMENTO\" ou \"NEGADA\".\n - O campo `cobv.calendario.dataDeVencimento` é anterior à data de criação da cobrança.\n - O campo `cobv.calendario.validadeAposVencimento` é menor do que zero.\n - O objeto `cobv.devedor` não respeita o _schema_.\n - O objeto `cobv.devedor` não respeita o _schema_.\n - O campo `cobv.chave` não respeita o _schema_.\n - O campo `cobv.chave` corresponde a uma conta que não pertence a este usuário recebedor.\n - O campo `solicitacaoPagador` não respeita o _schema_.\n - O objeto `infoAdicionais` não respeita o _schema_.\n - O localização referenciado por `cobv.loc.id` inexiste.\n - O localização referenciado por `cobv.loc.id` já está sendo utilizado por outra cobrança.\n - O localização referenciado por `cobv.loc.id` apresenta tipo \"cob\" (deveria ser \"cobv\").\n - O campo `cobv.valor.original` não respeita o _schema_.\n - O campo `cobv.valor.original` apresenta o valor `zero`.\n - O objeto `cobv.valor.multa` não respeita o _schema_.\n - O objeto `cobv.valor.juros` não respeita o _schema_.\n - O objeto `cobv.valor.abatimento` não respeita o _schema_.\n - O objeto `cobv.valor.desconto` não respeita o _schema_.\n - O objeto `cobv.valor.abatimento` representa um valor maior ou igual ao valor da\n cobrança original ou maior ou igual a 100%.\n - O objeto `cobv.valor.desconto` apresenta algum elemento de desconto que representa um valor maior ou\n igual ao valor da cobrança original ou maior ou igual a 100%.\n - O objeto `cobv.valor.desconto` apresenta algum elemento cuja data seja posterior à data de vencimento\n representada por `calendario.dataDeVencimento`.\n - O objeto `cobv.valor.desconto` apresenta modalidade no valor `1` ou `2`,\n porém `cobv.valor.desconto.valorPerc` encontra-se preenchido\n - O objeto `cobv.valor.desconto` apresenta modalidade no valor `1` ou `2`, porém\n o array `cobv.valor.desconto.descontoDataFixa` está vazio ou nulo.\n - O objeto `cobv.valor.desconto` apresenta modalidade nos valores de `3` a `6`, porém\n o elemento `cobv.valor.desconto.valorPerc` não está preenchido.\n - O objeto `cobv.valor.desconto` apresenta modalidade nos valores de `3` a `6`, porém\n o elemento `cobv.valor.desconto.descontoDataFixa` está preenchido ou não nulo.\n\n\n\n__Violações__ específicas para o endpoint `PUT /cobv/{txid}`:\n - A cobrança já existe, não está ATIVA, e a presente requisição busca alterá-la\n\n__Violações__ específicas para o endpoint `PATCH /cobv/{txid}`:\n - A cobrança não está ATIVA, e a presente requisição busca alterá-la\n - A cobrança está ATIVA, e a presente requisição propõe alterar\n seu status para _REMOVIDA_PELO_USUARIO_RECEBEDOR_ juntamente com outras alterações\n (não faz sentido remover uma cobrança ao mesmo tempo em que se realizam\n alterações que não serão aproveitadas).\n - o campo `cob.status` não respeita o _schema_.\n\n### `CobVConsultaInvalida`\n\n* __Significado__: os parâmetros de consulta à lista de cobranças com vencimento não respeitam o schema\nou não fazem sentido semanticamente.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `GET /cobv` e `GET /cobv/{txid}`.\n\n__Violações__ específicas para o endpoint `GET /cobv`:\n - algum dos parâmetros informados para a consulta não respeita o _schema_.\n - o _timestamp_ representado pelo parâmetro `fim` é anterior ao timestamp\n representado pelo parâmetro `inicio`.\n - ambos os parâmetros `cpf` e `cnpj` estão preenchidos.\n - o parâmetro `paginacao.paginaAtual` é negativo.\n - o parâmetro `paginacao.itensPorPagina` é negativo.\n\n__Violações__ específicas para o endpoint `GET /cobv/{txid}`:\n - o parâmetro `revisao` corresponde a uma revisão inexistente para a cobrança\n apontada pelo parâmetro `txid`.\n\n## Tag LoteCobV\nEsta seção reúne erros referentes a endpoints que tratam do gerenciamento de lotes de cobrança.\n\n### `LoteCobVNaoEncontrado`\n* __Significado__: Lote não encontrado para o `id` informado.\n* __HTTP Status Code__: [404](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n* __endpoints__: `[GET|PATCH] /lotecobv/{id}`.\n\n### `LoteCobVOperacaoInvalida`\n* __Significado__: a requisição que busca alterar ou criar um lote de cobranças com vencimento\nnão respeita o _schema_ ou está semanticamente errada.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `[PUT|PATCH] /lotecobv/{id}`.\n\n__Violações__ para os endpoints `PUT|PATCH /lotecobv/{id}`:\n - O campo `loteCobV.descricao` não respeita o _schema_.\n - O objeto `loteCobV.cobsV` não respeita o _schema_.\n\n__Violações__ para o endpoint `PUT /lotecobv/{id}`:\n - a presente requisição tenta criar um conjunto de cobranças dentre as quais pelo menos\n uma cobrança já encontra-se criada.\n - a presente requisição busca alterar um lote já existente, entretanto contém um array de\n solicitações de alteração de cobranças que não referencia exatamente as mesmas cobranças\n referenciadas pela requisição original que criou o lote.\n Uma vez criado um lote, não se pode remover ou adicionar solicitações de\n criação ou alteração de cobranças a este lote.\n\n__Violações__ para o endpoint `PATCH /lotecobv/{id}`:\n - a presente requisição busca alterar um lote já existente e contém, no `array`\n de cobranças representado por `cobsv`, uma cobrança não existente no array de cobranças\n atribuído pela requisição original que criou o lote.\n Uma vez criado um lote, não se pode remover ou adicionar cobranças a este lote.\n\n__Violações__ para os endpoints `GET /lotecobv/{id}`:\n - __observação__: para cada elemento do array `cobsv`, retornado por este endpoint, caso a requisição de criação de cobrança esteja em\n status \"NEGADA\", o atributo `problema` deste elemento deve ser preenchido respeitando\n o [schema](https://tools.ietf.org/html/rfc7807) referenciado pela API Pix.\n - o preenchimento do atributo `problema`, conforme descrito acima, segue o mesmo regramento dos\n erros especificados para os endpoints `[PUT/PATCH /cobv/{txid}]`, de maneira a possibilitar, ao\n usuário recebedor, entender qual foi a violação cometida ao se tentar criar\n a cobrança referenciada por este elemento do array `cobsv`.\n\n### `LoteCobVConsultaInvalida`\n\n* __Significado__: os parâmetros de consulta à lista de lotes de cobrança com vencimento\nnão respeitam o _schema_ ou não fazem sentido semanticamente.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `GET /lotecobv` e `GET /lotecobv/{id}`.\n\n__Violações__ específicas para o endpoint `GET /lotecobv`:\n - algum dos parâmetros informados para a consulta não respeitam o _schema_.\n - o _timestamp_ representado pelo parâmetro `fim` é anterior ao timestamp\n representado pelo parâmetro `inicio`.\n - o parâmetro `paginacao.paginaAtual` é negativo.\n - o parâmetro `paginacao.itensPorPagina` é negativo.\n\n## Tag PayloadLocation\nEsta seção reúne erros referentes a endpoints que tratam do gerenciamento de _locations_.\n\n### `PayloadLocationNaoEncontrado`\n* __Significado__: _Location_ não encontrada para o `id` informado.\n* __HTTP Status Code__: [404](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n* __endpoints__: `[GET|PATCH] /loc/{id}`, `DELETE /loc/{id}/txid`.\n\n### `PayloadLocationOperacaoInvalida`\n\n* __Significado__: a presente requisição busca criar uma localização sem respeitar o _schema_ estabelecido.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `POST /loc`.\n\n__Violações__ para o endpoint `POST /loc`:\n - o campo `tipoCob` não respeita o _schema_.\n\n### `PayloadLocationConsultaInvalida`\n\n* __Significado__: os parâmetros de consulta à lista de _locations_ não respeitam\no _schema_ ou não fazem sentido semanticamente.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `GET /loc` e `GET /loc/{id}`.\n\n__Violações__ específicas para o endpoint `GET /loc`:\n - algum dos parâmetros informados para a consulta não respeitam o _schema_.\n - o _timestamp_ representado pelo parâmetro `fim` é anterior ao timestamp\n representado pelo parâmetro `inicio`.\n - o parâmetro `paginacao.paginaAtual` é negativo.\n - o parâmetro `paginacao.itensPorPagina` é negativo.\n\n## Tag Pix\n\nReúne erros em endpoints de gestão de Pix recebidos e solicitação de devoluções.\n\n### `PixNaoEncontrado`\n\n* __Significado__: Pix não encontrada para o `e2eid` informado.\n* __HTTP Status Code__: [404](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n* __endpoints__: `GET /pix/{e2eid}`\n\n### `PixDevolucaoNaoEncontrada`\n\n* __Significado__: devolução representada por {id} não encontrada para o `e2eid` informado.\n* __HTTP Status Code__: [404](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n* __endpoints__: `GET /pix/{e2eid}/devolucao/{id}`\n\n### `PixConsultaInvalida`\n\n* __Significado__: os parâmetros de consulta à lista de Pix recebidos não respeitam o schema\nou não fazem sentido semanticamente.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `GET /pix`.\n\n__Violações__ específicas para o endpoint `GET /pix`:\n - algum dos parâmetros informados para a consulta não respeita o _schema_.\n - o _timestamp_ representado pelo parâmetro `fim` é anterior ao timestamp\n representado pelo parâmetro `inicio`.\n - ambos os parâmetros `cpf` e `cnpj` estão preenchidos.\n - o parâmetro `paginacao.paginaAtual` é negativo.\n - o parâmetro `paginacao.itensPorPagina` é negativo.\n\n### `PixDevolucaoInvalida`\n\n* __Significado__: a presente requisição de devolução não respeita o _schema_ ou não faz sentido semanticamente.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `PUT /pix/{e2eid}/devolucao/{id}`.\n\n__Violações__ específicas para o endpoint `PUT /pix/{e2eid}/devolucao/{id}`:\n - O campo `devolucao.valor` não respeita o _schema_.\n - A presente requisição de devolução, em conjunto com as demais prévias devoluções,\n se aplicável, excederia o valor do Pix originário.\n - A presente requisição de devolução apresenta um `{id}` já utilizado por outra requisição de\n devolução para o `{e2eid}` em questão.\n - A presente requisição de devolução viola a janela de tempo permitida para solicitações de devoluções\n de um Pix (hoje estabelecida como 90 dias desde a data de liquidação original do pix).\n\n## Tag Webhook\nReúne erros dos endpoints que tratam do gerenciamento dos Webhooks da API Pix.\n\n### `WebhookOperacaoInvalida`\n* __Significado__: a presente requisição busca criar um webhook sem respeitar o _schema_ ou,\nainda, apresenta semântica inválida.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `PUT /webhook/{chave}`.\n\n__Violações__ para o endpoint `PUT /webhook/{chave}`:\n - o parâmetro {chave} não corresponde a uma chave DICT válida.\n - o parâmetro {chave} não corresponde a uma chave DICT pertencente a este usuário recebedor.\n - Campo webhook.webhookUrl não respeita o _schema_.\n\n### `WebhookNaoEncontrado`\n\n* __Significado__: o webhook denotado por {chave} não encontra-se estabelecido.\n* __HTTP Status Code__: [404](https://tools.ietf.org/html/rfc7231#section-6.5.4).\n* __endpoints__: `GET /webhook/{chave}`, `DELETE /webhook/{chave}`\n\n### `WebhookConsultaInvalida`\n\n* __Significado__: os parâmetros de consulta à lista de webhooks ativados não respeitam o schema\nou não fazem sentido semanticamente.\n* __HTTP Status Code__: [400](https://tools.ietf.org/html/rfc7231#section-6.5.1).\n* __endpoints__: `GET /webhook`.\n\n__Violações__ específicas para o endpoint `GET /webhook`:\n - algum dos parâmetros informados para a consulta não respeita o _schema_.\n - o _timestamp_ representado pelo parâmetro `fim` é anterior ao timestamp\n representado pelo parâmetro `inicio`.\n - o parâmetro `paginacao.paginaAtual` é negativo.\n - o parâmetro `paginacao.itensPorPagina` é negativo.\n\n > #### __Observação__:🚧\n > O ambiente de produção será enviado ao cliente.", "contact": { "name": "Suporte Pix BCB", "email": "suporte.pix@bcb.gov.br", "url": "https://www.bcb.gov.br/estabilidadefinanceira/pix" }, "license": { "url": "http://www.apache.org/licenses/LICENSE-2.0", "name": "Apache 2.0" } }, "servers": [ { "url": "https://api.pix.voluti.com.br", "description": "Ambiente de Produção" } ], "paths": { "/pix/{e2eid}/devolucao/{id}": { "get": { "tags": [ "Gerenciamento de PIX" ], "summary": "Consultar devolução", "description": "Use este endpoint para consultar uma devolução através de um `e2eid` do Pix e do `id` da devolução.", "parameters": [ { "name": "e2eid", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EndToEndId" } }, { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DevolucaoId" } } ], "responses": { "200": { "description": "Dados da devolução.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Devolucao" }, "examples": { "retorno1": { "$ref": "#/components/examples/devolucaoResponse1" }, "retorno2": { "$ref": "#/components/examples/devolucaoResponse2" } } } } }, "403": { "$ref": "#/components/responses/AcessoNegado" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "503": { "$ref": "#/components/responses/ServicoIndisponivel" } }, "security": [ { "OAuth2": [ "pix.read" ] } ], "servers": [ { "url": "api.pix-h.voluti.com.br", "description": "Ambiente de Homologação" } ] } } }, "tags": [ { "name": "Gerenciamento de PIX", "description": "reúne endpoints destinados a lidar com gerenciamento de Pix recebidos.", "x-displayName": "Gerenciamento de Pix recebidos" } ], "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "clientCredentials": { "scopes": { "cob.write": "Permissão para alteração de cobranças imediatas", "cob.read": "Permissão para consulta de cobranças imediatas", "cobv.write": "Permissão para alteração de cobranças com vencimento", "cobv.read": "Permissão para consulta de cobranças com vencimento", "lotecobv.write": "Permissão para alteração de lotes de cobranças com vencimento", "lotecobv.read": "Permissão para consulta de lotes de cobranças com vencimento", "pix.write": "Permissão para alteração de Pix", "pix.read": "Permissão para consulta de Pix", "webhook.read": "Permissão para consulta do webhook", "webhook.write": "Permissão para alteração do webhook", "payloadlocation.write": "Permissão para alteração de payloads", "payloadlocation.read": "Permissão para consulta de payloads" }, "tokenUrl": "https://pix.example.com/oauth/token" } } } }, "responses": { "NaoEncontrado": { "description": "Recurso solicitado não foi encontrado.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "exemplo1": { "$ref": "#/components/examples/NaoEncontradoExample1" } } } } }, "AcessoNegado": { "description": "Requisição de participante autenticado que viola alguma regra de autorização.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "exemplo1": { "$ref": "#/components/examples/AcessoNegadoExample1" } } } } }, "ServicoIndisponivel": { "description": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "exemplo1": { "$ref": "#/components/examples/ServicoIndisponivelExample1" } } } } } }, "examples": { "devolucaoResponse1": { "summary": "Exemplo de devolução 1", "value": { "id": "123456", "rtrId": "D12345678202009091000abcde123456", "valor": "7.89", "horario": { "solicitacao": "2020-09-11T15:25:59.411Z" }, "status": "EM_PROCESSAMENTO" } }, "devolucaoResponse2": { "summary": "Exemplo de devolução 2", "value": { "id": "502", "rtrId": "D12345678202011111000fghij789012", "valor": "20.00", "horario": { "solicitacao": "2020-09-11T15:25:59.411Z" }, "status": "NAO_REALIZADO", "motivo": "Negado por timeout" } }, "AcessoNegadoExample1": { "summary": "Exemplo de erro da requisição 1", "value": { "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado", "title": "Acesso Negado", "status": 403, "detail": "Requisição de participante autenticado que viola alguma regra de autorização." } }, "NaoEncontradoExample1": { "summary": "Exemplo de erro da requisição 1", "value": { "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado", "title": "Não Encontrado", "status": 404, "detail": "Entidade não encontrada." } }, "ServicoIndisponivelExample1": { "summary": "Exemplo de erro da requisição 1", "value": { "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel", "title": "Serviço Indisponível", "status": 503, "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento." } } }, "schemas": { "Problema": { "type": "object", "properties": { "type": { "type": "string", "description": "URI de referência que identifica o tipo de problema. De acordo com a RFC 7807.", "format": "uri", "example": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado" }, "title": { "type": "string", "description": "Descrição resumida do problema.", "example": "Not found" }, "status": { "type": "integer", "description": "Código HTTP do status retornado.", "example": 404 }, "detail": { "type": "string", "description": "Descrição completa do problema." }, "correlationId": { "type": "string", "description": "Identificador de correlação do problema para fins de suporte" }, "violacoes": { "type": "array", "items": { "$ref": "#/components/schemas/Violacao" } } }, "required": [ "type", "title", "status" ] }, "Violacao": { "type": "object", "title": "Violações", "properties": { "razao": { "type": "string", "title": "Descrição do erro", "description": "Descrição do erro", "example": "Valor da cobrança não pode ser 0.00" }, "propriedade": { "type": "string", "title": "Nome da propriedade", "description": "Nome da propriedade", "example": "cob.chave" }, "valor": { "type": "string", "title": "Valor da propriedade", "description": "Valor da propriedade", "example": "061996671234" } } }, "EndToEndId": { "type": "string", "title": "Id fim a fim da transação", "description": "O identificador da transação ou End to End ID é utilizado para identificar um pagamento Pix realizado contemplando todo o mercado que transita na PACS002, PACS004 e PACS008.\n- PACS.002: Mensagem de status de pagamento. Utiliza o `EndToEndIdentification` para relacionar a resposta ao pagamento original.\n- PACS.004: Mensagem de devolução de pagamento. Garante que a devolução seja associada corretamente ao pagamento inicial.\n- PACS.008: Mensagem de crédito interbancário. Rastreia o pagamento da origem ao destino final.", "pattern": "[a-zA-Z0-9]{32}", "minLength": 32, "maxLength": 32 }, "Devolucao": { "type": "object", "title": "Devolução", "properties": { "id": { "$ref": "#/components/schemas/DevolucaoId" }, "rtrId": { "type": "string", "title": "RtrId", "description": "**ReturnIdentification** é utilizado para identificar de forma única uma transação de devolução na mensagem PACS.004. Ele assegura a correta associação entre a devolução e a transação original.\r\n\r\nA utilização do `ReturnIdentification` garante a integridade e a rastreabilidade das devoluções no sistema de pagamentos.\r\n", "pattern": "[a-zA-Z0-9]{32}", "minLength": 32, "maxLength": 32, "example": "D12345678202009091000abcde123456" }, "valor": { "type": "string", "title": "Valor a devolver.", "description": "Valor da devolução.", "pattern": "\\d{1,10}\\.\\d{2}" }, "natureza": { "$ref": "#/components/schemas/DevolucaoNatureza" }, "descricao": { "type": "string", "title": "Mensagem ao pagador relativa à devolução.", "description": "O campo `descricao` é opcional e permite que informações sobre a devolução sejam apresentadas ao pagador. Na mensagem PACS.004, este campo é preenchido pelo PSP do recebedor e inserido no campo `RemittanceInformation`.\r\n", "maxLength": 140 }, "horario": { "type": "object", "properties": { "solicitacao": { "type": "string", "title": "Horário de solicitação", "description": "Horário no qual a devolução foi solicitada no PSP.", "format": "date-time" }, "liquidacao": { "type": "string", "title": "Horário de liquidacao", "description": "Horário no qual a devolução foi liquidada no PSP.", "format": "date-time" } } }, "status": { "type": "string", "enum": [ "EM_PROCESSAMENTO", "DEVOLVIDO", "NAO_REALIZADO" ], "title": "Status", "description": "Status da devolução." }, "motivo": { "type": "string", "title": "Descrição do status.", "description": "**Status da Devolução**\n\nCampo opcional que pode ser utilizado pelo PSP recebedor para detalhar os motivos\nde a devolução ter atingido o status em questão.\nPode ser utilizado, por exemplo, para detalhar o motivo de a devolução não ter sido realizada.\n", "maxLength": 140 } }, "required": [ "id", "rtrId", "valor", "horario", "status" ] }, "DevolucaoId": { "type": "string", "title": "Id da Devolução", "description": "Identificação gerada pelo cliente para representar uma devolução.", "pattern": "[a-zA-Z0-9]{1,35}" }, "DevolucaoNatureza": { "type": "string", "enum": [ "ORIGINAL", "RETIRADA", "MED_OPERACIONAL", "MED_FRAUDE" ], "title": "Natureza da Devolução", "description": "Indica qual é a natureza da devolução. Uma devolução pode ser relacionada a um Pix comum (com códigos possíveis: `MD06`, `BE08` e `FR01` da pacs.004), \nou a um Pix de Saque ou Troco (com códigos possíveis: `MD06` e `SL02` da pacs.004). Na ausência deste campo a natureza deve ser interpretada como \nsendo de um Pix comum (`ORIGINAL`).\n\nAs naturezas são assim definidas:\n - `ORIGINAL`: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum ou ao valor da compra em um Pix Troco (`MD06`);\n - `RETIRADA`: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix Saque ou ao valor do troco em um Pix Troco (`SL02`);\n - `MED_OPERACIONAL`: quando a devolução ocorre no âmbito do MED por motivo de falha operacional e se refere a um Pix comum (`BE08`);\n - `MED_FRAUDE`: quando a devolução ocorre no âmbito do MED por fundada suspeita de fraude e se refere a um Pix comum (`FR01`).\n\nOs valores de devoluções são sempre limitados aos valores máximos a seguir:\n- Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso pode ser: ORIGINAL, MED_OPERACIONAL ou MED_FRAUDE);\n- Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA); \n- Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:\n - Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL); \n - Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA).\n" } } }, "x-internal": false, "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "_id": { "buffer": { "0": 102, "1": 61, "2": 35, "3": 187, "4": 32, "5": 249, "6": 144, "7": 0, "8": 74, "9": 225, "10": 19, "11": 105 } } } ```