Overview da API: Cliente Stone
Esta seção é destinada a clientes Stone (lojistas) que desejam acessar diretamente o próprio arquivo de conciliação, sem intermediação de uma conciliadora parceira.
Você é um parceiro conciliador? Consulte o Overview da API - Parceiros conciliadores. O fluxo de autenticação é diferente.
Como funciona
Diferente do fluxo de parceiros conciliadores, o cliente Stone não precisa passar pelo fluxo de consentimento. O acesso ao arquivo é direto, usando uma chave criada no Portal Stone.
| Aspecto | Cliente Stone (lojista) | Parceiro conciliador |
|---|---|---|
| Consentimento | Não necessário | Obrigatório |
| Autenticação | HTTP Basic Auth | Bearer Token (OAuth 2.0) |
| Credencial | Chave do Portal Stone | ClientId e ClientSecret (únicos por Conciliadora) + Username e Password (via consentimento) |
| Header extra | x-user-type: client (obrigatório) | Não se aplica |
Passo a passo
1. Obtenha sua chave de acesso
Acesse o Portal Stone e crie uma chave de API para conciliação. Essa chave será usada como seu identificador de autenticação.
O caminho no Portal é: Perfil > Chaves de Autenticação > Criar Chave > "API de Conciliação Stone"
Para visualização desse menu, é necessário que o acesso seja realizado pelo titular da conta.
2. Monte a requisição de extrato
Endpoint:
GET https://conciliation.stone.com.br/v2/merchant/{affiliationCode}/conciliation-file/{referenceDate}
Parâmetros de path:
| Parâmetro | Descrição | Formato |
|---|---|---|
affiliationCode | Seu StoneCode | Numérico |
referenceDate | Data de referência do arquivo | AAAAMMDD |
Headers obrigatórios:
Authorization: Basic <chave_do_portal> em Base64
Accept-Encoding: gzip
x-user-type: client
Detalhes da autenticação Basic Auth:
- User: Sua chave do Portal Stone
- Password: Vazio (não enviar valor)
- O header
Authorizationdeve conter o valor em Base64 de<chave>:(chave seguida de dois-pontos, sem senha)
3. Receba o arquivo
O arquivo de conciliação é retornado compactado em gzip. Os layouts disponíveis são XML2_2 (padrão) e XML2_4, configuráveis via query parameter layout.
Exemplo completo:
GET https://conciliation.stone.com.br/v2/merchant/123456789/conciliation-file/20260406?layout=XML2_2
Headers:
Authorization: Basic <base64 de "sua_chave:">
Accept-Encoding: gzip
x-user-type: client
Erros comuns
Causas mais frequentes:
Erro 401 — "Unauthorized"
- Faltou o header x-user-type: client — este é o erro mais comum. Sem ele, a API tenta validar como parceiro conciliador e a autenticação falha.
- Formato incorreto do Basic Auth — o valor deve ser o Base64 de
<chave>:(com dois-pontos no final, sem senha). Chave incorreta ou expirada — verificar no Portal Stone se a chave está ativa.
Erro 403 — "Forbidden"
- A chave usada não está associada ao Stone Code informado no path. Cada chave é vinculada a um documento (CPF/CNPJ) específico.
Dúvidas frequentes
Posso gerar mais de uma chave de conciliação?
Sim, é possível ter até 10 chaves no Portal Stone.
Preciso passar pelo fluxo de consentimento?
Não. O fluxo de consentimento é exclusivo para parceiros conciliadores. Como cliente Stone, você acessa diretamente o seu próprio arquivo.
Posso usar Bearer Token em vez de Basic Auth?
Não. A autenticação de cliente Stone é feita exclusivamente via Basic Auth com a chave do Portal.
O que é o x-user-type?
É um header que identifica o tipo de usuário na requisição. Para clientes Stone, o valor deve ser sempre client.
Minha chave funciona para todos os meus Stone Codes?
A chave está vinculada ao seu documento (CPF/CNPJ). Ela funciona para todos os Stone Codes associados a esse documento.
Próximos Passos
Extrato da Agenda Stone — detalhes completos do endpoint
Mensagens de erro — referência de todos os erros da API
Estrutura do extrato - Layout 2.2 — entenda o conteúdo do arquivo
Estrutura do extrato - Layout 2.4 — entenda o conteúdo do arquivo
Jornada: Começar a integrar
Etapa 4 de 8