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.

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.