Despesas Recorrentes

DESPESAS

Detalhamento das despesas mensais do CPF por categoria (moradia, essenciais, obrigações financeiras, compras/lazer e transferências recorrentes).

Endpoint

POST /api/client/provider/open-finance

Método

POST

Autenticação

Bearer JWT

Descrição

Retorna o detalhamento das despesas mensais do CPF por categoria, estimadas a partir da movimentação Open Finance.

Request Body

Content-Type: application/json

Campo	Tipo	Obrigatorio	Descricao
document	string	Sim	CPF do consultado (11 dígitos, somente números).
product_code	array	Sim	Lista de códigos de produto a consultar. Pode combinar vários relatórios Open Finance numa única requisição.

Exemplo

{
    "document": "12345678901",
    "product_code": [
        "DESPESAS"
    ]
}

Exemplo cURL

curl -X POST \
  https://positivaconnect.positivaconsultas.com.br/api/client/provider/open-finance \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12345678901",
    "product_code": ["DESPESAS"]
  }'

Formato do Envelope de Resposta

200 OK

{
  "success": true,
  "document": "12345678901",
  "provider": "open-finance",
  "query_date": "2026-03-18T10:00:00",
  "results": {
    "DESPESAS": {
      "success": true,
      "data": { ... }
    }
  }
}

Quando results.DESPESAS.success for false, indica falha de comunicação com o provider externo (timeout, erro 5xx). Erros de autorização são rejeitados antes da consulta com HTTP 403.

Campos do `data`

Campo	Descrição
reportStatus	Código HTTP do status do relatório na Klavi (200 = sucesso).
requestId	Identificador único da requisição na Klavi.
productName	Código do produto consultado na Klavi (ex.: pf_klavi_income_eco).
productVersion	Versão do produto (ex.: V1).
productReportTime	Data e hora de geração do relatório (ISO 8601).
enquiryCpf	CPF consultado.
expenses.labelDetails	Array de indicadores. Cada item tem labelCode, labelName e labelValue.
expenses.labelDetails[].labelCode	P000007 (Despesas totais), P000002 (Obrigações Financeiras), P000003 (Moradia e Utilidades), P000004 (Gastos Essenciais), P000005 (Compras e Lazer), P000006 (Transferências Recorrentes). Valores em R$.
expenses.personalInfo.civilName	Nome civil do consultado.
expenses.personalInfo.accounts	Instituições Open Finance vinculadas (bacenName, brandName, compeCode).

Exemplo de Resposta

Conteúdo de results.DESPESAS.data

200 OK

{
    "reportStatus": 200,
    "requestId": "064a7128cc334166891c59b0598e0cbf",
    "productName": "pf_klavi_expenses_eco",
    "productVersion": "V1",
    "productReportTime": "2026-08-19T17:49:23.932Z",
    "enquiryCpf": "76109277673",
    "expenses": {
        "labelDetails": [
            {
                "labelCode": "P000007",
                "labelName": "Expenses",
                "labelValue": 79.24
            },
            {
                "labelCode": "P000004",
                "labelName": "Living Essential Expenses",
                "labelValue": 36.95
            },
            {
                "labelCode": "P000002",
                "labelName": "Financial Obligation Expenses",
                "labelValue": 0
            },
            {
                "labelCode": "P000003",
                "labelName": "Housing and Utilities Expenses",
                "labelValue": 23.9
            },
            {
                "labelCode": "P000006",
                "labelName": "Recurring transfers",
                "labelValue": 18.39
            },
            {
                "labelCode": "P000005",
                "labelName": "Shopping and Leisure Expenses",
                "labelValue": 0
            }
        ],
        "personalInfo": {
            "accounts": [
                {
                    "bacenName": "Klavi OP Mock Institution",
                    "brandName": "Banco Brasileiro",
                    "compeCode": "11110"
                }
            ],
            "civilName": "Tatiana Galvão"
        }
    }
}

Respostas de Erro

400

invalid_request

Documento inválido, product_code ausente ou vazio

401

unauthenticated

Token JWT ausente ou inválido

403

product_not_authorized

Um ou mais produtos informados não estão contratados. A requisição inteira é rejeitada.

404

product_not_found

Um dos códigos em product_code não existe ou está inativo