EXTRATO ELETRÔNICO v15

Atualizações V15.15 - Data de implantação: 19/05/2026

• Demonstração dos eventos de bloqueio/desbloqueio/liquidação judicial nas transações Pix.
• Inclusão dos lançamentos de contrapartida das negociações Voucher (PAT).

Atualizações V15.14.1 - Data de implantação: 13/01/2026

• Identificação de hierarquia de cadastro.
• Identificação de transações com produto TC (Vendeu, Tá na Conta) no registro tipo “E”.

Anexos

LAYOUTS ATUALIZADOS:

• Manual de Especificação Técnica - Português
• Technical Specification Manual - English
  
  

Fluxo de entrega de extratos

• Portal único para clientes: As consultas e downloads dos arquivos estão disponíveis na área logada do site Cielo www.cielo.com.br - guia Serviços > acessar Extrato Eletrônico.
• Canal de atendimento: edi@cielo.com.br ou (11) 4002-5270

Descrição do produto

O Extrato Eletrônico é uma solução desenvolvida pela Cielo para clientes que demandam automação no processo de conciliação financeira. Este produto disponibiliza, de forma padronizada e sem intervenção manual, os dados referentes às vendas, pagamentos, negociações e saldo em aberto processados pela Cielo. As informações são geradas em formato estruturado e ficam disponíveis para download direto no Site Cielo, garantindo agilidade, segurança e integridade no tráfego dos dados. Essa abordagem permite que os sistemas dos clientes integrem os dados de forma eficiente, reduzindo erros operacionais e aumentando a produtividade dos processos de backoffice.

Benefícios

• Permite a realização da conciliação contábil e financeira de forma automatizada
• Maior agilidade e eficiência operacional
• Integração com a automação comercial de vendas
• Segurança no recebiento das informações
• Atendimento Especializado

Fluxo de concessão

Introdução para API (exclusiva para Conciliadoras)

Essa API (exclusiva para Conciliadoras) possibilita o registro de grupos e mantém seu registro para receber arquivos EDI (Electronic Data Interchange).

Passo 1 - Login

1 - O parceiro redireciona o cliente para {cielo-login-url}.
2 - O cliente entra com suas credenciais e clica em Entrar.
3 - A Cielo mostra os termos de autorização e o cliente aprova este acesso clicando em Permitir Acesso.
4 - A Cielo redireciona o cliente para o parceiro novamente em {partner-call-back-url}.

O que é base-login-url?

https://{base-login-url}?response_type=code &client_id={client_id} &redirect_uri={redirect_uri} &scope={scope} &state={state}

Homologação: https://digitalhml.hdevelo.com.br/oauth/?mode=redirect&client_id={client_id}&redirect_uri={redirect_uri}&state=STATE_INFO&scope=profile_read,transaction_read

Produção: https://minhaconta2.cielo.com.br/oauth/?mode=redirect&client_id={client_id}&redirect_uri={redirect_uri}&state=STATE_INFO&scope=profile_read,transaction_read

• base-login-url: URL base que muda por ambiente
• response_type: O valor deve ser fixo “code”
• client_id: Identificador do cliente, será enviado pela Cielo em tempo de projeto
• redirect_uri: URL do parceiro para a Cielo redirecionar o usuário quando o processo de login terminar, ou se der algum erro no processo
• scope: Uma lista separada por vírgula das APIs que o parceiro deseja acessar, os possiveis escopos serão enviados por API.
• state: Um valor que o cliente deseja receber no retorno para manter o estado entre a requisição e o retorno

O que é partner-callback-url?

https://{partner-callback-url}?code={code}&state={state}

• partner-callback-url: A URL do parceiro que será redirecionado quando o processo de login terminar.
• code: O authorization code gerado pela Cielo. Com esse código o parceiro vai poder trocar por um access_token para fazer chamadas em nome do cliente.
• state: O mesmo valor que o parceiro enviou na requisição.

Passo 2 – Requisitando um Access Token

• O serviço do parceiro solicita um access_token.
• A Cielo retorna um acess_token, um refresh_token e um expiration_time.

