Concilie suas Vendas

Consulta de identificadores do lojista

Endpoint

GET https://conciliation.stone.com.br/v2/merchant/identifiers

Query params

NomeObrigatórioTipoDescrição
documentsimstringCPF (11 caracteres) ou CNPJ (14 caracteres), sem máscara (apenas letras e dígitos).

Headers

NomeObrigatórioTipoDescrição
Authorizationsimstring(padrão: Bearer <JWT>)
Acceptsimstring(padrão: application/json)
Novos identificadores

A partir de Setembro de 2026, credenciamentos criados na Stone passaram a contar com novos identificadores, que substituem o Stonecode no processo de conciliação. Essa atualização está sendo aplicada de forma gradual: durante o período de transição, alguns estabelecimentos ainda podem ser credenciados no modelo anterior. Para viabilizar a conciliação nesse cenário, disponibilizamos este endpoint, que permite consultar os novos identificadores do estabelecimento a partir do CNPJ consentido. Com eles, você extrai os arquivos de conciliação seguindo o fluxo do NOVO Extrato da Agenda Stone.

Quando usar

  • Estabelecimentos com os novos identificadores (não possui Stonecode) — use esta consulta, informando o documento, para obter os identificadores e utilizá-los na extração.
  • Estabelecimentos no modelo anterior — a extração continua sendo feita pelo StoneCode, como sempre.
Mesmo formato

Não é necessária nenhuma mudança estrutural na sua integração: o arquivo de conciliação mantém o mesmo formato e o mesmo conteúdo. O que muda é apenas por qual identificador você solicita o arquivo.

Como funciona

  1. Você faz a consulta informando o documento (CPF ou CNPJ) do estabelecimento que o cliente consentiu.
  2. O endpoint retorna a lista de identificadores associados àquele documento.
  3. Você utiliza esses identificadores na extração dos arquivos de conciliação.

Autenticação

É feita passando o token de acesso no header Authorization: Bearer TOKEN.

O documento informado em document precisa ser o mesmo documento para o qual o token de acesso foi gerado (obtido por meio do consentimento). Se o token for de outro documento, a requisição é recusada com 403.

Regras de comportamento

Documento válido que possua apenas credenciamentos no modelo anterior (por Stonecode) retorna 200 com lista vazia ([]) — isso não é um erro.

Documento existente, sem credenciamentos no modelo novo:

[]

Códigos de status

  • 200 OK — Lista de identificadores retornada (pode ser vazia).
  • 400 Bad Request — Falha de validação da requisição. Retorna a lista de erros por campo.
  • 401 Unauthorized — Token ausente, malformado ou inválido.
  • 403 Forbidden — Claim custom:document do token diferente do document informado na query.
  • 404 Not Found — Documento não encontrado na base de estabelecimentos.
  • 429 Too Many Requests — Limite de chamadas excedido (ver Rate limit).
  • 503 Service Unavailable — Indisponibilidade momentânea do serviço. Aguarde e repita a chamada mais tarde.

Rate limit

A rota possui limite de 4 chamadas por hora, considerando a URL completa, ou seja, 4 requisições por documento. Ao exceder o limite, a resposta é 429.

Como os identificadores mudam com pouca frequência, recomendamos aplicar cache local no seu fluxo em vez de consultar a cada extração. Isso evita consumir o limite sem necessidade.

Jornada: Obter o consentimento e autenticar
Etapa 5 de 6

Etapa anteriorConsulta de status de consentimentoPróxima etapaGerando seu token de acesso