Valloria Group

Nexus API

Gestao Centralizada e Padronizada

Referencia operacional da Nexus para agendamento, disparo, consulta de retornos persistidos e consumo consolidado de saldo + extrato.

Downloads

Baixar Postman collection

Collection pronta para importar no Postman com variaveis de ambiente.

JSON

Baixar OpenAPI

Especificacao OpenAPI 3.1 usada como referencia tecnica de contrato.

JSON

Autenticacao

Autenticacao e escopos

O acesso usa emissao de Bearer JWT via client_credentials e separa leitura, escrita de schedules e execucao manual por escopo.

  1. 1Receba client_id e client_secret provisionados pela Valloria.
  2. 2Chame POST /v1/auth/token.
  3. 3Receba um access_token JWT.
  4. 4Envie Authorization: Bearer <access_token> nas demais rotas.
Emissao de tokenbash
curl -X POST "{{AUTH_BASE_URL}}/v1/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=client_demo&client_secret=secret_demo"
Resposta de tokenjson
{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "statements.read statements.write statements.run"
}

Fluxo recomendado

Fluxo recomendado de implementacao

O caminho recomendado desacopla autenticacao, preparo de conta, coleta e consumo, o que deixa a integracao mais previsivel.

  1. 1Emitir token em POST /v1/auth/token.
  2. 2Opcionalmente validar credenciais bancarias com GET /v1/banks/{bank_code}/preflight.
  3. 3Criar um schedule em POST /v1/statements/schedules.
  4. 4Aguardar o horario agendado ou disparar POST /v1/statements/schedules/run.
  5. 5Consultar GET /v1/statements/availability.
  6. 6Consumir GET /v1/statements/query, GET /v1/statements/balances ou GET /v1/statements/overview.

Schedules

Rotas de preflight e orquestracao de schedules

Estas rotas cobrem validacao bancaria, criacao, consulta, atualizacao, desativacao e disparo manual do pipeline de coleta.

GET/v1/banks/{bank_code}/preflight

Validar se a configuracao bancaria do tenant esta pronta para uso no ambiente informado.

Scope

statements.read

Requestbash
curl -X GET "{{API_BASE_URL}}/v1/banks/ITAU/preflight?environment=sandbox" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"
Respostajson
{
  "bank_code": "ITAU",
  "tenant_id": "tenant-demo",
  "environment": "sandbox",
  "status": "ok",
  "preflight": {
    "ready": true
  }
}

Erros comuns

  • 400 preflight_validation_failed
  • 404 not_found
  • 500 preflight_internal_error
POST/v1/statements/schedules

Criar um agendamento de coleta.

Scope

statements.write

Regras

  • Prefira account_id.
  • Quando a conta ainda nao for conhecida no tenant, envie bank_code.
  • Quando nao houver account_id, envie a identificacao minima exigida pelo banco.
Requestbash
curl -X POST "{{API_BASE_URL}}/v1/statements/schedules" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_code": "ITAU",
    "environment": "sandbox",
    "account_id": "acc_demo_001",
    "run_times": ["09:00", "18:00"],
    "timezone": "America/Sao_Paulo",
    "retention_days": 30,
    "webhook_enabled": false,
    "enabled": true
  }'
Respostajson
{
  "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
  "enabled": true,
  "status": "active",
  "purge_after": null
}

Erros comuns

  • 400 bank_code_required_for_unregistered_account
  • 400 bad_request
  • 409 account_id_bank_conflict
GET/v1/statements/schedules

Listar schedules do tenant autenticado.

Scope

statements.read

Requestbash
curl -X GET "{{API_BASE_URL}}/v1/statements/schedules" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"
Respostajson
{
  "schedules": [
    {
      "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
      "tenant_id": "tenant-demo",
      "bank_code": "ITAU",
      "environment": "sandbox",
      "account_type": "current_account",
      "run_times": ["09:00", "18:00"],
      "timezone": "America/Sao_Paulo",
      "retention_days": 30,
      "page_size": 1000,
      "account_id": "acc_demo_001",
      "webhook_enabled": false,
      "enabled": true,
      "status": "active",
      "last_run_keys": [],
      "created_at": "2026-03-15T12:00:00+00:00",
      "updated_at": "2026-03-15T12:00:00+00:00"
    }
  ]
}
GET/v1/statements/schedules/{schedule_id}

Consultar um schedule especifico.

Scope

statements.read

Erros comuns

  • 404 schedule not found
GET/v1/statements/schedules/{schedule_id}/next

Retornar a proxima execucao prevista para um schedule elegivel.

Scope

statements.read

Respostajson
{
  "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
  "status": "active",
  "timezone": "America/Sao_Paulo",
  "next_run_at": "2026-03-15T18:00:00-03:00"
}
PUT/v1/statements/schedules/{schedule_id}

Atualizar um schedule existente.

Scope

statements.write

