# LURI v2 API Documentation

> Documentação oficial da API LURI v2 (v2.6.4) para emissão e gestão de Boletos Bancários, Boletos Híbridos (Boleto + Pix), Cobranças Pix (`static`, `cob`, `cobv`), Contas Digitais BaaS (Saldos e Extratos), Gestão de Sellers, Autenticação Assimétrica JWT (RS256) e Webhooks de Cobrança e Eventos em Conta.

Diretrizes críticas para agentes de IA e integrações automatizadas (AI Coding Rules):

Base URL oficial: `https://api.luri.io/v2` (ou `{{base_url}}/v2`). Todas as requisições e respostas utilizam `Content-Type: application/json; charset=utf-8` sobre HTTPS (TLS 1.2+).

Convenção de valores monetários e percentuais ("Centavos"): 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 números inteiros representando 2 casas decimais implícitas (sem ponto ou vírgula). Exemplo: `15000` equivale a R$ 150,00; `200` equivale a R$ 2,00 ou 2,00%. Nos endpoints de conta (`/v2/accounts`) e nos webhooks de movimentação em conta (`account.*`), o campo `amount` é string decimal (`"80.00"`) acompanhado de `amount_cents` inteiro (`8000`).

Escopo de autenticação (Basic Auth vs. JWT RS256): Basic Auth (`Authorization: Basic <base64(token:)>` — username igual ao token e password em branco) é aceito nos recursos de cobrança (`/v2/charge`, `/v2/charge/pix`), `/v2/sellers`, `/v2/leads`, `/v2/webhooks`, `/v2/print` e no cadastro inicial de chave pública (`POST /v2/auth/public-keys`). JWT RS256 (`Authorization: Bearer <jwt>` assinado com Chave Privada RSA 2048+ bits, com claims obrigatórias `iss` igual ao `hash_marketplace` e `exp`) é aceito em todos os endpoints e obrigatório em `/v2/accounts` (saldos e extratos) e `GET/DELETE /v2/auth/public-keys`.

Escopo de Webhooks e verificação HMAC-SHA256: eventos de cobrança (`boleto.created`, `boleto.registered`, `boleto.failed`, `boleto.updated`, `boleto.canceled`, `boleto.paid`, `boleto.assign`, `pix.created`, `pix.paid`) são enviados para qualquer marketplace com `url_webhook` configurada. Boleto ou Boleto Híbrido pago (via código de barras ou QR Code Pix do boleto) dispara `type: "boleto.paid"` (com `payment_method: "boleto"` ou `"pix"`); cobrança Pix pura (`POST /v2/charge/pix`) paga dispara `type: "pix.paid"`; Pix avulso recebido diretamente na chave Pix/conta do seller dispara `type: "account.pix.received"` (exclusivo para marketplaces com credencial JWT ativa). Eventos `account.*` exigem `url_webhook` ativa e credencial JWT ativa (`/v2/auth/public-keys`). Valide sempre o cabeçalho HTTP `X-Webhook-Signature` calculando `hash_hmac('sha256', $rawRequestBody, $webhookSecret)` e comparando em tempo constante (`hash_equals`).

## Arquivos de Referência para LLMs

- [Documentação Completa Consolidada (llms-full.txt)](https://api.luri.io/v2/docs/llms-full.txt): Especificação completa de todos os módulos, endpoints, parâmetros, exemplos de requisição/resposta e catálogo de webhooks em um único arquivo Markdown.
- [Portal Interativo da Documentação (index.html)](https://api.luri.io/v2/docs/): Interface de referência da API LURI v2 com busca, exemplos e utilitários para IA.
- [Visão Geral e Arquitetura (OVERVIEW.md)](https://api.luri.io/v2/docs/OVERVIEW.md): Arquitetura da API, regras de negócio, convenção de centavos e fluxo de integração.
- [Autenticação e Chaves Públicas JWT RS256 (AUTH.md)](https://api.luri.io/v2/docs/AUTH.md): Basic Auth vs. JWT RS256, geração de par de chaves RSA, claims obrigatórias (`iss`, `exp`) e rotação de chaves (`/v2/auth/public-keys`).
- [Pré-Cadastro de Contas / Leads (PRE_CADASTRO.md)](https://api.luri.io/v2/docs/PRE_CADASTRO.md): Envio de leads PF/PJ (`POST /v2/leads`) e disparo automático de convite via WhatsApp.
- [Gestão de Sellers (SELLERS.md)](https://api.luri.io/v2/docs/SELLERS.md): Consulta e listagem de estabelecimentos vinculados ao marketplace (`/v2/sellers`).
- [Emissão e Gestão de Boletos (BOLETOS.md)](https://api.luri.io/v2/docs/BOLETOS.md): Boleto tradicional e Boleto Híbrido (Boleto + Pix), encargos, descontos, protesto, split e impressão (`/v2/charge`, `/v2/print`).
- [API de Cobranças Pix (PIX.md)](https://api.luri.io/v2/docs/PIX.md): Regras de auto-detecção (`static`, `cob`, `cobv`), encargos avançados (`interest_mode`, `discount[].mode`), conciliação ativa (`/payments`) e exemplos.
- [Contas Digitais — Saldos e Extratos (ACCOUNTS.md)](https://api.luri.io/v2/docs/ACCOUNTS.md): Consulta de saldo e extrato paginado (`/v2/accounts`), exclusivo para autenticação JWT RS256.
- [Webhooks de Cobrança e Eventos em Conta (WEBHOOKS.md)](https://api.luri.io/v2/docs/WEBHOOKS.md): Todos os eventos `boleto.*`, `pix.*`, `account.*` e `public_key.*`, validação HMAC-SHA256 e exemplos de payload.
- [Collection Postman (COLLECTION.md)](https://api.luri.io/v2/docs/COLLECTION.md): Guia de importação e variáveis da Collection Postman oficial da API LURI v2.
- [Changelog da API (changelog.html)](https://api.luri.io/v2/docs/changelog.html): Histórico de versões, melhorias de segurança e novos recursos da API LURI v2.

## Mapa de Endpoints da API LURI v2

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

## Links Institucionais

- [Luri Soluções Financeiras — Site Oficial](https://www.luri.com.vc/): Portal institucional da LURI S/A (Boleto Garantido, Conta Digital PJ e Conta Escrow B2B).
- [Política de Privacidade e LGPD](https://www.luri.com.vc/politica-de-privacidade): Diretrizes de proteção de dados e segurança da informação da LURI S/A.
- [Termos de Uso](https://www.luri.com.vc/termos-de-uso): Condições gerais de uso da plataforma e serviços financeiros LURI.