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 eu 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
• Adição de novo status em um evento de postback já existente

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', '2013-03-01'

API changelog

2017-08-28

Os campos para criar transações por companhias com antifraude ligado passaram por vastas alterações. Foram implementados features às rotas customers e transactions para permitir análises de fraude ainda mais robustas.

O objeto customer foi dissociado em customer, billing e shipping, nos quais constam, respectivamente, os dados do cliente, os dados de cobrança e os dados de envio. billing e shipping estão associados a transaction. Adicionalmente, foi criado o objeto items, também associado a transaction, que coleta informações sobre os itens da compra.

Os parâmetros customer, billing e items passam a ser obrigatórios para transações com cartão de crédito e antifraude habilitado.

Para criação de boletos, os campos country, documents e type dentro de customer passam a ser obrigatórios.

Resumo das alterações:

• Parâmetros obrigatórios adicionados a customer: external_id, type, country, phone_numbers, documents. Para mais informações, clique aqui.
• Parâmetros removidos de customer: document_number, document_type, gender, sex, born_at, phone e address. Para mais informações, clique aqui.
• Parâmetro criado: billing. Inclui os campos obrigatórios name e address. Para mais informações, clique aqui.
• Parâmetro criado: items. Inclui os campos obrigatórios id, title, unit_price, quantity e tangible. Para mais informações, clique aqui.
• Parâmetro opcional criado: shipping. Inclui os campos obrigatórios name, fee e address. Para mais informações, clique aqui.
• Novos status de transações podem agora ser enviados dentro do payload de um postback.
• Eliminação do comportamento de preenchimento dos campos de endereço a partir do CEP (presente nas versões 2013-03-01 e 2017-07-17).

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.