Migração de clientes entre a API V1 e V2

Este documento descreve as principais diferenças entre as versões V1 e V2 da nossa API, com o objetivo de orientar os clientes na migração para a nova versão. Abaixo, detalhamos as alterações em autenticação, uso de impersonate e contratos dos endpoints.

1. Autenticação

V1

No fluxo de autenticação da versão V1, o cliente utiliza um formato application/x-www-form-urlencoded e baseia-se em client_id e client_secret para obter o token de acesso. Esse fluxo é genérico e não está focado no contexto do parceiro ou permissões específicas.

Exemplo de Requisição (V1)

Bash

curl --request POST \
     --url {{env}}/auth/token \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data client_id=client_service_account \
     --data client_secret=92f4adbb-5e5f-428d-8c9e-56dcc32108e0 \
     --data grant_type=client_credentials

Características do V1

• Formato: application/x-www-form-urlencoded.
• Autenticação: Baseada em client_id e client_secret.
• Impersonate: Funcionalidade não integrada diretamente ao fluxo de autenticação.

V2

A autenticação na versão V2 introduz um fluxo aprimorado, utilizando JSON como formato principal para a requisição. A abordagem foca no contexto do parceiro (partner) e permite o controle granular de permissões e integração com funcionalidades avançadas, como impersonate.

Exemplo de Requisição (V2)

Bash

curl --location --request POST '{{env}}/v3/auth/partner/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKeyId": "13481db7a462583bdfdae3dc",
    "secretKey": "5b3abf849a2b2ff60a27b1b7"
}'

Características do V2

• Formato: application/json.
• Autenticação: Baseada em accessKeyId e secretKey, representando credenciais exclusivas do parceiro.
• Impersonate: Como partner, permite o controle de contas vinculadas ao partner.
• Segurança: Melhorias na validação e rastreamento das credenciais utilizadas.

---

Principais Diferenças entre V1 e V2

Aspecto	V1	V2
Formato	application/x-www-form-urlencoded	application/json
Identificação	client_id e client_secret	accessKeyId e secretKey
Foco	Genérico	Contexto de parceiro (partner)
Impersonate	Não integrado	Totalmente integrado
Segurança	Básica	Melhorias no rastreamento e validação

2. Impersonate

No modelo V2, todas as requisições devem incluir o campo accountIdentifier no header. Esse campo refere-se à conta que o parceiro deseja manipular, permitindo realizar ações específicas em nome dessa conta.

Essa funcionalidade oferece maior flexibilidade e controle, especialmente em fluxos onde o parceiro precisa agir em nome de diferentes contas, como na emissão de cobranças ou criação de transações.

3. Alteração de Contratos

A migração entre V1 e V2 não altera os principais contratos de API e Webhook utilizados nas requisições, com exceção do uso do campo accountIdentifier no header, a URL de alguns endpoints será diferente.

No entanto, recomendamos fortemente que os contratos sejam atualizados para as versões descritas na documentação V2.1, uma vez que os contratos antigos deixarão de ter suporte. Essa atualização garante compatibilidade total com as melhorias e novos recursos disponíveis na V2.

Se precisar de assistência durante a migração, entre em contato com o suporte técnico.