Versionamento

O que é a versão da API?

A versão define o comportamento da API, assim como quais parâmetros você pode enviar nas requisições e quais propriedades a mesma retorna.

Qual versão estou usando?

Todas as requisições a API utilizam a versão configurada em sua conta. Esta versão é automaticamente definida para a mais recente ao criar a conta no Pagar.me. Esta informação pode ser consultada através da Dashboard, em Ver minha conta > Configurações > API Keys.

Como navegar entre as versões na documentação?

No canto superior esquerdo da tela é indicado qual versão da documentação você está vendo. Se você clicar neste botão, como mostra a imagem abaixo, é possível navegar entre as versões e escolher a correspondente com a versão da API que você está usando.

Quando novas versões são criadas?

Todas as mudanças na API que não forem retrocompatíveis serão realizadas com a criação de uma nova versão. O objetivo deste comportamento é não quebrar integrações já existentes e permitir a evolução do produto.

Quais mudanças são retrocompatíveis?

• Criação de novas rotas na API
• Adição de parâmetros opcionais na requisição
• Adição de propriedades na resposta da API
• Alteração na ordem das propriedades da resposta
• Alteração dos formatos de ids

Quais mudanças não são retrocompatíveis?

• Adição de parâmetro obrigatório na requisição
• Adição de eventos de postback
• Alteração da validação de um parâmetro na requisição
• Alteração da rota de um recurso
• Alteração ou criação de códigos de resposta
• Alteração de valores padrão
• Remoção de parâmetros na requisição
• Remoção de propriedades na resposta ou postback

Como eu faço o upgrade da versão?

Se você deseja utilizar uma versão mais recente da API para aproveitar funcionalidades novas, você deve atualizar a mesma. Através de sua dashboard, acesse Ver minha conta > Configurações > API Keys. No final da página você poderá escolher a versão que deseja usar e salvar essa configuração. Mas atenção, essa mudança é aplicada imediatamente em sua conta e poderá afetar suas integrações existentes.

📘

Header X-Pagarme-Version

Você também pode enviar o Header X-Pagarme-Version para realizar requisições com o payload compatível com o de uma versão diferente da sua, sem que seja necessário o upgrade para esta versão. Isto é útil para utilizar features disponíveis em novas versões da API. Os valores aceitos para este cabeçalho são: '2017-08-28", "2017-07-17" e "2013-03-01"

API changelog

2017-07-17

• O parâmetro customer.document_number passa a ser obrigatório para a criação de transações com payment_method=boleto.
• O parâmetro customer.name passa a ser obrigatório para a criação de transações com payment_method=boleto.
• Um novo evento de postback passa a ser enviado quando uma transação de boleto muda do status processing para waiting_payment.

2013-03-01

Versão inicial da API.