Request

POST {cielo-api-base-url}/consent/v1/oauth/access-token

Key	Value
Authorization	Basic Base64(client_id e client_secret do parceiro concatenado com “:” e codificado em base64)

curl --location --request POST 'https://{cielo-api-base-url}/consent/v1/oauth/access-token' \
--header 'Basic Basic64'
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "authorization_code",
    "code": "{}"
}'
--verbose

Response

{
"access_token": "{access_token}",
"refresh_token": "{refresh_token}",
"token_type": "access_token",
"expires_in": {expiration_time}
}

Observações

• O authorization_code precisa ser trocado por um access_token em menos de 10 minutos.
• Este tipo de access_token é mandatório para chamar as APIs que retornam dados sensíveis dos clientes.
• O parceiro precisa armazenar o access_token e o refresh_token em um lugar seguro.
• Quando o access_token expirar o parceiro não conseguirá mais chamas as APIs até que solicite um novo acess_token usando o fluxo de refresh_token.
• O acess_token gerado nesse fluxo será único por cliente da Cielo, pois precisa obrigatoriamente a aprovação do cliente.
• O parceiro NÃO consegue gerar um access_token sem o consentimento do cliente.
• O parceiro NÃO consegue usar o authorization code, recebido no primeiro passo, mais de uma vez.

Passo 3 - Chamando as APIs

Neste momento parceiro vai conseguir chamar as APIs da Cielo sem a necessidade da aprovação do cliente, pois esta já foi concedida.

A única exigência para chamar as APIs da Cielo é enviar o seguinte header HTTP: Authorization: Bearer {access_token} Em todas as chamadas para as APIs.

• O access_token foi obtido no Segundo passo

Passo 3.1 - Atualizando um Access Token

1. O serviço do parceiro chama o serviço de refresh_token.
2. A Cielo retorna um access_token novo, um refresh_token novo e um novo expiration_time.

O dados de resposta serão os mesmos do passo 2 quando o parceiro solicita um acess_token, porém todos os dados retornados são novos e precisam ser armazenados no lugar dos antigos.

Request

curl --location --request POST 'https://{cielo-api-base-url}/consent/v1/oauth/access-token' \
--header 'Basic Basic64'
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "refresh_token",
    "refresh_token": "{}"
}'
--verbose

Um ponto de atenção na requisição pois agora o parceiro precisa enviar o grant_type como refresh_token e no campo refresh_token deve ser enviado um refresh_token válido (e não mais um access_token).

Response

{
"access_token": "{access_token}",
"refresh_token": "{refresh_token}",
"token_type": "access_token",
"expires_in": {expiration_time}
}

Erros

Caso ocorra algum erro do lado Cielo o cliente será redirecionado para a URL de call-back do parceiro com o parâmetro error na URL, por exemplo https://{partner-callback-url}?error={error}.

Possíveis valores para {error}:

• lid_request: A requisição está faltando algum parâmetro obrigatório, ou esta com algum parâmetro inválido, ou qualquer outra possibilidade que faça a URL ficar incorreta.
• unauthorized_client: O parceiro não está autorizado a fazer uma requisição usando este método.
• access_denied: O dono do recurso ou o servidor de autorização negou a requisição.
• unsupported_response_type: O servidor de autorização não suporta obter um authorization code usando este método.
• invalid_scope: O escopo é invalido, desconhecido ou malformado.
• server_error: O servidor de autorização encontrou uma condição inesperada e não consegue concluir esta requisição. ( Este erro é necessário porque não é possível retornar um HTTP status code 500 Internal Server Error via redirecionamento HTTP)
• temporarily_unavailable: O servidor de autorização não consegue tratar a requisição devido a uma sobrecarga temporária ou está em manutenção. (Este erro é necessário pois não é possível retornar um HTTP Status 503 Service Unavailable para o parceiro via redirecionamento HTTP)

Opcionalmente pode ser retornado um outro parâmetros error_description com um detalhe do erro, apenas um texto simples.

Observações