Importante

  • Segue as mesmas regras de identificacao da rota de criacao.
  • Se o schedule estiver em expurgo pendente, a API nao permite reativacao por update.

Erros comuns

  • 404 schedule not found
  • 409 schedule_pending_purge
  • 409 account_id_bank_conflict
POST/v1/statements/schedules/{schedule_id}/toggle

Desativar um schedule ou confirmar o estado atual.

Scope

statements.write

Importante

  • O schedule fica consultavel por ate 4 horas.
  • Schedules nessa janela nao sao executados.
  • Apos expurgo, o mesmo schedule_id nao volta.
Requestjson
{
  "enabled": false
}
Respostajson
{
  "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
  "enabled": false,
  "status": "disabled_pending_purge",
  "purge_after": "2026-03-15T16:00:00+00:00"
}

Erros comuns

  • 404 schedule not found
  • 409 schedule_pending_purge
POST/v1/statements/schedules/run

Disparar manualmente a execucao dos schedules ativos do tenant.

Scope

statements.run

Requestbash
curl -X POST "{{API_BASE_URL}}/v1/statements/schedules/run" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"
Respostajson
{
  "tenant_id": "tenant-demo",
  "triggered_at": "2026-03-15T12:15:00+00:00",
  "request_id": "7e4357d4-4d4f-4703-bf62-ea1886b42335",
  "eligible_schedules": 2,
  "dispatched_runs": 2,
  "ignored_schedules": [
    {
      "schedule_id": "9f9fb1ef-e6df-4ff2-b5ef-c2e4bf74f76e",
      "bank_code": "ITAU",
      "status": "disabled_pending_purge",
      "reason": "disabled_or_pending_purge"
    }
  ],
  "runs": [
    {
      "run_id": "run_demo_001",
      "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
      "bank_code": "ITAU",
      "status": "DONE"
    }
  ]
}

Runs

Rotas de runs e download de artefatos

Depois do disparo, estas rotas permitem inspecionar metadados de execucao e baixar artefatos persistidos quando houver justificativa tecnica.

GET/v1/statements/runs

Listar runs do tenant com filtros por banco, conta e periodo.

Scope

statements.read

Filtros

  • bank_code
  • date_from
  • date_to
  • account_id
  • branch_code
  • account_number
  • investment_account
Requestbash
curl -X GET "{{API_BASE_URL}}/v1/statements/runs?account_id=acc_demo_001&date_from=2026-03-01&date_to=2026-03-15" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"
GET/v1/statements/runs/{run_id}

Consultar metadados de um run especifico.

Scope

statements.read

Erros comuns

  • 404 run not found
GET/v1/statements/runs/{run_id}/download

Baixar o artefato persistido de um run concluido.

Scope

statements.read

Importante

  • A rota pode retornar payloads mais sensiveis que as rotas normalizadas.
  • Use apenas quando houver necessidade tecnica legitima.
  • Armazene o arquivo com controles adequados de acesso, criptografia e retencao.

Erros comuns

  • 404 run not found
  • 400 bad_request quando o run ainda nao foi concluido

Consumo

Rotas de disponibilidade e consumo normalizado

Estas rotas sao o ponto de consumo do material ja persistido e normalizado para saldo, extrato e visao consolidada.

GET/v1/statements/availability

Descobrir, em um intervalo de datas, quais retornos ja estao prontos para consumo.

Scope

statements.read

Quando usar

  • Chame availability antes de query, balances ou overview quando quiser confirmar se o material do periodo ja foi coletado.
Requestbash
curl -X GET "{{API_BASE_URL}}/v1/statements/availability?account_id=acc_demo_001&date_from=2026-03-01&date_to=2026-03-10" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"
Respostajson
{
  "bank_code": "ITAU",
  "account_id": "acc_demo_001",
  "requested_range": {
    "date_from": "2026-03-01",
    "date_to": "2026-03-10"
  },
  "available_dates": [
    {
      "date": "2026-03-05",
      "available_routes": ["balances", "overview", "query"],
      "statement_events_count": 12,
      "balance_items_count": 1,
      "latest_run": {
        "run_id": "run_demo_001",
        "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
        "status": "DONE",
        "start_date": "2026-03-05",
        "end_date": "2026-03-05",
        "updated_at": "2026-03-05T12:10:00+00:00",
        "normalized_schema": "statement.v1"
      }
    }
  ]
}

Erros comuns

  • 400 missing_date_range
  • 400 invalid_date_range
GET/v1/statements/query

Consultar extratos normalizados ja persistidos.

Scope

statements.read

Regras

  • account_id e preferencial.
  • bank_code pode ser omitido quando a conta ja for conhecida no tenant.
  • A rota nao consulta banco em tempo real.
