Listar Extratos - Últimos protocolos criados – Central de Atendimento

Introdução

A consulta dos últimos extratos processados é uma etapa opcional do fluxo. Nesta rota, retornaremos os últimos protocolos de extratos processados, com seus respectivos UniqueID.

O objetivo aqui é apresentar à SH uma lista dos arquivos processados, para que esta capture os UniqueId e faça a consulta completa.

Definições da requisição:

Método

GET

URL da API

Homologação:

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

Produção:

https://api.pagamentobancario.com.br/api/v1/statement/openfinance

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.

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)

Query Parameters

Parâmetro	Tipo	Descrição
`dateStart`	string	Data inicial que o protocolo do extrato foi criado (YYYY-MM-DD)
`dateEnd`	string	Data final que o protocolo do extrato foi criado (YYYY-MM-DD)
`accountHash`	string	Hash identificador da conta bancária
`page`	number	Número da página a ser retornada
`pageLimit`	number	Limite de registros por página Caso não informado, padrão 20 registros por página

Obs: Caso o dateStart e o dateEnd não sejam informados, serão consultados os útimos 7 dias.

Exemplo de Retorno

Status=200 - Sucesso

{
"data": [
{
"uniqueId": "a-lvOjj6oC0NXU",
"status": "SUCCESS",
"origin": "OPENFINANCE",
"createdAt": "2025-09-15 21:04:38",
"reason": null,
"accountHash": "guayFAISU12"
"totalTransactions": "2"
},
{
"uniqueId": "D0Vl9bDz3DNR91",
"status": "FAILED",
"origin": "OPENFINANCE",
"createdAt": "2025-09-15 21:04:24",
"reason": "Falha ao criar extrato: Error: nenhuma transação fornecida para conversão",
"accountHash": "guayFAISU12"
"totalTransactions": null
}
],
"meta": {
"page": "1",
"totalPages": 5
}
}

Onde:

Campo	Tipo	Descrição
uniqueId	string	Identificador do protocolo de busca do Extrato Open Finance (rota de solicitando extrato).
status	string	Status do processamento do arquivo SUCCESS: Retornado em caso de sucesso no processamento do arquivo FAILED: Retornado em caso de falha no processamento do arquivo. Verificar o campo "statement.reason"
origin	string	Origem do extrato OPENFINANCE
createdAt	string	Data de processamento do extrato: Formato: AAAA-MM-DDTHH:MM.SSSZ Exemplo: 2024-09-25T19:02:32.769Z
accountHash	string	Identificador da conta na qual o arquivo foi processado. Retorna o mesmo "accountHash" no qual o arquivo foi processado originalmente
reason	string	Retornado em caso de falha no processamento do arquivo. Quando sucesso, apenas null.
totalTransactions	string	Quantidade de movimentos financeiros dentro do extrato.

Obs.: Observe que os resultados aparecem de forma paginada. Portanto, é importante que a integração considere a possibilidade de trabalhar com diversas páginas, dentro do objeto "meta".

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": "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=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 a SH ou os pagadores cadastrados por ela não possuem autorização para uso do Extrato via Open Finance.

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.

Introdução

Definições da requisição:

Método

URL da API

Rate Limit: 3 requisições por minuto.

Cache: Duração de 1 hora.

Headers

Query Parameters

Exemplo de Retorno

Artigos relacionados