• Todos os tokens (access_token e refresh_token) devem ser armazenados em um local seguro.
• O parceiro precisam iniciar um novo fluxo de concessão se perderem os tokens ou ambos expirarem (O refresh_token tem expiração de 90 dias a partir da geração).
• Caso gere um novo refresh_token este tem mais 90 dias a partir da geração para expirar.
• O parceiro precisa iniciar um novo fluxo de concessão para cada cliente da Cielo que o parceiro deseja consultar os dados.

Ambiente

Collection

Dispobilizamos as Collections utiizadas para realizar as todas operações da API. Será necessário configurar a URL e as credenciais.

Download das Collections

Operações

GET Consulta a Lista de Filiais

Executa a lista de clientes abaixo do access_token informado. O filtro pode ser usado para listar apenas aqueles disponíveis ou indisponíveis. Indisponível significa que a filial já participa de outro registro. Nos serviços de registro e edição, há validação para permitir que apenas aqueles disponíveis sejam informados.

Response

GET /merchantgroup

Headers

Key	Value
	Authorization	Bearer + access_token

{
  "legalEntityNumber": "string",
  "branches": [
    {
      "merchantID": "9999111222",
      "legalEntityNumber": "01234567890",
      "businessName": "V",
      "status": "UNAVAILABLE"
    }
  ]
}

GET Consultar configurações existentes.

Retorna configurações existentes agrupadas por mainMerchantID.

Response

GET /mainmerchants

Headers

Key	Value
Authorization	Bearer + access_token

{
  "registerID": "38724",
  "mainMerchantID": "2006907071",
  "merchants": ["2006907071"],
  "type": [
    "SELL",
    "PAYMENT",
    "BALANCE",
    "NRC",
    "PIX"
  ],
  "ediStatus": "AVAILABLE"
}

POST Registrar merchantID

Registre o ID do lojista(apenas um, uma lista ou todos), com base no número da entidade.

Request

POST /registers

Headers

Key	Value
Authorization	Bearer + access_token

{
  "mainMerchantId": "9999111222",
  "merchants": ["9999111111", "9999111333"],
  "merchantEMail": "customer@customer.com",
  "type": ["SELL"]
}

Response

{
  "legalEntityNumber": 1234567890,
  "mainMerchantId": 2008983,
  "registerID": 12345,
  "merchants": [823958412384701, 679809436576210],
  "type": ["SELL"],
  "status": "PROCESSING"
}

GET Consultar o Status do Registro

Recupere o status de registro do EDI.

Response

GET /registers/{registerID}

Headers

Key	Value
Authorization	Bearer + access_token
registerID	Valor usado para recuperar o status do registro.

{
  "legalEntityNumber": "01234567890",
  "registerID": 12345,
  "merchants": [9999222111, 9999222222],
  "status": "PROCESSING"
}

GET Consulta o Registro do merchantID

Consulte o MerchantID com base no registerID ou no mainMerchantID.

Response

GET /edi?registerID=&mainMerchantID=

Headers

Key	Value
Authorization	Bearer + access_token
registerID	O registerID é fornecido pela operação /edi/registers ao se registrar. Pode ser usado no lugar de mainMerchantID, se preferir (apenas um precisa ser informado).
mainMerchantID	A maneira mais comum de recuperar um registro EDI na empresa. Pode ser usado em vez de registerID, principalmente em casos de registro não realizados por /edi/registers.

{
  "legalEntityNumer": "12314314",
  "mainMerchantId": 9999111222,
  "registerID": 12345,
  "merchants": [9999111111, 9999111333],
  "type": ["SELL"],
  "acknowledge": "COMPLETED"
}

PUT Atualizar o Registro do merchantID

Atualize o merchantID com base no registerID ou mainMerchantID.

Request

PUT /edi

Headers

Key	Value
Authorization	Bearer + access_token

{
  "registerID": "string",
  "mainMerchantId": "9999222333",
  "merchants": ["9999222111", "9999222222"],
  "type": ["SELL"]
}

Response

