GuidesSuporteAPI Reference

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

662


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