API LURI v2 — Documentação Oficial de Integração

Bem-vindo à documentação oficial da API LURI v2 (v2.6.4). Nossa plataforma oferece infraestrutura financeira BaaS (Banking as a Service) e meios de pagamento para emissão e gestão de Boletos Bancários, Boletos Híbridos (Boleto + Pix), Cobranças Pix (static, cob, cobv), Contas Digitais (Saldos e Extratos), Sellers e Webhooks em Tempo Real.

Regras Gerais e Convenções da API (`https://api.luri.io/v2`)

• Formato de Comunicação: Todas as requisições e respostas utilizam JSON (Content-Type: application/json; charset=utf-8) sobre HTTPS (TLS 1.2+).
• Convenção de Valores em "Centavos" (Inteiros): Nos endpoints de cobrança (/v2/charge e /v2/charge/pix) e nos webhooks boleto.* e pix.*, todos os valores monetários e percentuais (amount, late_fee_amount, late_fee_percentage, interest_amount, interest_percentage, abatement_amount, discount[].amount) são representados como números inteiros com 2 casas decimais implícitas (sem ponto ou vírgula). Exemplo: 15000 = R$ 150,00; 200 = R$ 2,00 ou 2,00%.
• Autenticação e Escopos (Basic Auth vs. JWT RS256):
  • Basic Auth: Aceito nos endpoints de cobrança (/v2/charge, /v2/charge/pix), impressão (/v2/print), /v2/sellers, /v2/leads, /v2/webhooks e no cadastro inicial de chave pública (POST /v2/auth/public-keys).
  • JWT RS256 (Bearer Token): Aceito em todos os endpoints da API e obrigatório para consulta de contas e extratos (/v2/accounts), gestão de chaves públicas (GET/DELETE /v2/auth/public-keys) e recebimento de webhooks de movimentação em conta (account.*).
• Suporte Nativo a Agentes de IA (llmstxt.org): Esta documentação disponibiliza llms.txt, llms-full.txt e ai-catalog.json otimizados para LLMs (Cursor, Claude, ChatGPT, Perplexity, GitHub Copilot).

Documentação Técnica por Módulo (Arquivos Markdown)

• Visão Geral e Arquitetura (OVERVIEW.md) — Regras gerais, convenção de centavos e arquitetura BaaS.
• Autenticação Basic Auth e JWT RS256 (AUTH.md) — Geração de par de chaves RSA 2048+ bits, claims obrigatórias (iss, exp) e rotação de chaves públicas.
• Pré-Cadastro de Contas / Leads (PRE_CADASTRO.md) — Envio de leads PF/PJ (POST /v2/leads) com convite via WhatsApp.
• Gestão de Sellers (SELLERS.md) — Consulta de estabelecimentos vinculados ao marketplace (GET /v2/sellers).
• Emissão e Gestão de Boletos (BOLETOS.md) — Boleto tradicional e Boleto Híbrido (Boleto + Pix), juros, multa, desconto, abatimento, protesto, split e impressão PDF/Carnê.
• API de Cobranças Pix (PIX.md) — Auto-detecção static, cob e cobv, encargos avançados, conciliação ativa e consulta de pagamentos.
• Contas Digitais — Saldos e Extratos (ACCOUNTS.md) — Listagem de contas, saldo em tempo real e extrato paginado (exclusivo JWT RS256).
• Webhooks de Cobrança e Eventos em Conta (WEBHOOKS.md) — Eventos boleto.*, pix.*, account.* e public_key.* com validação HMAC-SHA256 (X-Webhook-Signature).
• Collection Postman Oficial (COLLECTION.md) — Download e guia de uso do arquivo LURI v2.postman_collection.json.
• Changelog da API LURI v2 (changelog.html) — Histórico detalhado de versões até a v2.6.4.

Mapa Completo de Endpoints da API LURI v2

Módulo	Método	Endpoint	Autenticação	Resumo Funcional
Autenticação	POST	/v2/auth/public-keys	Basic Auth	Cadastra nova chave pública RSA (PEM, 2048+ bits) para JWT RS256
Autenticação	GET	/v2/auth/public-keys	JWT (Bearer)	Lista chaves públicas ativas, revogadas e legadas do marketplace
Autenticação	DELETE	/v2/auth/public-keys/{kid}	JWT (Bearer)	Revoga uma chave pública específica com trava anti-lockout
Pré-Cadastro	POST	/v2/leads	Basic Auth / JWT	Envia lead de abertura de conta correntista com disparo via WhatsApp
Sellers	GET	/v2/sellers	Basic Auth / JWT	Lista estabelecimentos (sellers) vinculados ao marketplace
Boletos	POST	/v2/charge	Basic Auth / JWT	Cria cobrança por Boleto Bancário ou Boleto Híbrido (Boleto + Pix)
Boletos	PATCH	/v2/charge/{id_boleto}	Basic Auth / JWT	Altera vencimento, valor, multa, juros, descontos, abatimento ou avalista
Boletos	POST	/v2/charge/{id_boleto}/cancel	Basic Auth / JWT	Solicita baixa ou cancelamento de boleto registrado
Boletos	GET	/v2/charge/{id_boleto}	Basic Auth / JWT	Consulta detalhes completos de um boleto por ID
Boletos	GET	/v2/charge/{id_boleto}/history	Basic Auth / JWT	Consulta trilha de auditoria e eventos do boleto
Boletos	GET	/v2/charge	Basic Auth / JWT	Listagem paginada de boletos com filtros
Boletos	POST	/v2/print	Basic Auth / JWT	Gera PDF ou HTML de impressão de boleto individual ou carnê
Pix	POST	/v2/charge/pix	Basic Auth / JWT	Cria cobrança Pix Estática (static), Dinâmica (cob) ou com Vencimento (cobv)
Pix	GET	/v2/charge/pix/{id_pix}	Basic Auth / JWT	Consulta cobrança Pix por id_pix ou txid
Pix	GET	/v2/charge/pix/{id_pix}/payments	Basic Auth / JWT	Consulta pagamentos e devoluções no liquidante e executa conciliação ativa
Pix	GET	/v2/charge/pix/{id_pix}/history	Basic Auth / JWT	Consulta histórico de eventos da cobrança Pix
Pix	GET	/v2/charge/pix	Basic Auth / JWT	Listagem paginada de cobranças Pix
Pix	GET	/v2/charge/pix/all	Basic Auth / JWT	Consulta consolidada de QR Codes Pix do seller no liquidante
Accounts	GET	/v2/accounts	Exclusivo JWT	Lista todas as contas ativas vinculadas aos sellers do marketplace
Accounts	GET	/v2/accounts/{account_id}/balance	Exclusivo JWT	Consulta em tempo real o saldo disponível, bloqueado e agendado da conta
Accounts	GET	/v2/accounts/{account_id}/statements	Exclusivo JWT	Consulta em tempo real o extrato bancário e resumo de saldos do período
Webhooks	POST	/v2/webhooks	Basic Auth / JWT	Cadastra ou atualiza URL HTTPS de webhook e gera webhook_secret
Webhooks	GET	/v2/webhooks	Basic Auth / JWT	Consulta configuração ativa de webhook do marketplace
Webhooks	DELETE	/v2/webhooks/{hash_marketplace}	Basic Auth / JWT	Remove configuração de webhook e revoga webhook_secret