{
  "legalEntityNumber": "01234567890",
  "mainMerchantId": 9999111222,
  "registerID": 12345,
  "merchants": [9999222333, 9999111222],
  "type": ["SELL"]
}

DELETE Excluir o Registro do merchantID

Consulte o MerchantID com base no registerID ou no mainMerchantID.

Response

DELETE /edi

Headers

Key	Value
Authorization	Bearer + access_token
registerID	O registerID é fornecido pela operação /edi/registers ao se registrar. Pode ser usado no lugar de mainMerchantID, se preferir (apenas um precisa ser informado).
mainMerchantID	A maneira mais comum de recuperar um registro EDI na empresa. Pode ser usado em vez de registerID, principalmente em casos de registro não realizados por /edi/registers.

{
  "legalEntityNumer": "12314314",
  "mainMerchantId": 9999111222,
  "registerID": 12345,
  "acknowledge": "COMPLETED"
}

Duplicação de matriz

A duplicação de registro funciona com base no retorno do GET /merchantgroup, se retornar “unavailable” significa que esse merchant já possui vínculo com alguma conciliadora.

GET /merchantgroup

{
  "legalEntityNumber": "67625512",
  "branches": [
    {
      "merchantID": "2006907071",
      "legalEntityNumber": "67.625.512/0001-14",
      "businessName": "MERCHANTI",
      "status": "UNAVAILABLE"
    }
  ]
}

Com isso, será necessário efetuar um novo GET para saber se você pode ou não vincular essa cadeia de merchant a sua conciliadora, que nesse caso é o GET /mainmerchants, se você obter o status “available” no campo “ediStatus”, significa que você poderá fazer a duplicação de matriz via API.

GET /mainmerchants

[
  {
    "registerID": "38724",
    "mainMerchantID": "2006907071",
    "merchants": ["2006907071"],
    "type": ["SELL", "BALANCE"],
    "ediStatus": "AVAILABLE"
  }
]

GET /mainmerchants pode retornar mais de um objeto, com isso, se o objeto estiver como “available”, será necessário efetuar uma chamada de PUT para cada objeto. Os objetos que retornarem “unavailable”, será necessário solicitar a duplicação manual através do edi@cielo.com.br (lembrando que isso representa apenas 10% dos casos, após a implementação da duplicação através do método PUT).

Com isso, deverá ser feita uma chamada de PUT /edi no qual, irá fazer a duplicação da matriz.

PUT /edi

{
  "mainMerchantID": "2006907071",
  "registerID": "38724",
  "merchants": ["2006907071"],
  "type": ["SELL", "PAYMENT"]
}

O header de todas essas requisições permanecem da mesma forma, deve ser informado o Authorization, como nas demais chamadas desta API. Com base no retorno do GET /mainmerchants, será necessário informar o registerID, mainMerchantID e as filiais no array de merchants da chamada de PUT.

Transmissão e reenvio de arquivo

Para clientes que não utilizam conciliador terceirizado, o recebimento dos arquivos pode ocorrer da seguinte forma: Download no site da Cielo www.cielo.com.br. Ao realizar o login no site, os arquivos estão disponíveis na guia Serviços > acessar Extrato Eletrônico.

Para clientes que utilizam um conciliador de mercado, todo o processo de solicitação e envio de extratos é realizado diretamente pelo conciliador.

Reenvio de arquivos

Para cliente, basta localizar o arquivo e efetuar o download no Site Cielo. Para conciliadora, caso seja necessário o reenvio dos arquivos, deve contatar o Atendimento EDI (edi@cielo.com.br) indicando as matrizes de extrato, data dos arquivos e tipo de arquivo.

Reprocessamento de arquivos

Permite o reprocessamento (geração de um novo arquivo) de uma data anterior, atualizando o status dos lançamentos conforme visão atual da agenda financeira. Os arquivos são disponibilizados separadamente do arquivo diário e identificados com o sequencial “9999999” no header. A solicitação deve ser encaminhada para o Atendimento EDI (edi@cielo.com.br). Esta função não está disponível para extratos de Saldo em Aberto (09)