Introdução
Esse é o método pelo qual o extrato é solicitado ao Open Finance onde as movimentações bancárias existentes na conta (e disponíveis no Open Finance) são localizadas e replicadas na Tecnospeed.
Se trata da primeira etapa do processo assíncrono, onde o sistema integrado com nossa API poderá realizar a busca pelo extrato e obterá um protocolo. Este protocolo deverá ser consultado na segunda etapa do processo de consulta, para que se tenha acesso ao resultado da busca do extrato e suas movimentações.
Definições da requisição:
Método
POST
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: 1 requisição de sucesso a cada 6 horas.
Obs: Essa limitação funciona como créditos mensais do lado do Open Finance, portanto, esses créditos são cuidadosamente distribuídos ao longo do mês para garantir a disponibilidade do serviços durante todo o período.
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) |
Body
O body da requisição é enviado em formato JSON. Portanto os parâmetros de envio são:
| Campo | Tipo | Descrição | Valores aceitos |
| dateStart | string |
Data de início da busca pelo extrato. | 2025-01-30 |
| dateEnd | string |
Data de início da busca pelo extrato. | 2025-01-30 |
| today | boolean |
Quando ativo, retornará somente as movimentações do dia atual. | true/false |
| accountHash | string |
Identificador da conta que está solicitando o extrato |
AccountHash válido, cadastrado previamente, pertencente ao CNPJ do Pagador informado no header da requisição. O cadastro da conta é feito através deste processo. |
Exemplo de Retorno
Status=201 - Sucesso
Onde:
| Campo | Tipo | Descrição |
|---|---|---|
| uniqueId | string | Protocolo de recebimento do pedido. Este protocolo deverá ser registrado pelo sistema do cliente e consultado na rota GET que mostra efetivamente o resultado da consulta. |
| status | string | Identifica se a requisição entrou para a fila de processamento da API. Em caso de sucesso é esperado o status='Processing', que indica que o arquivo entrou na fila de processamento da API. |
Status=400 - Falha no processamento
{
"uniqueId": "_dhrDuJUAxD55c",
"error": "Falha ao criar extrato: Error: Error: connect ECONNREFUSED 127.0.0.1:8080"
}
Onde:
| Campo | Tipo | Descrição |
|---|---|---|
| code | number | Código de erro que identifica a falha na autorização da requisição |
| uniqueId | string | Protocolo de recebimento do pedido. |
| error | string | Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota |
Status=401 - Falta de autorização
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 o CNPJ e token de SH informados estão corretos (cadastrados de acordo com este processo) |
Status=401 - Falta de autorização
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. |
Obs.: Caso a Software House não possua contrato para uso da API de Extratos via Open Finance junto à Tecnospeed e tenha interesse em obtê-lo, entre em contato com nosso departamento comercial para que possamos iniciar a apresentação do recurso e do contrato.
Status=404 - Conta não encontrada
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 conta informada no body não foi encontrada ou não pertence ao CNPJ do Pagador presente na autenticação. Recomenda-se conferir o accountHash cadastrado neste processo. |
Status=422 - Falha no processamento
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 > 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 conta utilizada no header da requisição não possui autorização para uso do Extrato via Open Finance. |
| errors > internalCode | numérico | Código de erro (mapeamento dos códigos ainda não disponível) |
Obs.: Caso a Software House não possua contrato para uso da API de Extratos via Open Finance junto à Tecnospeed e tenha interesse em obtê-lo, entre em contato com nosso departamento comercial para que possamos iniciar a apresentação do recurso e do contrato.
Comentários
0 comentário
Por favor, entre para comentar.