Overview da API: Parceiros conciliadores
Esta seção é destinada a parceiros Stone que desejam acessar os arquivos de conciliação de terceiros.
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 integracoes.parcerias@stone.com.br.
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
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.
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
Jornada: Começar a integrar
Etapa 5 de 8