Pular para o conteúdo principal

Busca de Movimentos Financeiros de Extrato Open Finance (Protocolo Detalhado)

Yago Xavier
Atualizado

Introdução

A consulta do processamento do protocolo do Extrato Open Finance via UniqueID (valor este, retornado no campo "uniqueId" da primeira etapa do processo) é a segunda etapa do fluxo, e é o momento onde o resultado do processamento do extrato será verificado.

 

O objetivo aqui é visualizarmos o resultado do processamento do extrato ou eventuais erros que tenham ocorrido.

 

Definições da requisição:

 

Método

GET

 

URL da API

   Homologação:

https://staging.pagamentobancario.com.br/api/v1/statement/openfinance/[UniqueID]

   Produção:

https://api.pagamentobancario.com.br/api/v1/statement/openfinance/[UniqueID]

 

Rate Limit: 3 requisições por minuto.

Cache: Duração de 1 hora.

Obs: Caso ainda dentro da duração do cache outro extrato seja gerado, o cache atual será excluído e criado novamente somente após a próxima consulta, garantindo que a informação esteja atualizada.

 

Onde:

[UniqueID] se trata do valor retornado no campo "UniqueID" do JSON de resposta da solicitação do extrato.

Headers

Os headers necessários para a autenticação da requisição são:

 Header  Descrição
 cnpjsh  CNPJ da Software House que possui contrato com a Tecnospeed
 tokensh  Token de autenticação da Software House (obtido através deste processo)
payercpfcnpj CNPJ do pagador que será responsável pela consulta do Extrato. CNPJ cadastrado através deste processo)

 

Exemplo de Retorno

Status=200 - Sucesso

{
    "statement": {
        "uniqueId": "a-lvOjj6oC0NXU",
        "bankCode": "208",
        "totalTransactions": "2",
        "origin": "OPENFINANCE",
        "accountHash": "gDyriq_q39"
    },
    "transaction": {
        "credit": [],
        "debit": []
    },
    "transactionDuplicated": {
        "credit": [
            {
                "transactionId": "048ffd42-4ae0-4344-9c51-c60a2b406dea",
                "transactionType": "credit",
                "code": "DIGITALSERVICES",
                "amount": "18.99",
                "date": "2024-10-20",
                "sequence": 1,
                "description": "DL*GOOGLEYouTube",
                "fitid": null,
                "name": "John Doe",
                "category": "Digital services",
                "paymentName": null,
                "paymentMethod": null,
                "paymentBarcode": null,
                "paymentBaseAmount": null,
                "paymentDigitableLine": null,
                "paymentDiscountAmount": null,
                "paymentInterestAmount": null,
                "paymentPenaltyAmount": null
            }
        ],
        "debit": [
            {
                "transactionId": "108ffd42-4ae0-4344-9c51-c60a2b406deB",
                "transactionType": "debit",
                "code": "SERVICES",
                "amount": "100.00",
                "date": "2025-09-09",
                "sequence": 1,
                "description": "Pagamento de boleto",
                "fitid": null,
                "name": "PLUGGY",
                "category": "Services",
                "paymentName": null,
                "paymentMethod": null,
                "paymentBarcode": null,
                "paymentBaseAmount": "90.00",
                "paymentDigitableLine": "11190000111001113911100000021110600000000111000",
                "paymentDiscountAmount": "0.00",
                "paymentInterestAmount": "10.00",
                "paymentPenaltyAmount": null
            }
        ]
    },
    "balance": {
        "inicial": {
            "date": "2024-10-20",
            "balance": "100.00"
        },
        "final": {
            "date": "2025-09-09",
            "balance": "18.99"
        }
    }
}

 

Onde:

Campo Tipo Descrição
statement.uniqueId string Identificador do protocolo do Extrato Open Finance.
statement.bankCode string Código da instituição bancária.
statement.totalTransactions string Quantidade de transações contidas no extrato.
statement.origin string Origem do extrato. 
statement.accountHash string Código da conta detentora do extrato.
transacion/transactionDuplicated array Ambos as opções possuem os mesmos campos em seu conteúdo. A diferença está na validação de duplicidade. Portanto, quando um movimento já existir em outros extratos, o transactionDuplicated será preenchido.
transacion.credit.transactionType string Tipo da transação de crédito ou débito.
transacion.credit.code string Código da transação utilizada para identificar o tipo na qual a transação se refere.
transacion.credit.amount string Valor monetário. Ex: 18.99
transacion.credit.date string Data do lançamento da transação. Formato: 2025-09-09. 
Mais detalhes sobre as datas de transações.
transacion.credit.sequence number Sequencial da transação.
transacion.credit.description string Descrição da transação.
transacion.credit.fitid string Identificação padrão de extratos.
transacion.credit.name string Nome da empresa ou pessoa referenciada. 
transacion.credit.category string Categoria da transação. Exemplo: Restaurantes, Educação).
transacion.credit.paymentName string Nome do participante da transação.
transacion.credit.paymentMethod string Tipo de transação. Exemplo: TED, DOC, PIX, TEV ou BOLETO.
transacion.credit.paymentBarCode string Código de barras da transação.
transacion.credit.paymentBaseAmount string Valor base da transação.
transacion.credit.paymentDigitableLine string Linha digitável da transação.
transacion.credit.paymentDiscountAmount string Valor de desconto da transação.
transacion.credit.paymentInterestAmount string Valor de juros da transação.
transacion.credit.paymentPenaltyAmount string Valor de multa da transação.
transacion.debit.transactionType string Tipo da transação de crédito ou débito.
transacion.debit.code string Código da transação utilizada para identificar o tipo na qual a transação se refere.
transacion.debit.amount string Valor monetário. Exemplo: 18.99
transacion.debit.date string Data do lançamento da transação. Formato: 2025-09-09. 
Mais detalhes sobre as datas de transações.
transacion.debit.sequence number Sequencial da movimentação financeira.
transacion.debit.description string Descrição da movimentação financeira.
transacion.debit.fitid string Identificação padrão de extratos.
transacion.debit.name string Nome da empresa ou pessoa referenciada. 
transacion.debit.category string Categoria da transação. Exemplo: Restaurantes, Educação).
transacion.debit.paymentName string Nome do participante da transação.
transacion.debit.paymentMethod string Tipo de transação. Exemplo: TED, DOC, PIX, TEV ou BOLETO
transacion.debit.paymentBarCode string Código de barras da transação.
transacion.debit.paymentBaseAmount string Valor base da transação.
transacion.debit.paymentDigitableLine string Linha digitável da transação.
transacion.debit.paymentDiscountAmount string Valor de desconto da transação.
transacion.debit.paymentInterestAmount string Valor de juros da transação.
transacion.debit.paymentPenaltyAmount string Valor de multa da transação.
balance.inicial.date string Data inicial do extrato. Exemplo: 2025-09-09
balance.incial.balance string Balanço inicial antes da inclusão dessas transações. 
balance.final.date string Data final do extrato. Exemplo: 2025-09-09
balance.final.balance string Balanço final após a inclusão dessas transações.

 

Status=401 - Falta de autorização

{
    "code": 401,
    "message": "Payer não encontrado"
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string

Mensagem que identifica o tipo de erro ocorrido. Recomendamos que haja um mapeamento e apresentação desta mensagem ao usuário que efetua o envio do arquivo no sistema da SH. 

Neste caso, o erro indica que há uma falha na autenticação da requisição. Verifique se os 3 campos do header estão informados adequadamente

 

Status=401 - Falta de autorização

{
    "code": 401,
    "message": "Software House/Payer sem autorização para a função Extrato via Open Finance"
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string

Mensagem que identifica o tipo de erro ocorrido. Recomendamos que haja um mapeamento e apresentação desta mensagem ao usuário que efetua o envio do arquivo no sistema da SH. 

Neste caso, o erro indica que há uma falha na autenticação da requisição. Verifique se os 3 campos do header estão informados adequadamente

 

Status=401 - Falta de autorização

{
    "code": 401,
    "message": "CNPJ ou TOKEN incorretos, verifique sua conta em https://conta.tecnospeed.com.br"
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string

Mensagem que identifica o tipo de erro ocorrido. Recomendamos que haja um mapeamento e apresentação desta mensagem ao usuário que efetua o envio do arquivo no sistema da SH. 

 Neste caso, recomenda-se a validação das credenciais de autenticação da rota.

 

Status=404 - UniqueId não encontrado

{
    "code": 404,
    "message": "Extrato Open Finance não encontrado"
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string

Mensagem que identifica o tipo de erro ocorrido. Recomendamos que haja um mapeamento e apresentação desta mensagem ao usuário que efetua o envio do arquivo no sistema da SH. 

Neste caso, o erro indica que o uniqueId identificado na URL está incorreto.

 

 

Status=422 - Falta de autorização

{
    "code": 422,
    "message": "Unprocessable Entity",
    "errors": [
        {
            "message": "Campo cnpjsh é obrigatório",
            "internalCode": 4001
        }
    ]
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string  Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota
errors Objeto Lista de erros identificadas e que impossibilitaram o processamento da requisição
internalCode numérico

Código de erro interno

Obs.: Lista de erros em criação pela Tecnospeed
message string Mensagem de erro que orienta quanto ao problema. Neste caso, orienta-se que se verifique se todos os campos de autenticação (headers) estão preenchidos adequadamente.

Artigos relacionados

Comentários

0 comentário

Por favor, entre para comentar.