--- title: "Overview da API: Parceiros conciliadores" url: "https://devcenter.stone.com.br/conciliacao-overview-parceiros-conciliadores" image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_~T3ZlcnZpZXcgZGEgQVBJOiBQYXJjZWlyb3MgY29uY2lsaWFkb3Jlcw,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9jb25jaWxpYWNhby1vdmVydmlldy1wYXJjZWlyb3MtY29uY2lsaWFkb3JlcyI,s_qc-sMyuy4R21ZMmG.png" --- # 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](https://devcenter.stone.com.br/conciliacao-overview-cliente-stone). O fluxo de autenticação é diferente. ### [Fluxo para parceiros conciliadores](#fluxo-para-parceiros-conciliadores) Para conseguir acesso ao arquivo de Conciliação, é preciso seguir 3 passos: 1. Solicitar as credenciais da API 2. Solicitar concessão de acesso ao arquivo, para o estabelecimento 3. Buscar o arquivo em nossa API ## [1\. Solicitar Credenciais de 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](https://devcenter.stone.com.br/conciliacao-solicitacao-de-credencial). Se já for um parceiro, entre em contato com [integracoes.parcerias@stone.com.br](mailto: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](#_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: 1. A conciliadora solicita o acesso ao arquivo do lojista via nossa API ([Pedido de consentimento](https://devcenter.stone.com.br/conciliacao-pedido-de-consentimento)); 2. O lojista recebe um e-mail, podendo **aprovar ou recusar** o pedido através dos links disponíveis. 3. Ao aprovar, nosso sistema registra a concessão e envia um e-mail de confirmação. 4. **As credenciais de acesso são enviadas automaticamente à conciliadora via webhook ([Resposta de Consentimento](https://devcenter.stone.com.br/conciliacao-resposta-de-consentimento));** 5. Após receber e **decriptar a senha** utilizando AES CBC PKCS7 ([Decriptando senha](https://devcenter.stone.com.br/conciliacao-decriptando-senha)), a conciliadora pode se autenticar utilizando o endpoint de autenticação [Gerando seu token de acesso](https://devcenter.stone.com.br/conciliacao-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 ao**`affiliationCode`(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 ([meajuda@stone.com.br](mailto:meajuda@stone.com.br)). Após atualizado, o pedido deve ser refeito. - O remetente do e-mail de consentimento é [no\_reply@stone.com.br,](https://devcenter.stone.com.br/no_reply@stone.com.br "no_reply@stone.com.br") com Assunto: "Conciliação Stone - Solicitação de acesso por _\[Nome do Parceiro\]_". **O e-mail não possui expiração**. - **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](#_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](https://devcenter.stone.com.br/conciliacao-extrato-da-agenda-stone#/versions). - Para arquivos de **PIX**, acesse [PIX - Solicitação de Arquivo](https://devcenter.stone.com.br/conciliacao-pix-solicitacao-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](#erros-comuns) #### [No pedido de consentimento (POST /v2/merchant/consents)](#no-pedido-de-consentimento-post-v2merchantconsents) | 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)](#na-geração-do-token-post-authoauthtoken) | 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)](#no-extrato-get-v2merchantstonecodeconciliation-filedate) | Sintoma | Causa provável | Solução | | :--------------------- | :----------------------------------------------------- | :-------------------------------------------------------------- | | 401 | Faltando prefixo Bearer no Authorization | Corrigir para Bearer | | 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](#próximos-passos) - [Pedido de consentimento](https://devcenter.stone.com.br/conciliacao-pedido-de-consentimento) — detalhes da requisição - [Resposta de Consentimento](https://devcenter.stone.com.br/conciliacao-resposta-de-consentimento) — estrutura dos eventos de webhook - [Decriptando senha](https://devcenter.stone.com.br/conciliacao-decriptando-senha) — algoritmo e exemplos - [Gerando seu token de acesso](https://devcenter.stone.com.br/conciliacao-gerando-seu-token-de-acesso) — endpoint de autenticação - [Extrato da Agenda Stone](https://devcenter.stone.com.br/conciliacao-extrato-da-agenda-stone) — download do arquivo - [Mensagens de erro](https://devcenter.stone.com.br/conciliacao-mensagens-de-erro) — referência completa --- --- **Jornada: [Começar a integrar](https://devcenter.stone.com.br/conciliacao-processo-de-integracao)** Etapa 5 de 8 [**Etapa anterior**Overview da API: Cliente Stone](https://devcenter.stone.com.br/conciliacao-overview-cliente-stone)[**Próxima etapa**Ambientes](https://devcenter.stone.com.br/conciliacao-ambientes) 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.