--- title: "Overview da API: Cliente Stone" url: "https://devcenter.stone.com.br/conciliacao-overview-cliente-stone" image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_~T3ZlcnZpZXcgZGEgQVBJOiBDbGllbnRlIFN0b25l,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9jb25jaWxpYWNhby1vdmVydmlldy1jbGllbnRlLXN0b25lIg,s_tBylwSYTK5PSHtfy.png" --- # 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](https://devcenter.stone.com.br/conciliacao-overview-parceiros-conciliadores). O fluxo de autenticação é diferente. ## [Como funciona](#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](#passo-a-passo) ### [1\. Obtenha sua chave de acesso](#_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](#_2-monte-a-requisição-de-extrato) **Endpoint:** ```text 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**: ```text Authorization: Basic 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 `Authorization` deve conter o valor em Base64 de `:` (chave seguida de dois-pontos, sem senha) **Importante:** O header x-user-type: client é obrigatório. Sem ele, a API não reconhece a requisição como sendo de um cliente Stone e retornará erro de autenticação. ### [3\. Receba o arquivo](#_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:** ```text GET https://conciliation.stone.com.br/v2/merchant/123456789/conciliation-file/20260406?layout=XML2_2 Headers: Authorization: Basic Accept-Encoding: gzip x-user-type: client ``` --- ### [Erros comuns](#erros-comuns) _Causas mais frequentes:_ #### [Erro 401 — "Unauthorized"](#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 `:` (com dois-pontos no final, sem senha). Chave incorreta ou expirada — verificar no Portal Stone se a chave está ativa. #### [Erro 403 — "Forbidden"](#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](#dúvidas-frequentes) #### [Posso gerar mais de uma chave de conciliação?](#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?](#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?](#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?](#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?](#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](#próximos-passos) [Extrato da Agenda Stone](https://devcenter.stone.com.br/conciliacao-extrato-da-agenda-stone) — detalhes completos do endpoint [Mensagens de erro](https://devcenter.stone.com.br/conciliacao-mensagens-de-erro) — referência de todos os erros da API [Estrutura do extrato - Layout 2.2](https://devcenter.stone.com.br/conciliacao-layout-2-2) — entenda o conteúdo do arquivo [Estrutura do extrato - Layout 2.4](https://devcenter.stone.com.br/conciliacao-layout-2-4) — entenda o conteúdo do arquivo --- **Jornada: [Começar a integrar](https://devcenter.stone.com.br/conciliacao-processo-de-integracao)** Etapa 4 de 8 [**Etapa anterior**Solicitação de credencial](https://devcenter.stone.com.br/conciliacao-solicitacao-de-credencial)[**Próxima etapa**Overview da API: Parceiros conciliadores](https://devcenter.stone.com.br/conciliacao-overview-parceiros-conciliadores) Siga a Stone nas redes sociais [](https://www.facebook.com/stonepagamentos/)[](https://x.com/sejastone/)[](https://www.instagram.com/stone/)[](https://br.linkedin.com/company/stone-co)[](https://www.youtube.com/channel/UCk4L4JykgoDkN8YeuxkNqIQ) © Stone Instituição de Pagamento S.A. CNPJ 16.501.555/0001-57 Av. Rebouças, 2880, 4º andar, Pinheiros, CEP 05.402-500 – São Paulo/SP Instituição de pagamento autorizada pelo Banco Central do Brasil, nas modalidades de credenciadora e emissora de moeda eletrônica.