Overview da API - Parceiros conciliadores

Antes de integrar a nossa solução, é necessário que você entenda o fluxo operacional para que sua integração possa ocorrer sem problemas.

Você é um cliente Stone (lojista) acessando seu próprio arquivo? Consulte o Overview da API - Cliente Stone. O fluxo de autenticação é diferente.

Fluxo para parceiros conciliadores

Para conseguir acesso ao arquivo de Conciliação, é preciso seguir 3 passos:

Solicitar as credenciais da API
Solicitar concessão de acesso ao arquivo, para o estabelecimento
Buscar o arquivo em nossa API

1. Solicitar Credenciais de API

As credenciais para acesso aos arquivos de conciliação são: ClientId e ClientSecret.

Para obter suas credenciais, acesse e preencha o formulário de Parcerias disponível nesta página. Se já for um parceiro, entre em contato com [email protected].

Importante: Caso você seja um lojista, informe sua conciliadora para que ela entre em contato com nosso canal de Parcerias.

2. Solicitar Concessão de Acesso ao Arquivo

Para que uma empresa terceira (conciliadora) acesse os dados de conciliação de um estabelecimento, é necessário o consentimento do lojista.

O fluxo ocorre da seguinte forma:

A conciliadora solicita o acesso ao arquivo do lojista via nossa API (Pedido de consentimento);
O lojista recebe um e-mail, podendo aprovar ou recusar o pedido através dos links disponíveis.
Ao aprovar, nosso sistema registra a concessão e envia um e-mail de confirmação.
As credenciais de acesso são enviadas automaticamente à conciliadora via webhook (Resposta de Consentimento);
Após receber e decriptar a senha utilizando AES CBC PKCS7 (Decriptando senha), a conciliadora pode se autenticar utilizando o endpoint de autenticação Gerando seu token de acesso .

❗️
Pontos importantes sobre o consentimento:

O token obtido na autenticação permite o acesso aos arquivos de conciliação nos fluxos disponíveis e tem validade de 24 horas. Recomenda-se implementar cache com renovação automática baseada no tempo de expiração.

O consentimento é vinculado ao documento (CNPJ), não ao StoneCode. Uma vez que o lojista aprova o acesso para um documento, todos os StoneCodes associados a esse documento ficam acessíveis com as mesmas credenciais — inclusive StoneCodes criados no futuro.

A webhookUrl deve obrigatoriamente usar HTTPS. As URLs com HTTP serão recusadas com erro 400.

Recomenda-se usar a mesma webhookUrl para todos os lojistas. Caso seja necessário alterar a URL, há um cache por clientId de 10 minutos — a nova URL só passa a receber eventos após esse prazo.

O e-mail de consentimento é enviado para o endereço principal vinculado aoaffiliationCode(StoneCode) informado no pedido. Se o e-mail estiver desatualizado, a atualização deve ser feita pelo próprio lojista no Portal ou com ajuda do RC ([email protected]). Após atualizado, o pedido deve ser refeito.

Se dois pedidos de consentimento forem aceitos para o mesmo documento, dois usernames e passwords distintos serão gerados. Ambos são válidos e podem ser usados normalmente, basta selecionar qual utilizará.

3. Buscar o arquivo em nossa API

Com o token retornado, é possível consultar e baixar os arquivos de conciliação:

Para o arquivo geral XML, utilize a página de extrato de agenda Stone.
Para arquivos de PIX, acesse PIX - Solicitação de Arquivo.

📘
Ao solicitar acesso, a conciliadora terá autorização para arquivos XML e de Pix (CSV).
Atenção: Os métodos de integração para cada tipo de arquivo são diferentes, siga o fluxo específico de cada um.

Erros comuns

No pedido de consentimento (POST /v2/merchant/consents)

Sintoma	Causa provável	Solução
400	`webhookUrl` usando HTTP	Trocar para HTTPS
400	`document` com pontuação (pontos, traços, barras)	Enviar apenas números
400	`affiliationCode` sem e-mail vinculado	Solicitar vinculação de e-mail via Admin/credenciamento
Webhook não chega após aprovação	Cache da `webhookUrl`(trocou URL recentemente)	Aguardar 10 minutos após a troca
Webhook não chega (URL não trocou)	URL inacessível externamente ou firewall bloqueando	Verificar se a URL está acessível pela internet

Na geração do token (POST /auth/.../oauth/token)

Sintoma	Causa provável	Solução
401	Senha não foi decriptada antes do uso	Decriptar com AES CBC PKCS7 conforme documentação
401	`clientId` ou `clientSecret` incorretos	Verificar credenciais

No extrato (GET /v2/merchant/stoneCode/conciliation-file/date)

Sintoma	Causa provável	Solução
401	Faltando prefixo `Bearer` no Authorization	Corrigir para `Bearer <token>`
401	Token expirado (validade de 24h)	Gerar novo token
403	Token não pertence ao documento do Stone Code	Verificar se o consentimento foi feito para o documento correto
404	Stone Code com letras ou data fora do formato AAAAMMDD	Corrigir parâmetros
Arquivo não encontrado	Solicitação antes das 5h do dia seguinte	Aguardar disponibilidade

Próximos passos

Pedido de consentimento — detalhes da requisição
Resposta de Consentimento — estrutura dos eventos de webhook
Decriptando senha — algoritmo e exemplos
Gerando seu token de acesso — endpoint de autenticação
Extrato da Agenda Stone — download do arquivo
Mensagens de erro — referência completa