Requestbash
curl -X GET "{{API_BASE_URL}}/v1/statements/query?account_id=acc_demo_001&date_from=2026-03-01&date_to=2026-03-10" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"
Respostajson
{
  "items": [
    {
      "run": {
        "run_id": "run_demo_001",
        "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
        "bank_code": "ITAU",
        "status": "DONE"
      },
      "normalized": {
        "events": [
          {
            "id": "evt_001",
            "posted_at": "2026-03-05",
            "amount": "-150.00",
            "currency": "BRL",
            "description": "PIX ENVIO"
          }
        ],
        "balances": [
          {
            "amount": "9840.10",
            "currency": "BRL"
          }
        ],
        "pagination": {
          "page": 1
        }
      },
      "raw": {
        "statement_available": true
      }
    }
  ]
}
GET/v1/statements/balances

Consultar saldos normalizados ja persistidos.

Scope

statements.read

Requestbash
curl -X GET "{{API_BASE_URL}}/v1/statements/balances?account_id=acc_demo_001&date_from=2026-03-01&date_to=2026-03-10" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"
Respostajson
{
  "items": [
    {
      "run": {
        "run_id": "run_demo_001",
        "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
        "bank_code": "ITAU",
        "status": "DONE"
      },
      "balances": [
        {
          "amount": "9840.10",
          "currency": "BRL"
        }
      ],
      "raw": {
        "balance_available": true
      }
    }
  ]
}
GET/v1/statements/overview

Consultar saldo + extrato em uma unica resposta.

Scope

statements.read

Quando usar

  • Quando o consumidor quer uma chamada unica por conta.
  • Quando nao precisa separar consulta de saldo e extrato.
Requestbash
curl -X GET "{{API_BASE_URL}}/v1/statements/overview?account_id=acc_demo_001&date_from=2026-03-01&date_to=2026-03-10" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}"
Respostajson
{
  "bank_code": "ITAU",
  "account_id": "acc_demo_001",
  "account": {
    "bank_id": null,
    "branch_code": null,
    "account_number": null,
    "account_id": "acc_demo_001",
    "account_type": "current_account"
  },
  "balances": [
    {
      "amount": "9840.10",
      "currency": "BRL"
    }
  ],
  "statements": {
    "events": [
      {
        "id": "evt_001",
        "posted_at": "2026-03-05",
        "amount": "-150.00",
        "currency": "BRL",
        "description": "PIX ENVIO"
      }
    ],
    "pagination": {
      "page": 1
    }
  },
  "run_context": {
    "run_id": "run_demo_001",
    "schedule_id": "f5a8c4dd-f8d9-4b8f-bf7f-428aeb190d39",
    "status": "DONE",
    "start_date": "2026-03-05",
    "end_date": "2026-03-05",
    "updated_at": "2026-03-05T12:10:00+00:00",
    "normalized_schema": "statement.v1"
  },
  "raw_available": true
}

Erros e compliance

Catalogo de erros, LGPD e compliance

A API padroniza erros operacionais e exige controles claros sobre segredos, rastreabilidade e armazenamento de artefatos sensiveis.

  • unauthorized: token ausente, invalido ou expirado.
  • forbidden: escopo insuficiente ou tenant bloqueado.
  • invalid_client: client_id ou client_secret invalidos.
  • client_disabled: cliente desativado.
  • unsupported_grant_type: grant diferente de client_credentials.
  • invalid_request: request de token invalido.
  • rate_limited: limite por tenant ou auth excedido.
  • validation_error: payload, query string ou schema invalido.
  • preflight_validation_failed: credenciais/configuracao do banco nao estao prontas.
  • preflight_internal_error: falha interna no preflight.
  • bank_code_required_for_unregistered_account: a conta ainda nao era conhecida no tenant.
  • account_id_bank_conflict: o account_id ja esta associado a outro banco no tenant.
  • schedule_pending_purge: schedule desativado e em janela de expurgo.
  • internal_error: falha inesperada.

Downloads

Assets para importacao e manutencao futura

A pagina tambem funciona como ponto de distribuicao da collection Postman e da especificacao OpenAPI usadas como base para evolucao futura.

  1. 1Importe a collection Postman ou o arquivo OpenAPI.
  2. 2Configure as variaveis AUTH_BASE_URL, API_BASE_URL e ACCESS_TOKEN.
  3. 3Use esta pagina como guia humano para fluxo, exemplos, erros e compliance.
  • Fora de escopo: endpoints internos.
  • Fora de escopo: fluxos de observabilidade.
  • Fora de escopo: detalhes de storage, DynamoDB, S3 ou workers.
  • Fora de escopo: credenciais bancarias por banco.
  • Fora de escopo: dados pessoais reais de clientes finais.

Collection Postman

Importe direto no Postman e ajuste AUTH_BASE_URL, API_BASE_URL e ACCESS_TOKEN.

JSON

OpenAPI 3.1

Referencia de contrato para gerar clients, mocks e revisoes de payload.

JSON