## 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.