# LURI v2 API Documentation > Documentação oficial da API LURI v2 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 (AI Coding Rules) 1. **Base URL**: `https://api.luri.io/v2` (ou `{{base_url}}/v2`). Todas as requisições e respostas utilizam `Content-Type: application/json; charset=utf-8`. 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 **inteiros representando 2 casas decimais** (sem ponto ou vírgula). Exemplo: `15000` = R$ 150,00; `200` = 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`). 3. **Escopo de Autenticação (Basic Auth vs. JWT RS256)**: - **Basic Auth (`Authorization: Basic ` — username = token, password em branco)**: Aceito nos recursos de cobrança (`/v2/charge`, `/v2/charge/pix`), `/v2/sellers`, `/v2/webhooks`, `/v2/print` e no cadastro inicial de chave pública (`POST /v2/auth/public-keys`). - **JWT RS256 (`Authorization: Bearer ` assinado com Chave Privada RSA 2048+ bits, claims obrigatórias `iss` = `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`. 4. **Escopo de Webhooks (Cobrança vs. Eventos em Conta)**: - **Eventos de Cobrança (`boleto.created`, `boleto.registered`, `boleto.failed`, `boleto.updated`, `boleto.canceled`, `boleto.paid`, `boleto.assign`, `pix.created`, `pix.paid`)**: Enviados para qualquer marketplace com `url_webhook` configurada (Basic Auth ou JWT). - **Distinção `boleto.paid` vs. `pix.paid` vs. `account.pix.received`**: - Boleto ou Boleto Híbrido pago (via código de barras ou QR Code Pix do boleto) -> `type: "boleto.paid"` (com `payment_method: "boleto"` ou `"pix"`). - Cobrança Pix pura (`POST /v2/charge/pix`) paga -> `type: "pix.paid"`. - Pix avulso recebido diretamente na chave Pix/conta do seller (sem cobrança prévia) -> `type: "account.pix.received"` (exclusivo para marketplaces com credencial JWT ativa). - **Eventos de Movimentação em Conta (`account.*`)**: Enviados **exclusivamente** para marketplaces que possuam `url_webhook` ativa **E** credencial JWT ativa (`/v2/auth/public-keys`). 5. **Verificação de Assinatura de Webhook (HMAC-SHA256)**: - Valide 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)](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. - [Visão Geral e Arquitetura (OVERVIEW.md)](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)](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)](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)](SELLERS.md): Consulta e listagem de estabelecimentos vinculados ao marketplace (`/v2/sellers`). - [Emissão e Gestão de Boletos (BOLETOS.md)](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)](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)](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)](WEBHOOKS.md): Todos os eventos `boleto.*`, `pix.*`, `account.*` e `public_key.*`, validação HMAC-SHA256 e exemplos de payload. - [Collection Postman (COLLECTION.md)](COLLECTION.md): Guia de importação e variáveis da Collection Postman ([LURI v2.postman_collection.json](LURI%20v2.postman_collection.json)). ## Mapa de Endpoints da API LURI v2 | Módulo | Método | Endpoint | Autenticação | Resumo | | :--- | :--- | :--- | :--- | :--- | | **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 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/cancelamento de boleto registrado | | **Boletos** | `GET` | `/v2/charge/{id_boleto}` | Basic Auth / JWT | Consulta detalhes 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/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 c/ 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/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 (padrão: últimos 30 dias) | | **Webhooks** | `POST` | `/v2/webhooks` | Basic Auth / JWT | Cadastra/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` | --- # Referência Detalhada de Módulos e Endpoints ## Módulo: Autenticação # 2 tipos de autenticação Disponibilizamos 2 formas de autenticação na API v2: - Basic Auth - JWT Todos os endpoints aceitam JWT, enquanto alguns endpoints aceitam Basic Auth. Em regra, os endpoints de listagem e de geração de cobrança aceitam Basic Auth, enquanto os endpoints de informação de conta ou cash-out aceitam exclusivamente JWT. Consulte a documentação de cada endpoint para saber qual tipo de autenticação é aceita. ## Autenticação via BASIC AUTH A API suporta autenticação segura através de **BASIC AUTH**. Para autenticar, envie o seu Token de acesso no campo **username** e deixe o campo **password** em branco. Por padrão, o método basic auth utiliza uma string única de **username** e **password**, separada por dois-pontos ( : ). Como o Token gerado pelo sistema LURI não contém senha, utilize este Token diretamente no campo **username** e deixe o campo **password** em branco. Exemplo: {credencial}:{} Em seguida, a string resultante é codificada utilizando **Base64 (RFC 4648)**. ### Exemplo de requisição: ```http POST /v2/endpoint/ HTTP/1.1 Host: api.luri.io Authorization: Basic YWJjMTIzNDU2Nzg5MA== Content-Type: application/json ``` # Autenticação via JWT (JSON Web Token) A API suporta autenticação segura através de JWT assinado assimetricamente utilizando o algoritmo **RS256**. Esta abordagem é ideal para comunicações B2B seguras, dispensando o tráfego contínuo de chaves estáticas ou senhas. ## Como funciona? Em vez de enviar sua credencial base64 diretamente (como no Basic Auth), você usará sua **Chave Privada** (`Private Key`) para assinar um token JWT. A LURI utilizará a sua **Chave Pública** (previamente cadastrada na nossa plataforma, utilizando os endpoints abaixo) para verificar a autenticidade e a integridade matemática daquela requisição, validando você como emissor. ## Estrutura do Token ### 1. Header O cabeçalho deve obrigatoriamente especificar o algoritmo `RS256` para que o cofre virtual da LURI reconheça o pacote. ```json { "alg": "RS256", "typ": "JWT" } ``` ### 2. Payload O corpo do JWT possui os dados abertos do seu sistema. Requer as seguintes *claims*: - `iss` (Issuer): **Obrigatório.** Deve ser exatamente o **hash do seu marketplace** (identificador único) fornecido pelo sistema LURI. É a partir desta chave que o sistema localizará sua chave pública. - `exp` (Expiration Time): **Obrigatório.** O timestamp (Unix Epoch) de quando o token irá expirar. Recomenda-se um tempo de vida muito curto (ex: 5 a 15 minutos) garantindo segurança caso interceptado. - `iat` (Issued At): Opcional, o momento em que foi gerado. - `jti` (JWT ID): Opcional, um ID para ratrear/debugging o uso. *Exemplo de Payload:* ```json { "iss": "hash_exemplo_a1b2c3d4", "iat": 1713361200, "exp": 1713361500 } ``` ### 3. Signature A assinatura do token ocorre juntando o Header e Payload (ambos codificados em Base64Url), e criptografando essa string usando OpenSSL (SHA256) com sua Chave Privada (`PRIVATE KEY` PEM). ## Realizando a Requisição Uma vez gerado o token pelas suas funções backend, inclua-o no cabeçalho HTTP `Authorization` usando o esquema `Bearer`: ```http POST /v2/endpoint/ HTTP/1.1 Host: api.luri.io Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJt... (seu token completo) Content-Type: application/json ``` ### [POST] Cadastrar Chave Pública - **Endpoint**: `POST https://api.luri.io/v2/auth/public-keys` Cadastra uma nova chave pública assimétrica (RSA 2048+ bits) em formato PEM para utilização na assinatura de tokens JWT RS256. - **Canal Seguro Obrigatório:** Conexão HTTPS com TLS 1.2+. - **Autenticação:** Basic Auth utilizando o Token de acesso do marketplace (`secret_marketplace`). - **KID (Key Identifier):** Identificador alfanumérico único para a chave. Se omitido, a LURI gerará um `kid` seguro automaticamente retornado na resposta. - **Bloqueio de Chaves Privadas:** O envio de chaves privadas (`BEGIN PRIVATE KEY`) é sumariamente bloqueado. #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Basic :basic_auth` | Credencial Basic Auth do marketplace (secret_marketplace no username, senha em branco) | | `Content-Type` | `application/json` | - | #### Request Body (`application/json`) ```json { "kid": "prod-key-2026-v1", "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyQKhZOSn8W/7x+is46OV\nJxiX30yXg79OWUicGOZkbC7GXjZ5UEIN8Xqo0GfXsiEOcz5L5RsJ7jGxTU3Niuu0\nVf1QHJek9vY+pGuPRKK4sVEWESK7CmX7n0jGqvXIgLBpSTXfjurkys2pkvaZGPlq\nyxrEbYf4pQApB8+HoxMHVZ2xBd/0Cb3sXQGoSaHL9qhVtRCegNYAk3crNySrBiVb\ncgZz0pImQ+FIgmpn+pG147fFCY7PeeBv1rQ65ibOJ+X1GG7uCBGPNk/tl+0kPt0n\nE21hX4OjxQaYZPNkkahSFLkDXP8wGtQBzsxGyAIowR845Q5QLg6KCyPEh3d0mE9N\nAgMBAAE=\n-----END PUBLIC KEY-----" } ``` #### Respostas de Exemplo ##### HTTP 201 (Created) ```json { "success": true, "message": "Chave pública cadastrada com sucesso.", "data": { "kid": "prod-key-2026-v1", "algorithm": "RS256", "key_type": "RSA", "key_size": 2048, "fingerprint_sha256": "4b68e982d6fc5732c4d622955f269389e1b2123d24268e3b5df51a84f506ee4f", "status": "active", "created_at": "2026-10-23T16:30:00Z" } } ``` ##### HTTP 400 (Bad Request) ```json { "status": "Bad Request", "status_code": 400, "message": "Violação de segurança: Chave privada detectada no payload. Por motivos de segurança, nunca compartilhe ou envie chaves privadas." } ``` ##### HTTP 409 (Conflict) ```json { "status": "Conflict", "status_code": 409, "message": "Já existe uma chave pública ativa cadastrada com o identificador (kid) 'prod-key-2026-v1'." } ``` --- ### [GET] Listar Chaves Públicas - **Endpoint**: `GET https://api.luri.io/v2/auth/public-keys` Retorna a relação de todas as chaves públicas (ativas, revogadas e chaves legadas) vinculadas ao marketplace emissor do token JWT. - **Autenticação:** Obrigatoriamente JWT (`Authorization: Bearer `). Requisições com Basic Auth são rejeitadas com `HTTP 401 Unauthorized`. - **Legado Ativo:** Caso o marketplace possua chave configurada na coluna legada `api_boleto_marketplace.public_key`, ela é listada com status `active` e identificador `legacy-default`. #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Bearer :jwt_token` | Token JWT assinado com algoritmo RS256 (Obrigatório) | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "success": true, "data": [ { "kid": "prod-key-2026-v2", "algorithm": "RS256", "key_type": "RSA", "key_size": 2048, "fingerprint_sha256": "4b68e982d6fc5732c4d622955f269389e1b2123d24268e3b5df51a84f506ee4f", "is_legacy": false, "status": "active", "created_at": "2026-10-23T16:30:00Z", "revoked_at": null, "last_used_at": "2026-10-23T16:35:10Z" }, { "kid": "prod-key-2026-v1", "algorithm": "RS256", "key_type": "RSA", "key_size": 2048, "fingerprint_sha256": "8a7c293817498127394872938471923847192837491827394817293847192837", "is_legacy": false, "status": "revoked", "created_at": "2026-09-01T10:00:00Z", "revoked_at": "2026-10-23T16:20:00Z", "last_used_at": "2026-10-23T16:19:40Z" }, { "kid": "legacy-default", "algorithm": "RS256", "key_type": "RSA", "key_size": 2048, "fingerprint_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "is_legacy": true, "status": "active", "created_at": null, "revoked_at": null, "last_used_at": null } ] } ``` ##### HTTP 401 (Unauthorized) ```json { "status": "Unauthorized", "status_code": 401, "message": "Acesso negado: A listagem de chaves públicas exige obrigatoriamente autenticação via JWT (Bearer Token)." } ``` --- ### [DELETE] Revogar Chave Pública - **Endpoint**: `DELETE https://api.luri.io/v2/auth/public-keys/:kid` Invalida logicamente uma chave pública, bloqueando instantaneamente qualquer autenticação futura assinada por ela. - **Autenticação:** Obrigatoriamente JWT (`Authorization: Bearer `). - **Regra de Segurança Crítica (Anti-Lockout):** O token JWT que autoriza a requisição de revogação **NÃO** pode ter sido assinado com a mesma chave (`kid`) que está sendo revogada. Caso tente auto-revogação, a requisição é bloqueada com `HTTP 403 Forbidden`. - **Fluxo de Rotação sem Downtime:** Cadastre a chave nova primeiro (`POST`), passe a assinar suas requisições com ela, e em seguida revogue a antiga (`DELETE`). #### Path Variables | Parâmetro | Exemplo | Descrição | | :--- | :--- | :--- | | `kid` | `prod-key-2026-v1` | Identificador único (kid) da chave pública a ser revogada | #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Bearer :jwt_token` | Token JWT assinado com uma chave ATIVA DIFERENTE da que está sendo revogada | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "success": true, "message": "Chave pública revogada com sucesso. Tokens futuros assinados com este kid serão rejeitados.", "data": { "kid": "prod-key-2026-v1", "status": "revoked", "revoked_at": "2026-10-23T16:40:00Z" } } ``` ##### HTTP 403 (Forbidden) ```json { "status": "Forbidden", "status_code": 403, "message": "Operação não permitida: Não é permitido revogar a mesma chave pública ('prod-key-2026-v1') utilizada para assinar o token desta requisição. Realize a rotação utilizando outra chave ativa." } ``` ##### HTTP 404 (Not Found) ```json { "status": "Not Found", "status_code": 404, "message": "Chave pública com o identificador (kid) 'chave-inexistente' não foi encontrada para este marketplace." } ``` --- ## Módulo: Pre Cadastro Envio de leads para abertura de conta correntista na LURI. O objetivo é permitir que a equipe da LURI receba e trate os leads. - **Campo `source`:** Deve ser previamente combinado com a equipe comercial da LURI para identificar o parceiro e o acordo comercial prévio. - **WhatsApp Automático:** Ao enviar o lead, o contato receberá uma mensagem automática via WhatsApp iniciando o tratamento de dados. - **Estrutura:** Suporta a nova estrutura categorizada (`lead`, `contact`, `source`) com validação de CPF/CNPJ e mantém total retrocompatibilidade com o formato legado (`ein`). ### [POST] Enviar Lead - **Endpoint**: `POST https://api.luri.io/v2/lead/` #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Content-Type` | `application/json` | - | #### Request Body (`application/json`) ```json { "lead": { "document": "12345678000195", "name": "Empresa Exemplo LTDA", "segment": "servico" }, "contact": { "document": "39053344705", "name": "Maria da Silva", "cell_phone": "11912345678", "email": "maria@empresa.com.br" }, "source": "GHP" } ``` #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "status": "success", "message": "Lead data received and processed successfully.", "data": { "lead": { "document": "12345678000195", "name": "Empresa Exemplo LTDA", "segment": "servico" }, "contact": { "document": "39053344705", "name": "Maria da Silva", "cell_phone": "11912345678", "email": "maria@empresa.com.br" }, "source": "GHP" } } ``` ##### HTTP 200 (OK) ```json { "status": "success", "message": "Lead data received and processed successfully.", "data": { "ein": "12345678000195", "contact_name": "Maria da Silva", "cell_phone": "11912345678", "email": "maria@empresa.com.br", "source": "ghp_wedrop" } } ``` ##### HTTP 400 (Bad Request) ```json { "error": { "status": "Bad Request", "status_code": 400, "message": [ "The \"lead.document\" field is invalid. Must be a valid CPF (11 digits) or CNPJ (14 digits).", "The \"lead.name\" field is required.", "The \"contact.name\" field is required.", "The \"contact.cell_phone\" field is required.", "The \"source\" field is required." ] } } ``` --- ## Módulo: Sellers Caso a credencial seja do tipo marketplace, disponibilizamos com uma única credencial a consulta dos dados dos sellers que estão no mesmo workspace. Isso facilita a integração de estabelecimentos que estão vinculados a um mesmo grupo econômico. ### [GET] Listar Sellers - **Endpoint**: `GET https://api.luri.io/v2/sellers` #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `limit` | Opcional | `100` | Escolha a limitação de registros por página. Padrão 300 registros. | | `page` | Opcional | `9` | Caso a lista apresente mais de uma página, escolha para paginação. | | `orderby` | Opcional | `name` | Informe o nome do campo pelo qual deseja ordenar. created_at, name, taxpayer_id | | `orderdirection` | Opcional | `ASC` | Informe a direção da ordenação. ASC ou DESC | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": [ { "id": "9519f68914bb40359a045ec8a142b75f", "status": "active", "created_at": null, "type": "business", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank_details": { "bank": "274", "branch": "0001", "account": "2426583", "type": 3, "model": null, "agreement": null, "pix_enabled": null }, "address": { "line1": null, "line2": null, "neighborhood": null, "city": null, "state": null, "postal_code": null } } ], "has_more": false, "total_pages": 1, "page": 1, "total": 1, "query_count": 1 } ``` ##### HTTP 400 (Bad Request) ```json { "error": { "status": "Bad Request", "status_code": 400, "message": "Page 2 does not exist. Total pages: 1" } } ``` ##### HTTP 401 (Unauthorized) ```json { "error": { "status": "Unauthorized", "status_code": 401, "message": "No authentication parameters provided." } } ``` ##### HTTP 405 (Method Not Allowed) ```json { "error": { "status": "Method Not Allowed", "status_code": 405, "message": "Request method not allowed." } } ``` --- ### [GET] Buscar Seller - **Endpoint**: `GET https://api.luri.io/v2/sellers/:identificador` #### Path Variables | Parâmetro | Exemplo | Descrição | | :--- | :--- | :--- | | `identificador` | `` | - UUID que identifica o estabelecimento comercial e sua conta. - Ou o CNPJ do estabelecimento - Ou o numero do banco + agencia + conta concatenados. ex: 27400012277881 | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": [ { "id": "9519f68914bb40359a045ec8a142b75f", "status": "active", "created_at": null, "type": "business", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank_details": { "bank": "274", "branch": "0001", "account": "2426583", "type": 3, "model": null, "agreement": null, "pix_enabled": null }, "address": { "line1": null, "line2": null, "neighborhood": null, "city": null, "state": null, "postal_code": null } } ], "has_more": false, "total_pages": 1, "page": 1, "total": 1, "query_count": 1 } ``` ##### HTTP 404 (Not Found) ```json { "error": { "status": "Not Found", "status_code": 404, "message": "No sellers found matching the criteria." } } ``` --- ## Módulo: Boletos O conjunto de endpoints de **Charge** gerencia o ciclo de vida das cobranças por boleto, permitindo criar, consultar, atualizar, cancelar (dar baixa) e imprimir. Na LURI, o objeto `charge` representa a cobrança gerada. Dependendo da configuração da carteira do _seller_, ao acionar o método de criação, a cobrança pode assumir os seguintes formatos: - **Boleto Tradicional:** Cobrança padrão via código de barras e linha digitável. - **Boleto Híbrido (Boleto + Pix):** Um único documento contendo tanto o código de barras quanto o QR Code Pix. **Comportamento do Boleto Híbrido:** Esta funcionalidade unifica duas opções de pagamento em uma única cobrança. Independentemente de o cliente pagar via Pix ou código de barras, o sistema registra a liquidação e dá baixa na cobrança automaticamente, invalidando o método que não foi utilizado. _Para habilitar o Boleto Híbrido na carteira do seller, faça o pedido para o suporte._ > **Convenção de Valores ("Centavos"):** Todos os valores monetários e percentuais da API (como `amount`, `late_fee_amount`, `late_fee_percentage`, `interest_amount`, `interest_percentage`, `abatement_amount` e `discount[].amount`) devem ser informados como **números inteiros representando duas casas decimais** (sem ponto ou vírgula). Exemplo: `15000` = R$ 150,00; `200` = R$ 2,00 (fixo) ou 2,00% (percentual); `100` = R$ 1,00 (fixo) ou 1,00% (percentual). > *Nota de Compatibilidade:* Parâmetros do formato legado (como `discount_percentage` e `discount_limit_date` diretamente em `billing_instructions`) continuam funcionando normalmente.
CampoTipoObrigatórioDescrição
sellerstringSimID da loja/conta recebedora (seller_id).
amountintegerSimValor nominal do boleto em centavos (mínimo 100 = R$ 1,00). Ex.: R$ 150,00 = 15000.
reference_idstringNãoCódigo de conciliação do seu sistema para identificar a cobrança.
installmentobjectNãoIdentificação da parcela e quantidade total de parcelas da venda associada àquele boleto.
numberintegerCondicionalNúmero da parcela atual (inteiro positivo >= 1 e <= total; obrigatório se installment for enviado).
totalintegerCondicionalQuantidade total de parcelas da venda (inteiro positivo >= 1; obrigatório se installment for enviado).
tagsarrayNãoEtiquetas livres para identificar o boleto (pedido, parcela etc.). Ex.: ["Parcela 1/12", "Pedido #1234"].
customerobjectSimDados do pagador (sacado).
taxpayer_idstringSimCPF ou CNPJ do pagador (somente números).
namestringSimNome ou Razão Social do pagador.
emailstringNãoE-mail do pagador.
phone_numberstringSimTelefone com DDD (somente números). Formato: 11912345678.
street_linestringSimLogradouro do pagador (rua e número).
street_line2stringNãoComplemento do endereço.
neighborhoodstringNãoBairro.
citystringSimCidade.
statestringSimEstado (UF com 2 letras, ex.: SP).
postal_codestringSimCEP (somente números). Formato: 01310100.
payment_methodobjectSimInformações e regras de pagamento do boleto.
expiration_datestringSimData de vencimento no formato AAAA-MM-DD.
payment_limit_datestringNãoData limite para pagamento no formato AAAA-MM-DD (deve ser maior que expiration_date). Caso omitida, assume automaticamente +90 dias após o vencimento.
document_speciesintegerNãoCódigo FEBRABAN da espécie do título (padrão 2 = Duplicata Mercantil; 4 = Duplicata de Serviço).
document_numberstringNãoNúmero do documento/título (máx. 15 caracteres). Caso omitido, utiliza reference_id.
receiverobjectNãoDados do Sacador Avalista do boleto.
taxpayer_idstringCondicionalCPF ou CNPJ do sacador avalista (obrigatório se receiver for enviado).
namestringCondicionalNome ou Razão Social do sacador avalista (obrigatório se receiver for enviado).
billing_instructionsobjectNãoInstruções financeiras de cobrança (multa, juros, abatimento e descontos) — todos os valores representados em "centavos" (inteiro com 2 casas decimais).
late_fee_amountintegerNãoValor fixo da multa em centavos. Ex.: 200 = R$ 2,00. (Mutuamente exclusivo com late_fee_percentage).
late_fee_percentageintegerNãoPercentual da multa em base centesimal. Ex.: 200 = 2,00%. Máx.: 10000 (100,00%).
late_fee_datestringNãoData de início da multa (AAAA-MM-DD, posterior ao vencimento). Padrão: expiration_date + 1 dia.
interest_amountintegerNãoValor fixo de juros ao dia (dias corridos) em centavos. Ex.: 100 = R$ 1,00/dia. (Mutuamente exclusivo com interest_percentage).
interest_percentageintegerNãoPercentual de juros ao mês (dias corridos) em base centesimal. Ex.: 100 = 1,00%/mês.
interest_datestringNãoData de início dos juros (AAAA-MM-DD, posterior ao vencimento). Padrão: expiration_date + 1 dia.
abatement_amountintegerNãoValor de abatimento concedido no título em centavos. Ex.: 500 = R$ 5,00.
discountarrayNãoLista de até 3 faixas de desconto para pagamento antecipado. Cada item do array contém:
  • limit_date (string, obrigatório): Data limite do desconto (AAAA-MM-DD, menor ou igual a expiration_date).
  • mode (string, obrigatório): "fixed" (valor fixo) ou "percentage" (percentual).
  • amount (integer, obrigatório): Valor em centavos/base centesimal (ex.: 1000 = R$ 10,00 ou 10,00%).
body_instructionsobjectNãoInstruções impressas no corpo do boleto.
line1stringNãoTexto impresso na primeira linha (limite de 80 caracteres).
line2stringNãoTexto impresso na segunda linha (limite de 80 caracteres).
line3stringNãoTexto impresso na terceira linha (limite de 80 caracteres).
### [POST] Criar Boleto - **Endpoint**: `POST https://api.luri.io/v2/charge/` #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `IdempotencyKey` | `5cbcd00577a64d94b2ab2d18bb71df48` | - | #### Request Body (`application/json`) ```json { "seller": "9519f68914bb40359a045ec8a142b75f", "amount": 10000, "reference_id": "00001234", "installment": { "number": 1, "total": 12 }, "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-23", "payment_limit_date": "2026-05-24", "document_species": 2, "document_number": "00001234", "receiver": { "taxpayer_id": "12345678000195", "name": "Empresa Sacador Avalista LTDA" }, "billing_instructions": { "late_fee_percentage": 200, "interest_percentage": 100, "abatement_amount": 0, "discount": [ { "limit_date": "2026-02-23", "mode": "percentage", "amount": 1000 } ] } }, "body_instructions": { "line1": "LINHA 1", "line2": "LINHA 2", "line3": "LINHA 3" } } ``` #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "boleto_id": "2bc04ac09734440f9d77cfde45f280c1", "seller": "9519f68914bb40359a045ec8a142b75f", "amount": 10000, "reference_id": "00001234", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03", "payment_limit_date": "2026-03-04", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" } }, "body_instructions": { "line1": "LINHA 1", "line2": "LINHA 2", "line3": "LINHA 3" }, "linha_cod_barras": "27492137400000100000001010000000017002426580", "linha_digitavel": "27490001011000000001770024265806213740000010000" } ``` --- ### [GET] Listar Boleto - **Endpoint**: `GET https://api.luri.io/v2/charge/` #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `limit` | Opcional | `100` | - | | `page` | Opcional | `37` | - | | `seller_id` | Opcional | `9519f68914bb40359a045ec8a142b75f` | ID único que identifica o estabelecimento comercial e sua conta. Caso o estabelecimento tenha mais de uma conta, terá seller ids diferentes | | `seller_ein` | Opcional | `02647408000185` | Documento do (CNPJ) do seller | | `reference_id` | Opcional | `00001234` | Número de identificação do sistema cliente | | `status` | Opcional | `created` | Status dos boletos | | `created_date_lte` | Opcional | `2026-03-04` | Data de criação do boleto, formato “YYYY-MM-DD” menor igual a este valor | | `created_date_gte` | Opcional | `2026-03-03` | Data de criação do boleto, formato “YYYY-MM-DD” maior igual a este valor | | `updated_date_lte` | Opcional | `2026-03-04` | Data de atualização do boleto, formato “YYYY-MM-DD” menor igual a este valo | | `updated_date_gte` | Opcional | `2026-03-03` | Data de atualização do boleto, formato “YYYY-MM-DD” maior igual a este valor | | `payment_date_lte` | Opcional | `2026-03-04` | Data de pagamento do boleto, formato “YYYY-MM-DD” menor igual a este valor | | `payment_date_gte` | Opcional | `2026-03-03` | Data de pagamento do boleto, formato “YYYY-MM-DD” maior igual a este valor | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": [ { "boleto_id": "421886ac03a3405183ee5750e0b0171e", "nosso_numero": "01000000001701", "status": "registered", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-03-03T13:26:57+00:00", "updated_at": "2026-03-03T13:27:05+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03 00:00:00", "payment_limit_date": "2026-03-04 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "f742c5d05e334f08bf6263593db88a3b", "nosso_numero": "01000000001698", "status": "registered", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-03-03T12:54:15+00:00", "updated_at": "2026-03-03T12:54:23+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03 00:00:00", "payment_limit_date": "2026-03-04 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "5cbcd00577a64d94b2ab2d18bb71df48", "nosso_numero": "0100000000168P", "status": "registered", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-03-03T11:40:23+00:00", "updated_at": "2026-03-03T11:40:42+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03 00:00:00", "payment_limit_date": "2026-03-04 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "b7d600f7cbe14d1f8dcd27ff3ea4bbf4", "nosso_numero": "01000000001671", "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-03-03T11:37:49+00:00", "updated_at": "2026-03-03T11:39:16+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03 00:00:00", "payment_limit_date": "2026-03-04 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "7270d22fcf3f42a69a691bf416ca09fe", "nosso_numero": "01000000001671", "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-03-03T11:37:01+00:00", "updated_at": "2026-03-03T11:37:04+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03 00:00:00", "payment_limit_date": "2026-03-04 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "64cbbe022bee4156a6e0e5ee0c7229a1", "nosso_numero": "01000000001671", "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-03-03T11:00:43+00:00", "updated_at": "2026-03-03T11:09:52+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03 00:00:00", "payment_limit_date": "2026-03-04 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "9594ceb5b3d2440782ee8a30e25950a0", "nosso_numero": "01000000001671", "status": "registered", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-03-03T10:43:00+00:00", "updated_at": "2026-03-03T10:43:10+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03 00:00:00", "payment_limit_date": "2026-03-04 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "7e1ee5d904ed4854aeead217b3f473fb", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-23T18:48:20+00:00", "updated_at": "2026-02-23T18:48:20+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-23 00:00:00", "payment_limit_date": "2026-03-23 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-23" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "4723363f443f4bff99e3d12d6c62b6de", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-23T18:44:34+00:00", "updated_at": "2026-02-23T18:44:34+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-23 00:00:00", "payment_limit_date": "2026-03-23 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-23" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "2c686c28cebb4a3696a5531948cd3a52", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:58:17+00:00", "updated_at": "2026-02-20T19:58:17+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "eab449ae19b64562b7edf2d6c791bc25", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:57:30+00:00", "updated_at": "2026-02-20T19:57:30+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "590f3b26d8a24eec9fe5b2b9441fc076", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:56:57+00:00", "updated_at": "2026-02-20T19:56:57+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "11c3ee6a1eaf46c3bd60116cafef9b53", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:55:47+00:00", "updated_at": "2026-02-20T19:55:47+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "e692fa6245db4cf2a5f0bec5684bea38", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:55:43+00:00", "updated_at": "2026-02-20T19:55:43+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "26d97b44f9d74efcb38a73a407e328d1", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:55:35+00:00", "updated_at": "2026-02-20T19:55:35+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "c5ff1f5a62f34e16b9920e8bc4599680", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:43:45+00:00", "updated_at": "2026-02-20T19:43:45+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "3c2292f4a2994fc0b5c0c18f769ea311", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:24:48+00:00", "updated_at": "2026-02-20T19:24:48+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "a54769b0fa8c4c94b38b22d54986bb90", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T19:22:06+00:00", "updated_at": "2026-02-20T19:22:06+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "045097a912bf4f4eaa67234944960f02", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T11:13:16+00:00", "updated_at": "2026-02-20T11:13:16+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "85eece382357414295d3bb2ed1110fe1", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T11:12:32+00:00", "updated_at": "2026-02-20T11:12:32+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "d751b45be9724d479c50d24c067911f8", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T11:10:16+00:00", "updated_at": "2026-02-20T11:10:16+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "cb889256f87e439a973e441a8e0250e7", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T11:04:52+00:00", "updated_at": "2026-02-20T11:04:52+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "142ca16d0543438db28d70d31fdafd47", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T11:01:28+00:00", "updated_at": "2026-02-20T11:01:28+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "4a74cc5e84af41f6b5857cb4fbe7942a", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T11:00:46+00:00", "updated_at": "2026-02-20T11:00:46+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "6dec5225e8f44250a6dab864081af570", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T10:44:32+00:00", "updated_at": "2026-02-20T10:44:32+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "bc3c96ea6d454171a58707ede2968f33", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T10:42:22+00:00", "updated_at": "2026-02-20T10:42:22+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "ecedca72d98049728ad06845cfcaccf5", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T10:41:02+00:00", "updated_at": "2026-02-20T10:41:02+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "a97dd62789d54b539ce428fb4337897d", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-20T10:27:04+00:00", "updated_at": "2026-02-20T10:27:04+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-20 00:00:00", "payment_limit_date": "2026-03-20 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-20" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "0b2753eb87e3436f8ed4101fbc08db77", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-19T13:09:07+00:00", "updated_at": "2026-02-19T13:09:07+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-19 00:00:00", "payment_limit_date": "2026-03-19 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-19" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "ec55e930812d47b8a52fcc6db8bc796f", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-19T13:08:40+00:00", "updated_at": "2026-02-19T13:08:40+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-19 00:00:00", "payment_limit_date": "2026-03-19 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-19" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "80699d196f944da586be092d46a1521b", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-19T13:04:18+00:00", "updated_at": "2026-02-19T13:04:18+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-19 00:00:00", "payment_limit_date": "2026-03-19 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-19" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "c3219fe123a44c40805798b155ce696c", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-19T13:03:51+00:00", "updated_at": "2026-02-19T13:03:51+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "91994994010", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-19 00:00:00", "payment_limit_date": "2026-03-19 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-19" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "ff72e575704441b3abd3c6f218904789", "nosso_numero": null, "status": "requested", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-19T12:53:34+00:00", "updated_at": "2026-02-19T12:53:34+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "91994994010", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-19 00:00:00", "payment_limit_date": "2026-03-19 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-19" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "c27895e29ebe4092b03590c1ee2bb2e3", "nosso_numero": null, "status": "created", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-18T19:35:15+00:00", "updated_at": "2026-02-18T19:35:15+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "91994994010", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-18 00:00:00", "payment_limit_date": "2026-03-18 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-18" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "8361166b29874ca6803afdb62c5ed7ae", "nosso_numero": null, "status": "created", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-02-18T19:28:11+00:00", "updated_at": "2026-02-18T19:28:11+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "91994994010", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-02-18 00:00:00", "payment_limit_date": "2026-03-18 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-02-18" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "e30da7d06852f5d745d89aafdd0a40df", "nosso_numero": "000000000017", "status": "created", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 292545, "reference_id": "2851", "created_at": "2025-05-16T16:20:43+00:00", "updated_at": "2025-05-16T16:20:43+00:00", "tags": [ null ], "customer": { "taxpayer_id": "51303323000195", "name": "VALLE MADEIRAS LTDA", "email": "VALLEMADEIRAS@OUTLOOK.COM", "phone_number": "", "street_line1": "PREFEITO FRANCISCO RIBEIRO NOGUEIRA", "street_line2": "LJ 02", "neighborhood": "MOGI MODERNO", "city": "MOGI DAS CRUZES", "state": "SP", "postal_code": "08717490" }, "payment_method": { "expiration_date": "2025-05-15 00:00:00", "payment_limit_date": "2025-06-14 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "0", "discount_limit_date": null }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } }, { "boleto_id": "96e593d8eb999e0413baef556407af5a", "nosso_numero": "000000000000", "status": "created", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 191794, "reference_id": "2858", "created_at": "2025-05-16T16:20:22+00:00", "updated_at": "2025-05-16T16:20:22+00:00", "tags": [ null ], "customer": { "taxpayer_id": "34363405000106", "name": "ALUMIWORLD GLASS EIRELI", "email": "financeiro@alumiworld.com.br", "phone_number": "1143804207", "street_line1": "R BIRIGUI 960", "street_line2": "", "neighborhood": "VILA JAU", "city": "POA", "state": "SP", "postal_code": "08559010" }, "payment_method": { "expiration_date": "2025-05-15 00:00:00", "payment_limit_date": "2025-06-14 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "0", "discount_limit_date": null }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": null, "line2": null, "line3": null } } ], "has_more": false, "total_pages": 1, "page": 1, "total": 37, "query_count": 37 } ``` ##### HTTP 400 (Bad Request) ```json { "status": "Bad Request", "status_code": 400, "message": "Please provide at least one parameter." } ``` --- ### [GET] Buscar Boleto - **Endpoint**: `GET https://api.luri.io/v2/charge/:id` Permite consultar os detalhes de uma cobrança específica. ### Formas de Consulta Suportadas 1. **Por ID local (`boleto_id`):** Passe o UUID da cobrança no path `:id` (ex: `GET /v2/charge/ddd5c8bf766b4a78844bd53c55f39887`). 2. **Por Nosso Número / Reference ID:** Passe o nosso número ou seu ID de referência no path `:id`. 3. **Por Código de Barras + Seller (`seller_id` + `linha_cod_barras`):** - Informe o código de barras de 44 dígitos no parâmetro `:id` ou na querystring `linha_cod_barras` junto com o `seller_id`. - Caso o boleto não esteja cadastrado na base local, a API realiza automaticamente o **fallback bancário** consultando o registro diretamente no banco emissor (BMP). ### Parâmetros | Parâmetro | Local | Tipo | Descrição | | :--- | :--- | :--- | :--- | | `:id` | Path | `string` | `boleto_id`, `nosso_numero`, `reference_id` ou código de barras (44 dígitos) | | `seller_id` | Query | `string` | Hash do seller (obrigatório em consultas por código de barras no banco emissor) | | `linha_cod_barras` | Query | `string` | Código de barras de 44 dígitos numéricos | #### Path Variables | Parâmetro | Exemplo | Descrição | | :--- | :--- | :--- | | `id` | `` | boleto_id, nosso_numero, reference_id ou código de barras de 44 dígitos | #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `seller_id` | Sim/Ativo | `{{seller_id}}` | Hash do seller (Obrigatório em consultas por código de barras no banco emissor) | | `linha_cod_barras` | Opcional | `` | Código de barras numérico de 44 dígitos | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": [ { "boleto_id": "421886ac03a3405183ee5750e0b0171e", "nosso_numero": "01000000001701", "status": "registered", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "02647408000185", "name": "Federal Invest SA", "statement_descriptor": "FEDERAL INVEST", "bank": "BMP Money Plus", "branch_number": "0001", "account_number": "2426583" }, "amount": 10000, "reference_id": "00001234", "created_at": "2026-03-03T13:26:57+00:00", "updated_at": "2026-03-03T13:27:05+00:00", "tags": [ "Parcela 1/12", "Pedido #1234" ], "customer": { "taxpayer_id": "36160560042", "name": "George Costanza", "email": "george@costanza.com", "phone_number": "11999000707", "street_line1": "Rua Seinfeld, 180", "street_line2": "ap 129", "neighborhood": "West Side", "city": "São Paulo", "state": "SP", "postal_code": "11707000" }, "payment_method": { "expiration_date": "2026-03-03 00:00:00", "payment_limit_date": "2026-03-04 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "1000", "discount_limit_date": "2026-03-03" }, "emv": null, "qrcode": null }, "payment_date": null, "body_instructions": { "line1": "LINHA 1", "line2": "LINHA 2", "line3": "LINHA 3" } } ], "has_more": false, "total_pages": 1, "page": 1, "total": 1, "query_count": 1 } ``` --- ### [GET] Consultar Todos os Boletos (BaaS/BMP) - **Endpoint**: `GET https://api.luri.io/v2/charge/all?seller_id=:seller_id&page=1&limit=10` Endpoint para consulta geral de todos os boletos e cobranças emitidos diretamente na conta bancária (BaaS / BMP), inclusive boletos gerados por outros canais. ### Parâmetros Obrigatórios - `seller_id`: Identificador (hash) do estabelecimento vendedor / cedente. ### Parâmetros de Filtro e Paginação | Parâmetro | Tipo | Descrição | | :--- | :--- | :--- | | `seller_id` | `string` | **Obrigatório.** Identificador (hash) do seller | | `page` | `integer` | Número da página (padrão: `1`) | | `limit` | `integer` | Quantidade por página (máx: `300`) | | `created_date_gte` | `string` | Data inicial de emissão (`YYYY-MM-DD`) | | `created_date_lte` | `string` | Data final de emissão (`YYYY-MM-DD`) | | `expiration_date_gte` | `string` | Data inicial de vencimento (`YYYY-MM-DD`) | | `expiration_date_lte` | `string` | Data final de vencimento (`YYYY-MM-DD`) | | `status` | `string` | Status (`registered`, `paid`, `canceled`, `requested`, `error`, `protested`) | #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `seller_id` | Sim/Ativo | `{{seller_id}}` | Hash do seller (Obrigatório) | | `page` | Sim/Ativo | `1` | Número da página (padrão: 1) | | `limit` | Sim/Ativo | `10` | Quantidade de registros por página (máx: 300) | | `created_date_gte` | Opcional | `2026-09-01` | Data inicial de criação (YYYY-MM-DD) | | `created_date_lte` | Opcional | `2026-09-30` | Data final de criação (YYYY-MM-DD) | | `expiration_date_gte` | Opcional | `2026-09-01` | Data inicial de vencimento (YYYY-MM-DD) | | `expiration_date_lte` | Opcional | `2026-09-30` | Data final de vencimento (YYYY-MM-DD) | | `status` | Opcional | `registered` | Status do boleto (registered, paid, canceled, error, protested) | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": [ { "boleto_id": "ddd5c8bf766b4a78844bd53c55f39887", "nosso_numero": "01000000000349", "status": "registered", "seller": { "seller_id": "bd4c154beca34f148fd0161a0bc34c9d", "taxpayer_id": "31928597000162", "name": "ELIAS SPOMBERG", "statement_descriptor": "ELIAS SPOMBERG", "bank": "BMP Money Plus", "bank_code": "274", "branch_number": "0001", "account_number": "9911744" }, "amount": 10100, "reference_id": "0004127708", "created_at": "2026-09-17T11:27:28-03:00", "updated_at": "2026-09-17T14:27:30+00:00", "tags": [ "2/2" ], "customer": { "taxpayer_id": "05705033613", "name": "ADRISSA DOMINITINI PARANAIBA", "email": "R41@GMAIL.COM", "phone_number": "31984692532", "street_line1": "R CARANGOLA SILVA BARBOSA, 145", "street_line2": "", "neighborhood": "SANTO ANTONIO", "city": "BELO HORIZONTE", "state": "MG", "postal_code": "30330240" }, "payment_method": { "expiration_date": "2026-11-17 00:00:00", "payment_limit_date": "2026-12-17 00:00:00", "billing_instructions": { "late_fee_amount": "200", "interest_amount": "100", "discount_percentage": "0", "discount_limit_date": null }, "emv": "000201010212...", "qrcode": "iVBORw0KGgoAAAANSUhEUgAA..." }, "payment_date": null, "body_instructions": { "line1": " ", "line2": " ", "line3": " " } } ], "has_more": false, "total_pages": 1, "page": 1, "total": 1, "query_count": 1 } ``` --- ### [POST] Baixar Boleto - **Endpoint**: `POST https://api.luri.io/v2/charge/:boleto_id/cancel` #### Path Variables | Parâmetro | Exemplo | Descrição | | :--- | :--- | :--- | | `boleto_id` | `` | - | #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `IdempotencyKey` | `5cbcd00577a64d94b2ab2d18bb71df48` | - | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "boleto_id": "5cbcd00577a64d94b2ab2d18bb71df48", "status": "canceled" } ``` --- ### [GET] Imprimir Boleto - **Endpoint**: `GET https://api.luri.io/v2/print/:layout/:formato/:seller/:boleto` Endpoint de impressão visual e download de boletos nos formatos HTML, PDF ou Base64. ### Parâmetros de Path | Parâmetro | Tipo | Obrigatório | Descrição | | :--- | :--- | :--- | :--- | | `layout` | `string` | **Sim** | Layout do boleto (`boleto`, `double` ou `triple`) | | `formato` | `string` | **Sim** | Formato de saída (`html`, `pdf` ou `base64`) | | `seller` | `string` | **Sim** | Identificador do lojista (`seller_id` ou CNPJ) | | `boleto` | `string` | **Sim** | Identificador do boleto (`boleto_id` ou `reference_id`) | #### Path Variables | Parâmetro | Exemplo | Descrição | | :--- | :--- | :--- | | `layout` | `boleto` | layout do boleto que deseja imprimir, as opções são “boleto”, “double” ou “triple” | | `formato` | `html` | O formato do arquivo que deseja gerar. As opções são “html”, “pdf”, ou “base64” | | `seller` | `9519f68914bb40359a045ec8a142b75f` | Identificador do lojista. Pode ser o seller_id ou cnpj do lojista | | `boleto` | `2bc04ac09734440f9d77cfde45f280c1` | Identificador do boleto. Pode ser o boleto_id ou o reference_id. Quando usado o reference_id são impressos todos os boletos vinculados à aquela venda. | --- ### [PATCH] Atualizar Boleto - **Endpoint**: `PATCH https://api.luri.io/v2/charge/c6825525-5665-4ba2-a0e1-03a8f1a81bd4` Atualiza dados de um boleto registrado (valor nominal, data de vencimento, data limite de pagamento, instruções de multa/juros/desconto/abatimento ou sacador avalista `receiver`). Exige o envio do cabeçalho `IdempotencyKey`. #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `IdempotencyKey` | `9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c` | - | | `Content-Type` | `application/json` | - | #### Request Body (`application/json`) ```json { "amount": 12000, "payment_method": { "expiration_date": "2026-03-15", "payment_limit_date": "2026-06-13", "billing_instructions": { "late_fee_percentage": 200, "interest_percentage": 100, "abatement_amount": 500, "discount": [ { "limit_date": "2026-03-10", "mode": "percentage", "amount": 500 } ] } } } ``` #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "boleto_id": "c6825525-5665-4ba2-a0e1-03a8f1a81bd4", "status": "updating", "message": "Update request accepted and sent to the bank.", "nosso_numero": "0000185741008", "amount": 12000, "customer": { "name": "George Costanza", "taxpayer_id": "36160560042" }, "payment_method": { "expiration_date": "2026-03-15", "payment_limit_date": "2026-06-13" }, "linha_cod_barras": "27494192800000120004338110000185741000000000", "linha_digitavel": "27494.33819 10000.185742 10000.000005 4 19280000012000", "updated_at": "2026-03-03T14:10:00-03:00" } ``` --- ## Módulo: Pix A rota de `charge/pix` permite a criação, consulta, conciliação e listagem de cobranças **Pix** de forma simples e unificada. - **Auto-Detecção de Modalidade:** O endpoint `POST /v2/charge/pix` identifica automaticamente se o Pix é **Estático (`static`)**, **Dinâmico (`cob`)** ou **Cobrança com Vencimento (`cobv`)** com base nos campos do payload. - **Convenção Unificada de Valores ("Centavos"):** Todos os valores monetários e percentuais (`amount`, `late_fee_amount`, `late_fee_percentage`, `interest_amount`, `interest_percentage`, `abatement_amount`, `discount[].amount`) utilizam números inteiros representando duas casas decimais. - **Opções Avançadas de Encargos no `cobv`:** Suporta todas as modalidades de juros (`interest_mode`: valor por dia corrido/útil, percentual diário/mensal em dias corridos ou úteis, ou isento) e descontos (`discount[].mode`: fixo ou percentual até a data, ou por dia corrido/útil de antecipação). - **Provisionamento Automático de Chave:** Caso o estabelecimento vendedor não possua uma chave Pix ativa cadastrada, a API consulta/cria a chave Pix e realiza o cache de forma transparente. - **Consultas, Detalhes de Pagamento e Conciliação Ativa:** Suporta consulta individual por ID/txid (`GET /v2/charge/pix/{id}`), consulta de detalhes de pagamentos/devoluções no liquidante com conciliação ativa (`GET /v2/charge/pix/{id}/payments`), listagem paginada (`GET /v2/charge/pix`) e consulta consolidada (`GET /v2/charge/pix/all`). - **Webhooks Pix:** Dispara automaticamente os eventos `pix.created` na criação do QR Code e `pix.paid` (enriquecido com `e2e_id`, `movement_id`, `transaction_id` e `payer`) na liquidação. ### [POST] Criar Cobrança Pix (COBV) - **Endpoint**: `POST https://api.luri.io/v2/charge/pix` #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `IdempotencyKey` | `8a4c9b32-1111-2222-3333-444455556666` | - | | `Content-Type` | `application/json` | - | #### Request Body (`application/json`) ```json { "seller": "9519f68914bb40359a045ec8a142b75f", "amount": 15000, "reference_id": "PEDIDO-2026-001", "installment": { "number": 1, "total": 12 }, "tags": [ "Venda Online", "Plano Anual" ], "customer": { "taxpayer_id": "36160560042", "name": "Maria Oliveira", "email": "maria@exemplo.com", "phone_number": "11999887766", "street_line": "Av. Paulista, 1000", "street_line2": "Conjunto 42", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "postal_code": "01310100" }, "payment_method": { "expiration_date": "2026-12-31", "payment_limit_date": "2027-03-31", "billing_instructions": { "late_fee_percentage": 200, "interest_percentage": 100, "abatement_amount": 500, "discount": [ { "limit_date": "2026-12-20", "mode": "percentage", "amount": 500 } ] } } } ``` #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "id_pix": "f8a9e1d2-3c4b-5a6f-7e8d-9c0b1a2f3e4d", "txid": "7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b", "modality": "cobv", "status": "registered", "amount": 15000, "reference_id": "PEDIDO-2026-001", "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b5204000053039865405150.005802BR5915ESTABELECIMENTO6009SAO PAULO62070503***6304A1B2", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "12345678000195", "name": "Loja Exemplo LTDA", "chave_pix": "02a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" }, "created_at": "2026-08-14T08:30:00-03:00" } ``` --- ### [POST] Criar Pix Dinâmico (COB) - **Endpoint**: `POST https://api.luri.io/v2/charge/pix` #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Content-Type` | `application/json` | - | #### Request Body (`application/json`) ```json { "seller": "9519f68914bb40359a045ec8a142b75f", "amount": 5000, "reference_id": "PIX-IMEDIATO-123", "payment_method": { "expiration_seconds": 3600, "allow_amount_change": false, "payer_request": "Pagamento do Pedido #123" } } ``` #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "id_pix": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "txid": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "modality": "cob", "status": "registered", "amount": 5000, "reference_id": "PIX-IMEDIATO-123", "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cob/9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d520400005303986540550.005802BR5915ESTABELECIMENTO6009SAO PAULO62070503***6304C3D4", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "12345678000195", "name": "Loja Exemplo LTDA", "chave_pix": "02a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" }, "created_at": "2026-08-14T08:31:00-03:00" } ``` --- ### [POST] Criar Pix Estático - **Endpoint**: `POST https://api.luri.io/v2/charge/pix` #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Content-Type` | `application/json` | - | #### Request Body (`application/json`) ```json { "seller": "9519f68914bb40359a045ec8a142b75f", "amount": 2500, "reference_id": "BALCAO-001", "payment_type": "static" } ``` #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "id_pix": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e", "txid": "a1b2c3d4e5f60123456789ab", "modality": "static", "status": "registered", "amount": 2500, "reference_id": "BALCAO-001", "emv": "00020101021126580014br.gov.bcb.pix013602a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c520400005303986540525.005802BR5915ESTABELECIMENTO6009SAO PAULO62070503***6304E5F6", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "12345678000195", "name": "Loja Exemplo LTDA", "chave_pix": "02a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" }, "created_at": "2026-08-14T08:32:00-03:00" } ``` --- ### [GET] Buscar Cobrança Pix - **Endpoint**: `GET https://api.luri.io/v2/charge/pix/PEDIDO-2026-001` #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": [ { "id_pix": "f8a9e1d2-3c4b-5a6f-7e8d-9c0b1a2f3e4d", "txid": "7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b", "status": "registered", "amount": 15000, "reference_id": "PEDIDO-2026-001", "emv": "00020101021226870014br.gov.bcb.pix...", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "created_at": "2026-08-14T08:30:00-03:00", "updated_at": "2026-08-14T08:30:00-03:00", "tags": [ "Venda Online" ], "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "chave_pix": "02a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" }, "customer": { "taxpayer_id": "36160560042", "name": "Maria Oliveira", "email": "maria@exemplo.com" } } ], "has_more": false, "total_pages": 1, "page": 1, "total": 1, "query_count": 1 } ``` --- ### [GET] Listar Cobranças Pix - **Endpoint**: `GET https://api.luri.io/v2/charge/pix?seller_id=9519f68914bb40359a045ec8a142b75f&page=1&limit=10` #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `seller_id` | Sim/Ativo | `9519f68914bb40359a045ec8a142b75f` | - | | `page` | Sim/Ativo | `1` | - | | `limit` | Sim/Ativo | `10` | - | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": [ { "id_pix": "f8a9e1d2-3c4b-5a6f-7e8d-9c0b1a2f3e4d", "txid": "7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b", "status": "registered", "amount": 15000, "reference_id": "PEDIDO-2026-001", "emv": "00020101021226870014br.gov.bcb.pix...", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "created_at": "2026-08-14T08:30:00-03:00", "updated_at": "2026-08-14T08:30:00-03:00", "tags": [ "Venda Online" ], "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "chave_pix": "02a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" }, "customer": { "taxpayer_id": "36160560042", "name": "Maria Oliveira" } } ], "has_more": false, "total_pages": 1, "page": 1, "total": 1, "query_count": 1 } ``` --- ### [GET] Consultar Todos os Pix - **Endpoint**: `GET https://api.luri.io/v2/charge/pix/all?seller_id=9519f68914bb40359a045ec8a142b75f&page=1&limit=50` #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `seller_id` | Sim/Ativo | `9519f68914bb40359a045ec8a142b75f` | Identificador obrigatório do seller | | `start_date` | Opcional | `2026-01-01` | - | | `end_date` | Opcional | `2026-12-31` | - | | `page` | Sim/Ativo | `1` | - | | `limit` | Sim/Ativo | `50` | - | --- ### [GET] Consultar Detalhes de Pagamento do Pix (Conciliação Ativa) - **Endpoint**: `GET https://api.luri.io/v2/charge/pix/f8a9e1d2-3c4b-5a6f-7e8d-9c0b1a2f3e4d/payments` Consulta diretamente na instituição liquidante (BMP `GET /api/v2/QRCode/{codigoQRCode}/DetalhesPagamento`) todos os pagamentos recebidos para o QR Code da cobrança (`e2e_id`, `receipt_id`, `movement_id`, `amount`, `payment_date`) e eventuais devoluções (`refunds`), realizando conciliação ativa caso a cobrança ainda não esteja com status `paid`. #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `reconcile` | Opcional | `true` | Concilia ativamente o título para status 'paid' caso haja pagamento confirmado no liquidante (padrão: true) | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "id_pix": "f8a9e1d2-3c4b-5a6f-7e8d-9c0b1a2f3e4d", "txid": "7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b", "codigo_qrcode": "b1c2d3e4-f5a6-4789-8a9b-0c1d2e3f4a5b", "status": "paid", "reconciled": true, "total_payments": 1, "total_paid_amount": 15000, "total_refunded_amount": 0, "payments": [ { "e2e_id": "E1337083520261108172030123456789", "receipt_id": "f1e2d3c4-b5a6-4987-8c9d-0e1f2a3b4c5d", "movement_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "txid": "7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b", "amount": 15000, "payment_date": "2026-11-08T14:20:30", "refunds": [] } ] } ``` --- ## Módulo: Accounts A rota de `accounts` da API v2 fornece acesso aos dados financeiros e de extratos bancários vinculados aos seus vendedores (sellers). > **Segurança e Webhooks de Conta (`account.*`):** Todos os sub-recursos de `accounts` exigem **obrigatoriamente** que a requisição venha assinada via **JWT** (JSON Web Token) no cabeçalho (*Bearer Token*). O método *Basic Auth* não tem permissão de leitura neste endpoint. Além disso, marketplaces que possuem credencial **JWT ativa** e `url_webhook` configurada recebem automaticamente todos os webhooks de eventos e movimentações em conta (`account.pix.*`, `account.ted.*`, `account.transfer.*`, `account.bill_payment.*`, `account.utility_payment.*`, `account.service_fee`, `account.split`, etc.). ### [GET] Listar Contas Base - **Endpoint**: `GET https://api.luri.io/v2/accounts/` Obtém a lista de todas as contas cadastradas e ativas que pertencem ao seu marketplace atual. Requer obrigatoriamente autenticação via JWT. #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `page` | Opcional | `1` | Navega pelos resultados, página a página. | | `limit` | Opcional | `300` | Quantidade de itens por requisição (máximo 1000). | #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Bearer :jwt_token` | - | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": [ { "banco": "001", "agencia": "1234", "conta": "56789-0", "tipo_conta": "3", "correntista": "João da Silva", "documento": "11222333000199", "status": 1, "account_id": "567890" } ], "has_more": false, "total_pages": 1, "page": 1, "total": 1, "query_count": 1 } ``` ##### HTTP 401 (Unauthorized) ```json { "error": { "status": "Unauthorized", "status_code": 401, "message": "JWT token is required for accounts endpoint." } } ``` --- ### [GET] Consultar Saldo da Conta (Balance) - **Endpoint**: `GET https://api.luri.io/v2/accounts/:account_id/balance` Consulta em tempo real o saldo disponível, bloqueado e agendado da conta diretamente no provedor BaaS (`api/Conta/Saldo`). Requer obrigatoriamente autenticação via JWT RS256 e escopo `api.ext api.conta.saldo`. #### Path Variables | Parâmetro | Exemplo | Descrição | | :--- | :--- | :--- | | `account_id` | `567890` | Número da conta (com ou sem dígito/hífen) ou `hash_seller`. | #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `seller_id` | Opcional | `9519f68914bb40359a045ec8a142b75f` | ID único que identifica o estabelecimento comercial e sua conta. Caso o estabelecimento tenha mais de uma conta, terá seller ids diferentes. | | `seller_ein` | Opcional | `11222333000199` | Documento (CPF/CNPJ) do seller. | #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Bearer :jwt_token` | Token JWT RS256 obrigatório (escopo: `api.ext api.conta.saldo`) | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "balance", "account": { "account_id": "567890", "seller_id": "9519f68914bb40359a045ec8a142b75f", "banco": "001", "agencia": "1234", "conta": "56789-0", "conta_pgto": "567890", "modelo": "Movimento", "correntista": "João da Silva", "documento": "11222333000199" }, "balance": { "saldo_disponivel": "15420.50", "saldo_bloqueado": "0.00", "saldo_agendado": "0.00", "dt_ult_atualizacao": "2026-10-20 09:12:09" } } ``` ##### HTTP 404 (Not Found) ```json { "error": { "status": "Not Found", "status_code": 404, "message": "Account not found or does not belong to the authenticated marketplace." } } ``` --- ### [GET] Listar Extratos (Statements) - **Endpoint**: `GET https://api.luri.io/v2/accounts/:account_id/statements` Consulta diretamente no liquidante BaaS (`api/Conta/Extrato`) o histórico de transações bancárias e o resumo de saldos do período (`items.balance`) de uma conta específica. Quando nenhum filtro de data é informado, retorna automaticamente as movimentações dos **últimos 30 dias**. Requer obrigatoriamente autenticação via JWT RS256 e escopo `api.ext api.conta.extrato`. #### Path Variables | Parâmetro | Exemplo | Descrição | | :--- | :--- | :--- | | `account_id` | `567890` | O identificador ou próprio número da conta requerida. | #### Query Parameters | Parâmetro | Obrigatório | Exemplo | Descrição | | :--- | :--- | :--- | :--- | | `limit` | Opcional | `100` | Quantidade de itens (movimentações) por requisição. Padrão 300, limite máximo 1000. | | `page` | Opcional | `1` | Navega pelos resultados, página a página. | | `seller_id` | Opcional | `9519f68914bb40359a045ec8a142b75f` | ID único que identifica o estabelecimento comercial e sua conta. Caso o estabelecimento tenha mais de uma conta, terá seller ids diferentes. | | `seller_ein` | Opcional | `11222333000199` | Documento (CPF/CNPJ) do seller. | | `created_date_lte` | Opcional | `2026-10-31` | Data da movimentação no extrato, formato “YYYY-MM-DD” menor igual a este valor. | | `created_date_gte` | Opcional | `2026-10-01` | Data da movimentação no extrato, formato “YYYY-MM-DD” maior igual a este valor. | | `operacao` | Opcional | `ENVIO PIX` | Filtra as movimentações pela descrição ou código da operação bancária (exs: ENVIO PIX, PIXENV, RECEBIMENTO PIX, PIXREC, TED). | | `d_c` | Opcional | `D` | Filtra por natureza do lançamento: D (Débito) ou C (Crédito). | | `dt_mov` | Opcional | `2026-10-02` | Data específica da movimentação requerida (YYYY-MM-DD). | #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Bearer :jwt_token` | Token JWT RS256 obrigatório (escopo: `api.ext api.conta.extrato`) | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "resource": "list", "items": { "account": { "banco": "001", "agencia": "1234", "conta": "56789-0", "conta_pgto": "567890", "modelo": "Movimento", "correntista": "João da Silva", "documento": "11222333000199" }, "balance": { "saldo_inicial": "25720.50", "dt_saldo_inicial": "2026-10-01", "saldo_final": "15420.50", "dt_saldo_final": "2026-10-31", "saldo_disponivel": "15420.50", "saldo_bloqueado": "0.00", "dt_extrato": "2026-10-31 18:00:00" }, "transactions": [ { "modelo": "Movimento", "operador": "João da Silva", "dt_mov": "2026-10-02 17:36:04", "operacao": "ENVIO PIX", "identificador_operacao": "PIXENV", "valor": "10300.00", "d_c": "D", "nsu": "123456789", "banco_origem": "001", "ag_origem": "1111", "conta_origem": null, "complemento": "Pagamento a fornecedor", "observacoes": "Lote 012", "ISPB_destino": null, "nome_contraparte": "Fornecedor XYZ", "doc_contraparte": "33444555000100", "ISPB_Origem": null, "doc_correntista": "11222333000199", "end_to_end": null, "codigo": "f5c95010-599d-4b8f-9563-f125d870389e", "codigo_transacao": "9d1393fe-728b-474b-af71-299115cfc22c", "saldo_final_dia": "15420.50" } ] }, "has_more": false, "total_pages": 1, "page": 1, "total": 1, "query_count": 1 } ``` ##### HTTP 404 (Not Found) ```json { "error": { "status": "Not Found", "status_code": 404, "message": "Account not found or does not belong to the authenticated marketplace." } } ``` --- ## Módulo: Webhook Webhooks (HTTP Callbacks) são notificações automáticas enviadas via `HTTP POST` para a URL pública configurada no seu marketplace sempre que ocorrer um evento no ciclo de vida de uma cobrança (**Boleto Bancário**, **Boleto Híbrido** ou **Pix**), de uma **Movimentação Bancária em Conta (`account.*`)** ou de credenciais de segurança (**Chaves Públicas RSA**). ### Escopo de Envio por Credencial (Basic Auth vs. JWT) - **Escopo Basic Auth + JWT (Eventos de Cobrança — `boleto.*` e `pix.*`):** Enviados para **qualquer** marketplace que possua `url_webhook` ativa. - **Escopo Exclusivo JWT (Eventos em Conta — `account.*`):** Enviados **somente** para marketplaces que possuam `url_webhook` ativa **E** credencial **JWT (Chave Pública RSA RS256)** ativa configurada em `/v2/auth/public-keys`. --- ### Requisitos e Política de Entrega 1. **URL Pública HTTPS (TLS 1.2+):** O seu sistema deve expor uma URL acessível publicamente via `https://` na porta padrão `443` (hosts locais e IPs privados são bloqueados contra SSRF). 2. **Confirmação Rápida (`HTTP 2xx`) e Fila Assíncrona:** Responda com status HTTP entre `200` e `299` em até **10 segundos**. Recomendamos enfileirar o payload internamente para processamento assíncrono. 3. **Retentativas Automáticas:** Caso o servidor de destino não responda dentro do timeout (5s de conexão / 10s total) ou retorne erro (`4xx`/`5xx`), a LURI realiza até **3 tentativas** automáticas. 4. **Idempotência:** Utilize o identificador único do evento (`id`) ou a combinação (`payload.boleto_id` / `payload.movement_id` + `type`) para evitar processamento duplicado. --- ### Gerenciamento via API RESTful (`/v2/webhooks`) Você pode gerenciar suas notificações diretamente via API com suporte a autenticação via **Basic Auth** ou **JWT**: - **Cadastrar / Atualizar Webhook (`POST /v2/webhooks`):** Envia a URL pública HTTPS de destino e retorna o `webhook_secret` criptográfico (ex: `whsec_...`) gerado para o seu marketplace. - **Consultar Webhook (`GET /v2/webhooks`):** Retorna os detalhes do webhook ativo do seu marketplace (`id`, `url`, `status` e flag `has_secret`). - **Excluir Webhook (`DELETE /v2/webhooks/{hash_marketplace}`):** Remove permanentemente a URL configurada e revoga o segredo de assinatura associado. --- ### Autenticação e Segurança (`webhook_secret` / HMAC-SHA256) Ao cadastrar o webhook via `POST /v2/webhooks`, a LURI gera o seu `webhook_secret`. Toda notificação enviada inclui cabeçalhos HTTP para verificação de autenticidade e integridade: - `X-Webhook-Signature`: Assinatura hexadecimal **HMAC-SHA256** calculada sobre o corpo bruto (`raw JSON`) utilizando o seu `webhook_secret`. - `X-Webhook-Timestamp`: Timestamp Unix de quando a notificação foi emitida. **Exemplo de validação no seu backend (PHP):** ```php $rawPayload = file_get_contents('php://input'); $signatureHeader = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; $webhookSecret = 'whsec_seu_secret_aqui'; $expectedSignature = hash_hmac('sha256', $rawPayload, $webhookSecret); if (hash_equals($expectedSignature, $signatureHeader)) { // Origem autêntica confirmada: o evento partiu da infraestrutura da LURI! } ``` --- ### Tipos de Webhooks Enviados #### 1. Eventos de Cobrança (`resource: "event"` — Escopo Basic Auth + JWT) | Tipo (`type`) | Status (`payload.status`) | Meio / Origem | Quando é Enviado | | :--- | :--- | :--- | :--- | | `boleto.created` | `created` | Boleto / Híbrido | Quando o boleto é criado e emitido na instituição financeira (`POST /v2/charge`). | | `boleto.registered` | `registered` | Boleto / Híbrido | Quando o registro do boleto é confirmado pelo banco/DDA (inclui código de barras, linha digitável e QR Code Pix `emv`/`imagem`). | | `boleto.failed` | `failed` | Boleto / CNAB | Quando ocorre falha ou rejeição bancária na emissão ou no registro do boleto (detalhe no campo `error`). | | `boleto.updated` | `registered` | Boleto / Híbrido | Quando uma alteração nos dados do boleto (`PATCH /v2/charge/{id}`) é confirmada no banco. | | `boleto.canceled` | `canceled` | Boleto / Híbrido | Quando o cancelamento ou baixa do boleto é confirmado pelo banco (`POST /v2/charge/{id}/cancel` ou baixa bancária). | | `boleto.paid` | `paid` | `payment_method: "boleto"` | Quando o pagamento via compensação de código de barras de boleto bancário é confirmado e creditado. | | `boleto.paid` | `paid` | `payment_method: "pix"` | Quando um **Boleto Híbrido** (`POST /v2/charge`) é liquidado instantaneamente via seu QR Code Pix. | | `pix.created` | `registered` | Pix (`POST /v2/charge/pix`) | Quando uma cobrança Pix pura (`static`, `cob` ou `cobv`) é criada e registrada na instituição liquidante (`emv` e `qrcode`). | | `pix.paid` | `paid` | `payment_method: "pix"` | Quando uma **cobrança Pix pura** (`POST /v2/charge/pix` — `static`, `cob` ou `cobv`, sem boleto vinculado) é liquidada via Pix. | | `boleto.assign` | — | Boleto | Quando há alteração ou registro na cessão do boleto. | #### 2. Eventos de Movimentação e Operações em Conta (`resource: "event"` — Exclusivo Marketplaces com JWT) Quando a conta bancária de um `seller` vinculado a um marketplace com **credencial JWT ativa** recebe qualquer evento financeiro ou operacional no banco liquidante, o **Roteador de Webhooks** identifica a conta do titular e envia a notificação com prefixo `account.*`: | Tipo (`type`) | Ação Bancária (`event_code`) | Operação (`operation`) | Quando é Enviado | | :--- | :--- | :--- | :--- | | `account.pix.received` | `RecebePix` (sem cobrança prévia) | `credit` | Quando a conta recebe um **Pix avulso / transferência direta na Chave Pix** (sem vínculo com cobrança criada em `/v2/charge` ou `/v2/charge/pix`). | | `account.pix.sent` | `EnvioPix` | `debit` | Quando um envio/transferência Pix (cash-out) é debitado da conta do seller. | | `account.pix.failed` | `RejeicaoEnvioPix` | `credit` / `info` | Quando um envio Pix é rejeitado no SPI e estornado/cancelado na conta. | | `account.pix.refunded` | `DevolucaoPix` | `debit` / `credit` | Quando uma devolução de Pix é processada na conta. | | `account.pix.reversed` | `EstornoPix` | `credit` | Quando um estorno/devolução de Pix enviado anteriormente é creditado a favor da conta. | | `account.pix.refund_failed` | `RejeicaoDevolucaoPix` | `info` | Quando uma solicitação de devolução Pix é rejeitada pelo SPI. | | `account.ted.received` | `RecebTED` | `credit` | Quando a conta recebe uma transferência TED (cash-in). | | `account.ted.sent` | `EnvioTED` | `debit` | Quando uma transferência TED (cash-out) é debitada da conta. | | `account.ted.refunded` | `DevolucaoTED` | `credit` | Quando uma TED enviada é devolvida pelo banco destinatário e recreditada na conta. | | `account.transfer.received` | `RecebTransf` | `credit` | Quando a conta recebe uma transferência interna entre contas da instituição. | | `account.transfer.sent` | `EnvioTransf` | `debit` | Quando a conta envia uma transferência interna entre contas da instituição. | | `account.bill_payment.paid` | `PagamentoBoleto` | `debit` | Quando um pagamento de título/boleto de terceiros é debitado na conta. | | `account.bill_payment.refunded` | `DevolucaoTitulo` | `credit` | Quando um pagamento de título/boleto é devolvido e estornado na conta. | | `account.utility_payment.paid` | `PagamentoTituloConcessionaria` | `debit` | Quando um pagamento de conta de consumo/concessionária ou tributo é debitado na conta. | | `account.utility_payment.refunded` | `DevolucaoPagamentoTituloConcessionaria` | `credit` | Quando um pagamento de concessionária é devolvido/estornado na conta. | | `account.service_fee` | `movimentoServico` | `debit` | Quando uma tarifa bancária de serviço (custo de envio/recebimento Pix, registro/baixa/protesto de boleto, TED, etc.) é debitada na conta. | | `account.split` | `MovimentoSplit` | `credit` / `debit` | Quando ocorre lançamento de split financeiro na conta. | | `account.movement.other` | `OutrosMovimentos` | `credit` / `debit` | Quando ocorre outro lançamento financeiro avulso na conta. | | `account.boleto.credit_preview` | `PreviaBoletoCredito` | `info` | Quando o banco informa a prévia de liquidação/crédito de boleto na conta. | | `account.boleto.protested` | `ProtestoBoleto` | `info` | Quando ocorre confirmação/atualização de protesto de título vinculado à conta. | | `account.boleto.unified_credit` | `BoletoCreditoUnificado` | `credit` | Quando ocorre crédito unificado de liquidação de boletos em conta. | | `account.card.*` | `CompraCartao` / `DevolucaoCompraCartao` / `SaqueCartao` / `DevolucaoSaqueCartao` | `debit` / `credit` | Eventos de movimentação de cartão vinculado à conta (`purchase`, `purchase_refunded`, `withdrawal`, `withdrawal_refunded`). | | `account.cnab.*` | `CNAB_REG`, `CNAB_PGT`, `CNAB_CAN`, `CNAB_ALT`, `CNABRemessa`, `CNABRetorno` | `info` | Eventos de processamento de arquivos CNAB vinculados à conta. | | `account.` | `` | `credit` / `debit` / `info` | Fallback dinâmico: qualquer outro evento presente ou futuro emitido pelo liquidante para a conta do seller. | #### 3. Eventos de Segurança / Chaves Públicas (`event: "public_key.*"`) | Evento (`event`) | Cabeçalho `X-Event` | Quando é Enviado | | :--- | :--- | :--- | | `public_key.created` | `public_key.created` | Imediatamente após o cadastro de uma nova chave pública RSA via `POST /v2/auth/public-keys`. | | `public_key.revoked` | `public_key.revoked` | Imediatamente após a revogação de uma chave pública via `DELETE /v2/auth/public-keys/{kid}`. | --- ### Exemplos de Payloads por Tipo de Evento #### 1. `boleto.created` e `boleto.registered` (Criação / Confirmação de Registro) ```json { "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "resource": "event", "type": "boleto.registered", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "0000370296065", "status": "registered", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-2026-001", "tags": ["mensalidade", "parcela-1"], "id_customer": "c8f9a1b2-3d4e-5f6a-7b8c-9d0e1f2a3b4c", "updated_at": "2026-11-08T17:31:10+00:00", "linha_cod_barras": "27494149000001500000012221000037029606506000", "linha_digitavel": "27490.00129 22100.003704 29606.506000 4 14900000150000", "emv": "00020101021226870014br.gov.bcb.pix...", "imagem": "iVBORw0KGgoAAAANSUhEUgAA..." }, "created_at": "2026-11-08 14:31:12" } ``` *(No evento `boleto.created`, o `payload` inclui adicionalmente o objeto `payment_method` com `expiration_date`, `payment_limit_date`, `billing_instructions` e `body_instructions`).* #### 2. `boleto.failed` (Falha ou Rejeição na Emissão) ```json { "id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f", "resource": "event", "type": "boleto.failed", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133", "status": "failed", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-2026-001", "tags": ["mensalidade", "parcela-1"], "id_customer": "c8f9a1b2-3d4e-5f6a-7b8c-9d0e1f2a3b4c", "error": "Falha na emissão do boleto junto ao banco", "updated_at": "2026-11-08T14:30:05-03:00" }, "created_at": "2026-11-08 14:30:05" } ``` #### 3. `boleto.canceled` (Cancelamento / Baixa Confirmada) ```json { "id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b", "resource": "event", "type": "boleto.canceled", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133", "status": "canceled", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-2026-001", "tags": ["mensalidade", "parcela-1"], "id_customer": "41b466ec2de5b02178f1bf8a2e123133", "updated_at": "2026-11-08T18:00:00+00:00" }, "created_at": "2026-11-08 15:00:02" } ``` #### 4. `boleto.paid` (Liquidação de Boleto ou Boleto Híbrido via Pix) Disparado quando uma cobrança com boleto (`POST /v2/charge`) é paga. O campo `payload.payment_method` indica se o pagamento foi realizado via código de barras (`"boleto"`) ou via QR Code Pix do boleto híbrido (`"pix"`): ```json { "id": "3f9e1b5d-fbef-4b8a-a8ae-3c16565e0454", "resource": "event", "type": "boleto.paid", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "0000370296065", "status": "paid", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "total_amount": 15000, "interest": 0, "discount": 0, "payment_date": "2026-11-08T17:20:30+00:00", "credit_date": "2026-11-08T17:20:30+00:00", "expiration_date": "2026-11-20", "payment_method": "pix" }, "created_at": "2026-11-08 14:20:32" } ``` #### 5. `pix.created` (Criação de Cobrança Pix Pura — `POST /v2/charge/pix`) Disparado imediatamente após a criação e registro de uma cobrança Pix (`static`, `cob` ou `cobv`): ```json { "id": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c", "resource": "event", "type": "pix.created", "payload": { "id_pix": "e4d5c6b7a8f90123456789abcdef0123", "boleto_id": "e4d5c6b7a8f90123456789abcdef0123", "txid": "LURI20261108142030ABCDEF123456", "modality": "cobv", "status": "registered", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-PIX-2026-099", "emv": "00020101021226870014br.gov.bcb.pix...", "qrcode": "iVBORw0KGgoAAAANSUhEUgAA..." }, "created_at": "2026-11-08 14:15:01" } ``` #### 6. `pix.paid` (Liquidação de Cobrança Pix Pura — `/v2/charge/pix`) Disparado quando uma cobrança Pix emitida em `POST /v2/charge/pix` (sem boleto associado) é liquidada, incluindo identificadores da transação (`e2e_id`, `movement_id`, `transaction_id`) e dados do pagador (`payer`): ```json { "id": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f", "resource": "event", "type": "pix.paid", "payload": { "id_pix": "e4d5c6b7a8f90123456789abcdef0123", "boleto_id": "e4d5c6b7a8f90123456789abcdef0123", "txid": "LURI20261108142030ABCDEF123456", "e2e_id": "E1337083520261108172030123456789", "movement_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "transaction_id": "f1e2d3c4-b5a6-4987-8c9d-0e1f2a3b4c5d", "reference_id": "PEDIDO-PIX-2026-099", "status": "paid", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "total_amount": 15000, "interest": 0, "discount": 0, "payment_date": "2026-11-08T17:20:30+00:00", "credit_date": "2026-11-08T17:20:30+00:00", "expiration_date": "2026-11-20", "payment_method": "pix", "payer": { "name": "Maria Oliveira", "taxpayer_id": "36160560042", "bank_ispb": "00000000", "branch": "0001" } }, "created_at": "2026-11-08 14:20:32" } ``` #### 7. `account.*` (Eventos de Movimentação e Operações em Conta — Exclusivo JWT) Disparados exclusivamente para marketplaces com **credencial JWT ativa** quando ocorre uma movimentação na conta bancária do seller (como `account.pix.sent`, `account.pix.received` avulso, `account.ted.received`, `account.service_fee`, etc.): ```json { "id": "6f8a9b0c-1d2e-4f3a-8b9c-0d1e2f3a4b5c", "resource": "event", "type": "account.pix.sent", "payload": { "seller": { "id": "4e12dad6b58d4f83a9a12312312bd3757b", "name": "ABR PISCINAS COMPACTAS LTDA", "document": "66405113000185", "agency": "0001", "account": "986067-7" }, "event_code": "EnvioPix", "operation": "debit", "type_lancto": "D", "amount": "80.00", "amount_cents": 8000, "transaction_date": "2026-11-05T21:05:10.683", "movement_id": "e15075bf-fe5a-457c-a81b-b8366b0a01d3", "transaction_id": "3ed17a4c-75f6-4b66-a9e0-3a679c2edae5", "e2e_id": "E11581339202611060004A093F3805DD", "nsu": 289316327, "description": null, "counterparty": { "role": "beneficiary", "name": "Leticia Minotto Ravanholi", "document": "03979389006", "pix_key": "03979389006", "bank_ispb": "10573521", "agency": "0001" }, "details": { "Identificador": "27400010986067766405113000185", "CodigoMovimento": "e15075bf-fe5a-457c-a81b-b8366b0a01d3", "NumeroOperacao": "E11581339202611060004A093F3805DD", "VlrTransacao": 80, "TipoLancto": "D" } }, "created_at": "2026-11-06 00:05:11" } ``` #### 8. `public_key.created` / `public_key.revoked` (Segurança e Chaves Públicas) ```json { "event": "public_key.created", "request_id": "req_a1b2c3d4e5f67890", "timestamp": "2026-11-08T14:30:00-03:00", "data": { "hash_marketplace": "4b7e010c54a048efab973279355dbc51", "kid": "prod-key-2026-v1", "algorithm": "RS256", "key_size": 2048, "fingerprint_sha256": "4b68e982d6fc5732c4d622955f269389e1b2123d24268e3b5df51a84f506ee4f", "status": "active", "created_at": "2026-11-08T14:30:00-03:00", "ip_address": "177.18.25.10" } } ``` ### [POST] Cadastrar / Atualizar Webhook - **Endpoint**: `POST https://api.luri.io/v2/webhooks` Cadastra ou substitui a URL pública de destino para notificações de Webhook do marketplace e gera uma nova chave secreta criptográfica (webhook_secret). - **webhook_secret:** Retornado exclusivamente nesta resposta para utilização na validação de assinatura HMAC-SHA256. #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Basic :basic_auth` | Basic Auth (credencial do marketplace) OU Bearer {{token}} (JWT RS256) | | `Content-Type` | `application/json` | - | #### Request Body (`application/json`) ```json { "url": "https://api.empresa.com.br/webhooks/luri" } ``` #### Respostas de Exemplo ##### HTTP 201 (Created) ```json { "success": true, "status_code": 201, "message": "Webhook cadastrado com sucesso.", "data": { "id": "af0bbf2a540846798357a84d02dac2bc", "url": "https://api.empresa.com.br/webhooks/luri", "webhook_secret": "whsec_d47a8f9c1b2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e", "status": "active" } } ``` ##### HTTP 400 (Bad Request) ```json { "status": "Bad Request", "status_code": 400, "message": "O endereço IP de destino pertence a uma rede interna, privada ou metadados de nuvem e foi bloqueado (SSRF)." } ``` ##### HTTP 400 (Bad Request) ```json { "status": "Bad Request", "status_code": 400, "message": "Protocolo inseguro. Por exigência de segurança (TLS), apenas URLs com protocolo estritamente \"https://\" são aceitas." } ``` --- ### [GET] Consultar Webhook - **Endpoint**: `GET https://api.luri.io/v2/webhooks` Retorna a configuração ativa de webhook para o marketplace autenticado. #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Basic :basic_auth` | Basic Auth (credencial do marketplace) OU Bearer {{token}} (JWT RS256) | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "success": true, "status_code": 200, "data": [ { "id": "af0bbf2a540846798357a84d02dac2bc", "url": "https://api.empresa.com.br/webhooks/luri", "status": "active", "has_secret": true } ] } ``` --- ### [DELETE] Excluir Webhook - **Endpoint**: `DELETE https://api.luri.io/v2/webhooks/:hash_marketplace` Remove a configuração de webhook e revoga a chave secreta HMAC cadastrada para o marketplace informado na URL. #### Headers | Cabeçalho | Valor / Exemplo | Descrição | | :--- | :--- | :--- | | `Authorization` | `Basic :basic_auth` | Basic Auth (credencial do marketplace) OU Bearer {{token}} (JWT RS256) | #### Respostas de Exemplo ##### HTTP 200 (OK) ```json { "success": true, "status_code": 200, "message": "Webhook excluído com sucesso." } ``` --- # Apêndice A: Especificação Completa de Webhooks e Eventos em Conta # Documentação Completa de Webhooks (LURI v2) Webhooks (HTTP Callbacks) são notificações automáticas enviadas via `HTTP POST` pela plataforma **LURI** para uma URL pública configurada no seu marketplace sempre que ocorre um evento no ciclo de vida de uma cobrança (Boleto Bancário, Boleto Híbrido ou Pix) ou de credenciais de segurança (Chaves Públicas RSA). --- ## 1. Requisitos e Boas Práticas de Integração 1. **Canal Seguro Obrigatório (HTTPS / TLS 1.2+):** A URL de destino deve utilizar obrigatoriamente o protocolo `https://` na porta padrão `443` e possuir certificado SSL/TLS válido. Endereços locais (`localhost`), IPs privados (RFC 1918) ou portas não-padrão são bloqueados contra SSRF. 2. **Confirmação Rápida (`HTTP 2xx`) e Processamento Assíncrono:** Seu endpoint deve responder com um código HTTP de sucesso (`200` a `299`) em até **10 segundos**. Recomendamos que sua aplicação valide a assinatura, enfileire a mensagem internamente e retorne `200 OK` imediatamente. 3. **Política de Retentativas (Retry):** Caso o servidor de destino não responda dentro do timeout (5s de conexão / 10s total) ou retorne erro HTTP (`4xx` ou `5xx`), a LURI realizará até **3 tentativas de entrega** automáticas. 4. **Idempotência:** Utilize o identificador único do evento (`id`) ou a combinação (`payload.boleto_id` + `type`) para garantir que seu sistema processe cada transição de estado apenas uma vez. --- ## 2. Gerenciamento de Webhooks via API (`/v2/webhooks`) Você pode gerenciar a URL de recebimento e a chave de assinatura diretamente via API utilizando **Basic Auth** ou **JWT (Bearer Token)**: | Método | Endpoint | Autenticação | Descrição | | :--- | :--- | :--- | :--- | | `POST` | `/v2/webhooks` | Basic Auth / JWT | Cadastra ou atualiza a URL pública HTTPS e gera um novo `webhook_secret` (`whsec_...`). | | `GET` | `/v2/webhooks` | Basic Auth / JWT | Consulta a configuração ativa de webhook do marketplace (`id`, `url`, `status`, `has_secret`). | | `DELETE` | `/v2/webhooks/{hash_marketplace}` | Basic Auth / JWT | Remove o webhook configurado e revoga o `webhook_secret` associado. | --- ## 3. Cabeçalhos HTTP e Validação de Assinatura (HMAC-SHA256) Toda notificação de cobrança enviada pela LURI inclui os seguintes cabeçalhos HTTP: | Cabeçalho HTTP | Descrição | | :--- | :--- | | `Content-Type` | `application/json` | | `User-Agent` | `WebhookClient/1.0` (cobranças) ou `Luri-Webhook-Notifier/2.0` (chaves públicas) | | `X-Webhook-Signature` | Assinatura hexadecimal **HMAC-SHA256** calculada sobre o corpo bruto (`raw JSON`) usando o seu `webhook_secret`. | | `X-Webhook-Timestamp` | Timestamp Unix (segundos) do momento em que o disparo foi assinado. | ### Exemplo de Validação de Assinatura (PHP) ```php $rawPayload = file_get_contents('php://input'); $signatureHeader = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; $webhookSecret = 'whsec_seu_secret_aqui'; $expectedSignature = hash_hmac('sha256', $rawPayload, $webhookSecret); if (hash_equals($expectedSignature, $signatureHeader)) { // Assinatura válida: o evento é autêntico e íntegro $event = json_decode($rawPayload, true); http_response_code(200); } else { http_response_code(401); } ``` --- ## 4. Tipos de Eventos de Webhook Enviados e Escopo de Credencial (Basic Auth vs. JWT) A LURI envia três categorias de notificações para a URL cadastrada no seu marketplace, respeitando o nível de credencial configurado: 1. **Eventos de Cobrança (`boleto.*` e `pix.*` — Escopo Basic Auth + JWT):** Enviados para **qualquer** marketplace que possua `url_webhook` ativa. 2. **Eventos de Movimentação e Operações em Conta (`account.*` — Escopo Exclusivo JWT):** Enviados **somente** para marketplaces que possuam `url_webhook` ativa **E** pelo menos uma chave pública RSA (credencial JWT RS256) ativa configurada em `/v2/auth/public-keys`. 3. **Eventos de Segurança / Chaves Públicas (`public_key.*`):** Enviados no ciclo de vida das chaves públicas RSA. ### 4.1. Eventos de Cobrança (`resource: "event"` — Escopo Basic Auth + JWT) | Tipo (`type`) | Ação Bancária / Origem | Status da Cobrança | Quando é Disparado | | :--- | :--- | :--- | :--- | | `boleto.created` | `CriarBoleto` | `created` | Quando o boleto ou boleto híbrido é criado e emitido no liquidante (`POST /v2/charge`). | | `boleto.registered` | `RegistroBoleto` | `registered` | Quando o banco emissor confirma o registro do boleto na CIP/DDA e disponibiliza o código de barras e QR Code Pix (EMV). | | `boleto.failed` | `CriarBoletoFalha` / Retorno CNAB | `failed` | Quando ocorre uma falha ou rejeição bancária na emissão ou no registro do boleto. | | `boleto.updated` | `AlteracaoBoleto` | `registered` | Quando uma alteração nos dados do boleto (`PATCH /v2/charge/{id}`) é processada no banco. | | `boleto.canceled` | `CancelamentoBoleto` / `CancelarBoleto` | `canceled` | Quando o cancelamento ou baixa do boleto é confirmado pelo banco (`POST /v2/charge/{id}/cancel` ou baixa automática). | | `boleto.paid` | `BoletoCredito` (`payment_method: "boleto"`) | `paid` | Quando o pagamento via código de barras de boleto bancário é compensado e creditado. | | `boleto.paid` | `RecebePix` (`payment_method: "pix"`) | `paid` | Quando um **Boleto Híbrido** (criado em `POST /v2/charge`) é liquidado instantaneamente via seu QR Code Pix. | | `pix.created` | `CriarPix` | `registered` | Quando uma cobrança Pix pura (`static`, `cob` ou `cobv`) é criada e registrada na instituição liquidante (`POST /v2/charge/pix`). | | `pix.paid` | `RecebePix` (`payment_method: "pix"`) | `paid` | Quando uma **cobrança Pix pura** (criada em `POST /v2/charge/pix` — `static`, `cob` ou `cobv`, sem boleto vinculado) é liquidada via Pix. | | `boleto.assign` | `CessaoBoleto` | — | Quando ocorre evento de cessão fiduciária/carteira do título. | ### 4.2. Eventos de Movimentação e Operações em Conta (`resource: "event"` — Exclusivo Marketplaces com JWT) Quando a conta bancária de um `seller` vinculado a um marketplace com **credencial JWT ativa** sofre qualquer movimentação financeira, tarifa, transferência, pagamento ou evento operacional na instituição liquidante, o **Roteador de Webhooks** identifica automaticamente a conta do titular e encaminha o evento com prefixo `account.*`: | Tipo (`type`) | Ação Bancária (`event_code`) | Operação (`operation`) | Quando é Disparado | | :--- | :--- | :--- | :--- | | `account.pix.received` | `RecebePix` (sem cobrança em `api_boleto`) | `credit` | Quando a conta recebe um **Pix avulso / transferência direta via Chave Pix** (sem vínculo com cobrança emitida em `/v2/charge` ou `/v2/charge/pix`). | | `account.pix.sent` | `EnvioPix` | `debit` | Quando um envio/transferência Pix (cash-out) é debitado da conta do seller. | | `account.pix.failed` | `RejeicaoEnvioPix` | `credit` / `info` | Quando um envio Pix é rejeitado no SPI e estornado/cancelado na conta. | | `account.pix.refunded` | `DevolucaoPix` | `debit` / `credit` | Quando uma devolução de Pix é processada na conta. | | `account.pix.reversed` | `EstornoPix` | `credit` | Quando um estorno/devolução de Pix enviado anteriormente é creditado a favor da conta. | | `account.pix.refund_failed` | `RejeicaoDevolucaoPix` | `info` | Quando uma solicitação de devolução Pix é rejeitada pelo SPI. | | `account.ted.received` | `RecebTED` | `credit` | Quando a conta recebe uma transferência TED (cash-in). | | `account.ted.sent` | `EnvioTED` | `debit` | Quando uma transferência TED (cash-out) é debitada da conta. | | `account.ted.refunded` | `DevolucaoTED` | `credit` | Quando uma TED enviada é devolvida pelo banco destinatário e recreditada na conta. | | `account.transfer.received` | `RecebTransf` | `credit` | Quando a conta recebe uma transferência interna entre contas da instituição. | | `account.transfer.sent` | `EnvioTransf` | `debit` | Quando a conta envia uma transferência interna entre contas da instituição. | | `account.bill_payment.paid` | `PagamentoBoleto` | `debit` | Quando um pagamento de título/boleto de terceiros é debitado na conta. | | `account.bill_payment.refunded` | `DevolucaoTitulo` | `credit` | Quando um pagamento de título/boleto é devolvido e estornado na conta. | | `account.utility_payment.paid` | `PagamentoTituloConcessionaria` | `debit` | Quando um pagamento de conta de consumo/concessionária ou tributo é debitado na conta. | | `account.utility_payment.refunded` | `DevolucaoPagamentoTituloConcessionaria` | `credit` | Quando um pagamento de concessionária é devolvido/estornado na conta. | | `account.service_fee` | `movimentoServico` | `debit` | Quando uma tarifa bancária de serviço (custo de envio/recebimento Pix, registro/baixa/protesto de boleto, TED, etc.) é debitada na conta. | | `account.split` | `MovimentoSplit` | `credit` / `debit` | Quando ocorre lançamento de split financeiro na conta. | | `account.movement.other` | `OutrosMovimentos` | `credit` / `debit` | Quando ocorre outro lançamento financeiro avulso na conta. | | `account.boleto.credit_preview` | `PreviaBoletoCredito` | `info` | Quando o banco informa a prévia de liquidação/crédito de boleto na conta. | | `account.boleto.protested` | `ProtestoBoleto` | `info` | Quando ocorre confirmação/atualização de protesto de título vinculado à conta. | | `account.boleto.unified_credit` | `BoletoCreditoUnificado` | `credit` | Quando ocorre crédito unificado de liquidação de boletos em conta. | | `account.card.purchase` / `account.card.purchase_refunded` / `account.card.withdrawal` / `account.card.withdrawal_refunded` | `CompraCartao` / `DevolucaoCompraCartao` / `SaqueCartao` / `DevolucaoSaqueCartao` | `debit` / `credit` | Eventos de movimentação de cartão vinculado à conta. | | `account.cnab.*` | `CNAB_REG`, `CNAB_PGT`, `CNAB_CAN`, `CNAB_ALT`, `CNABRemessa`, `CNABRetorno` | `info` | Eventos de processamento de arquivos CNAB vinculados à conta. | | `account.` | `` | `credit` / `debit` / `info` | Fallback dinâmico: qualquer outro evento presente ou futuro emitido pelo liquidante para a conta do seller. | ### 4.3. Eventos de Segurança / Chaves Públicas (`event: "public_key.*"`) | Evento (`event`) | Cabeçalho `X-Event` | Quando é Disparado | | :--- | :--- | :--- | | `public_key.created` | `public_key.created` | Imediatamente após o cadastro de uma nova chave pública RSA via `POST /v2/auth/public-keys`. | | `public_key.revoked` | `public_key.revoked` | Imediatamente após a revogação de uma chave pública via `DELETE /v2/auth/public-keys/{kid}`. | --- ## 5. Estrutura e Exemplos de Payloads por Tipo de Webhook ### 5.1. `boleto.created` — Cobrança Criada Disparado após a criação inicial do título na instituição financeira. ```json { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "resource": "event", "type": "boleto.created", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133", "status": "created", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-2026-001", "tags": [ "mensalidade", "parcela-1" ], "id_customer": "41b466ec2de5b02178f1bf8a2e123133", "payment_method": { "expiration_date": "2026-11-20", "payment_limit_date": "2027-02-18", "billing_instructions": { "late_fee_amount": 200, "interest_amount": 100, "discount_percentage": 500, "discount_limit_date": "2026-11-15" }, "body_instructions": { "line1": "Não receber após a data limite", "line2": "Cobrar multa e juros após o vencimento", "line3": "" } }, "linha_cod_barras": "27494149000001500000012221000037029606506000", "linha_digitavel": "27490.00129 22100.003704 29606.506000 4 14900000150000", "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/...", "imagem": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA..." }, "created_at": "2026-11-08 14:30:00" } ``` --- ### 5.2. `boleto.registered` — Boleto Registrado no Banco / DDA Disparado quando o banco confirma o registro do boleto na CIP/DDA, consolidando o `nosso_numero`, código de barras, linha digitável e o QR Code Pix (`emv` e `imagem` Base64). ```json { "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "resource": "event", "type": "boleto.registered", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "0000370296065", "status": "registered", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-2026-001", "tags": [ "mensalidade", "parcela-1" ], "id_customer": "c8f9a1b2-3d4e-5f6a-7b8c-9d0e1f2a3b4c", "updated_at": "2026-11-08T17:31:10+00:00", "linha_cod_barras": "27494149000001500000012221000037029606506000", "linha_digitavel": "27490.00129 22100.003704 29606.506000 4 14900000150000", "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/...", "imagem": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA..." }, "created_at": "2026-11-08 14:31:12" } ``` --- ### 5.3. `boleto.failed` — Falha na Emissão ou Rejeição Bancária Disparado quando o banco emissor recusa o registro ou a emissão do boleto, informando o motivo no campo `error` (ou `rejection_reason` / `rejection_codes` quando originado via lote CNAB). ```json { "id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f", "resource": "event", "type": "boleto.failed", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133", "status": "failed", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-2026-001", "tags": [ "mensalidade", "parcela-1" ], "id_customer": "c8f9a1b2-3d4e-5f6a-7b8c-9d0e1f2a3b4c", "error": "Falha na emissão do boleto junto ao banco", "updated_at": "2026-11-08T14:30:05-03:00" }, "created_at": "2026-11-08 14:30:05" } ``` --- ### 5.4. `boleto.updated` — Alteração de Dados do Boleto Disparado quando uma instrução de alteração (`PATCH /v2/charge/{id}` — vencimento, valor, multa, juros, descontos ou abatimento) é confirmada. ```json { "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a", "resource": "event", "type": "boleto.updated", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133", "status": "registered", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 16000, "reference_id": "PEDIDO-2026-001", "tags": [ "mensalidade", "parcela-1" ], "id_customer": "41b466ec2de5b02178f1bf8a2e123133", "payment_method": { "expiration_date": "2026-12-10", "payment_limit_date": "2027-03-10", "billing_instructions": { "late_fee_amount": 200, "interest_amount": 100, "discount_percentage": 0, "discount_limit_date": null }, "body_instructions": { "line1": "Não receber após a data limite", "line2": "", "line3": "" } }, "linha_cod_barras": "27494151000001600000012221000037029606506000", "linha_digitavel": "27490.00129 22100.003704 29606.506000 4 15100000160000", "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/...", "imagem": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA..." }, "created_at": "2026-11-08 15:10:00" } ``` --- ### 5.5. `boleto.canceled` — Boleto Cancelado / Baixado Disparado quando o cancelamento ou baixa do boleto é efetivado no banco emissor. ```json { "id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b", "resource": "event", "type": "boleto.canceled", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133", "status": "canceled", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-2026-001", "tags": [ "mensalidade", "parcela-1" ], "id_customer": "41b466ec2de5b02178f1bf8a2e123133", "updated_at": "2026-11-08T18:00:00+00:00" }, "created_at": "2026-11-08 15:00:02" } ``` --- ### 5.6. `boleto.paid` — Boleto ou Boleto Híbrido Pago / Liquidado Disparado quando uma cobrança emitida via `POST /v2/charge` (Boleto ou Boleto Híbrido) é liquidada. O atributo `payload.payment_method` diferencia se a liquidação ocorreu por compensação de **Boleto (`"boleto"`)** ou via **QR Code Pix do Boleto Híbrido (`"pix"`)**: #### Exemplo A: Liquidado via Compensação de Boleto (`payment_method: "boleto"`) ```json { "id": "3f9e1b5d-fbef-4b8a-a8ae-3c16565e0454", "resource": "event", "type": "boleto.paid", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "0000370296065", "status": "paid", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "total_amount": 15300, "interest": 300, "discount": 0, "payment_date": "2026-11-08T12:15:00+00:00", "credit_date": "2026-11-08T12:15:00+00:00", "expiration_date": "2026-11-05", "payment_method": "boleto" }, "created_at": "2026-11-08 09:15:05" } ``` #### Exemplo B: Boleto Híbrido Liquidado via QR Code Pix (`payment_method: "pix"`) ```json { "id": "7a8b9c0d-1e2f-4a3b-5c6d-7e8f9a0b1c2d", "resource": "event", "type": "boleto.paid", "payload": { "boleto_id": "41b466ec2de5b02178f1bf8a2e123133", "nosso_numero": "0000370296065", "status": "paid", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "total_amount": 15000, "interest": 0, "discount": 0, "payment_date": "2026-11-08T17:20:30+00:00", "credit_date": "2026-11-08T17:20:30+00:00", "expiration_date": "2026-11-20", "payment_method": "pix" }, "created_at": "2026-11-08 14:20:32" } ``` --- ### 5.7. `pix.created` — Cobrança Pix Criada / Registrada (`POST /v2/charge/pix`) Disparado assim que uma cobrança Pix (`static`, `cob` ou `cobv`) é gerada e registrada com sucesso em `POST /v2/charge/pix`, entregando o `emv` (Pix Copia e Cola) e `qrcode` (Base64). ```json { "id": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c", "resource": "event", "type": "pix.created", "payload": { "id_pix": "e4d5c6b7a8f90123456789abcdef0123", "boleto_id": "e4d5c6b7a8f90123456789abcdef0123", "txid": "LURI20261108142030ABCDEF123456", "modality": "cobv", "status": "registered", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "reference_id": "PEDIDO-PIX-2026-099", "installment": { "number": 1, "total": 12 }, "tags": [ "mensalidade", "parcela-1" ], "id_customer": "c8f9a1b2-3d4e-5f6a-7b8c-9d0e1f2a3b4c", "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/...", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "payment_method": { "expiration_date": "2026-11-20", "payment_limit_date": "2027-02-18", "billing_instructions": { "late_fee_percentage": 200, "interest_percentage": 100, "interest_mode": "percentage_monthly", "discount": [ { "limit_date": "2026-11-15", "mode": "percentage", "amount": 500 } ] } }, "created_at": "2026-11-08T14:15:00-03:00" }, "created_at": "2026-11-08 14:15:01" } ``` --- ### 5.8. `pix.paid` — Cobrança Pix Pura Liquidada (`/v2/charge/pix`) Disparado quando uma cobrança Pix emitida diretamente pelo endpoint `POST /v2/charge/pix` (Estático `static`, Dinâmico `cob` ou Cobrança com Vencimento `cobv`, que não possui boleto bancário associado) é liquidada. Inclui os identificadores de liquidação na rede SPI (`e2e_id`, `movement_id`, `transaction_id`) e os dados do pagador (`payer`) quando retornados pela instituição liquidante. ```json { "id": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f", "resource": "event", "type": "pix.paid", "payload": { "id_pix": "e4d5c6b7a8f90123456789abcdef0123", "boleto_id": "e4d5c6b7a8f90123456789abcdef0123", "txid": "LURI20261108142030ABCDEF123456", "e2e_id": "E1337083520261108172030123456789", "movement_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "transaction_id": "f1e2d3c4-b5a6-4987-8c9d-0e1f2a3b4c5d", "reference_id": "PEDIDO-PIX-2026-099", "status": "paid", "seller": "4e12dad6b58d4f83a9a12312312bd3757b", "amount": 15000, "total_amount": 15000, "interest": 0, "discount": 0, "payment_date": "2026-11-08T17:20:30+00:00", "credit_date": "2026-11-08T17:20:30+00:00", "expiration_date": "2026-11-20", "payment_method": "pix", "payer": { "name": "Maria Oliveira", "taxpayer_id": "36160560042", "bank_ispb": "00000000", "branch": "0001" } }, "created_at": "2026-11-08 14:20:32" } ``` --- ### 5.9. `account.*` — Eventos de Movimentação e Operações em Conta (Exclusivo JWT) Disparados exclusivamente para marketplaces que possuem **credencial JWT ativa** quando ocorre uma movimentação na conta bancária do seller (como `account.pix.received` avulso, `account.pix.sent`, `account.ted.received`, `account.service_fee`, etc.). #### Exemplo A: `account.pix.sent` — Envio de Pix (Cash-out) ```json { "id": "6f8a9b0c-1d2e-4f3a-8b9c-0d1e2f3a4b5c", "resource": "event", "type": "account.pix.sent", "payload": { "seller": { "id": "4e12dad6b58d4f83a9a12312312bd3757b", "name": "ABR PISCINAS COMPACTAS LTDA", "document": "66405113000185", "agency": "0001", "account": "986067-7" }, "event_code": "EnvioPix", "operation": "debit", "type_lancto": "D", "amount": "80.00", "amount_cents": 8000, "transaction_date": "2026-11-05T21:05:10.683", "movement_id": "e15075bf-fe5a-457c-a81b-b8366b0a01d3", "transaction_id": "3ed17a4c-75f6-4b66-a9e0-3a679c2edae5", "e2e_id": "E11581339202611060004A093F3805DD", "nsu": 289316327, "description": null, "counterparty": { "role": "beneficiary", "name": "Leticia Minotto Ravanholi", "document": "03979389006", "pix_key": "03979389006", "bank_ispb": "10573521", "agency": "0001" }, "details": { "Identificador": "27400010986067766405113000185", "CodigoMovimento": "e15075bf-fe5a-457c-a81b-b8366b0a01d3", "NumeroOperacao": "E11581339202611060004A093F3805DD", "VlrTransacao": 80, "TipoLancto": "D" } }, "created_at": "2026-11-06 00:05:11" } ``` #### Exemplo B: `account.pix.received` — Recebimento de Pix Avulso na Chave da Conta ```json { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "resource": "event", "type": "account.pix.received", "payload": { "seller": { "id": "4e12dad6b58d4f83a9a12312312bd3757b", "name": "FUNDACAO PAULISTA DE TECNOLOGIA E EDUCACAO", "document": "51665727000129", "agency": "0001", "account": "288558-0" }, "event_code": "RecebePix", "operation": "credit", "type_lancto": "C", "amount": "100.00", "amount_cents": 10000, "transaction_date": "2026-11-05T21:24:15.607", "movement_id": "5e2d546e-f0b0-4633-af7b-8bf8a14c699b", "transaction_id": "0f9382c9-a8ee-43d1-b6f5-5bfdd1279f20", "e2e_id": "E228964312026110600231T6WC7F9PPD", "nsu": 289322193, "description": null, "counterparty": { "role": "payer", "name": "MARCO AURELIO RODRIGUES DIAS", "document": "38876716866", "bank_ispb": "22896431", "agency": "0001" }, "details": { "Identificador": "27400010288558051665727000129", "RecebedorChave": "51665727000129", "CodigoMovimento": "5e2d546e-f0b0-4633-af7b-8bf8a14c699b", "NumeroOperacao": "E228964312026110600231T6WC7F9PPD", "VlrTransacao": 100, "TipoLancto": "C" } }, "created_at": "2026-11-06 00:24:16" } ``` --- ### 5.10. `public_key.created` e `public_key.revoked` — Ciclo de Vida de Chaves Públicas Disparados quando uma chave pública assimétrica (RS256) é adicionada ou revogada em `/v2/auth/public-keys`. #### Exemplo: `public_key.created` ```json { "event": "public_key.created", "request_id": "req_a1b2c3d4e5f67890", "timestamp": "2026-11-08T14:30:00-03:00", "data": { "hash_marketplace": "4b7e010c54a048efab973279355dbc51", "kid": "prod-key-2026-v1", "algorithm": "RS256", "key_size": 2048, "fingerprint_sha256": "4b68e982d6fc5732c4d622955f269389e1b2123d24268e3b5df51a84f506ee4f", "status": "active", "created_at": "2026-11-08T14:30:00-03:00", "ip_address": "177.18.25.10" } } ``` #### Exemplo: `public_key.revoked` ```json { "event": "public_key.revoked", "request_id": "req_9f8e7d6c5b4a3210", "timestamp": "2026-11-08T15:00:00-03:00", "data": { "hash_marketplace": "4b7e010c54a048efab973279355dbc51", "kid": "prod-key-2026-v1", "status": "revoked", "revoked_at": "2026-11-08T15:00:00-03:00", "ip_address": "177.18.25.10" } } ``` --- ## 6. Dicionário de Campos do `payload` (Eventos `boleto.*` e `pix.*`) | Campo | Tipo | Presente nos Eventos | Descrição | | :--- | :--- | :--- | :--- | | `boleto_id` | `string` | Todos (`boleto.*` e `pix.*`) | Identificador único da cobrança na LURI. | | `id_pix` | `string` | `pix.created`, `pix.paid` | Identificador único da cobrança Pix na LURI. | | `txid` | `string` | `pix.created`, `pix.paid` | Identificador da transação/conciliação Pix (`txid`). | | `modality` | `string` | `pix.created` | Modalidade da cobrança Pix: `"static"`, `"cob"` ou `"cobv"`. | | `e2e_id` | `string` | `pix.paid`, `boleto.paid` (via Pix) | EndToEndId (`NumeroOperacao` `E...`) da liquidação Pix no SPI/BACEN. | | `movement_id` | `string` | `pix.paid`, `boleto.paid` (via Pix) | UUID do movimento (`CodigoMovimento`) no liquidante. | | `transaction_id` | `string` | `pix.paid` | UUID da transação (`CodigoTransacao`) no liquidante. | | `payer` | `object` | `pix.paid` | Dados do pagador informados pelo SPI (`name`, `taxpayer_id`, `bank_ispb`, `branch`). | | `nosso_numero` | `string` | Todos (`boleto.*`) | Nosso número bancário (ou identificador do título enquanto aguarda confirmação). | | `status` | `string` | Todos (`boleto.*` e `pix.*`) | Estado atual da cobrança: `created`, `registered`, `failed`, `canceled` ou `paid`. | | `seller` | `string` | Todos (`boleto.*` e `pix.*`) | Identificador (`hash_seller`) do estabelecimento recebedor. | | `amount` | `integer` | Todos (`boleto.*` e `pix.*`) | Valor nominal original da cobrança em centavos (ex: `15000` = R$ 150,00). | | `total_amount` | `integer` | `boleto.paid`, `pix.paid` | Valor total efetivamente pago pelo sacado em centavos. | | `interest` | `integer` | `boleto.paid`, `pix.paid` | Soma de juros e multa cobrados na liquidação em centavos. | | `discount` | `integer` | `boleto.paid`, `pix.paid` | Valor total de desconto concedido na liquidação em centavos. | | `payment_date` | `string` | `boleto.paid`, `pix.paid` | Data/hora do pagamento no formato ISO 8601. | | `credit_date` | `string` | `boleto.paid`, `pix.paid` | Data/hora da efetivação do crédito na conta no formato ISO 8601. | | `payment_method` | `string` / `object` | `boleto.paid`, `pix.paid` (string) / `created`, `pix.created`, `updated`, `assign` (object) | Em `boleto.paid` e `pix.paid`, informa `"boleto"` ou `"pix"`. Nos demais eventos, contém o objeto com datas e instruções de cobrança. | | `reference_id` | `string` | `created`, `pix.created`, `registered`, `failed`, `updated`, `canceled`, `pix.paid` | Identificador externo de conciliação enviado pelo parceiro. | | `tags` | `array` | `created`, `pix.created`, `registered`, `failed`, `updated`, `canceled` | Lista de etiquetas associadas à cobrança. | | `linha_cod_barras` | `string` | `created`, `registered`, `updated` | Código de barras numérico de 44 dígitos. | | `linha_digitavel` | `string` | `created`, `registered`, `updated` | Linha digitável formatada do boleto. | | `emv` | `string` | `created`, `pix.created`, `registered`, `updated` | Código Pix Copia e Cola (EMV). | | `qrcode` / `imagem` | `string` | `pix.created` (`qrcode`) / `boleto.*` (`imagem`) | Imagem do QR Code Pix em formato Base64. | | `error` | `string` | `boleto.failed` | Mensagem descritiva do erro ou motivo de rejeição bancária. | | `updated_at` | `string` | `registered`, `failed`, `canceled` | Data/hora da última atualização de status (ISO 8601). | --- # Apêndice B: Especificação Detalhada da API Pix # Documentação Completa da API Pix (LURI v2) A API v2 da LURI disponibiliza a rota `/v2/charge/pix` para a geração, consulta e gerenciamento de cobranças **Pix**. O serviço contempla o QR Code **Estático (`static`)**, Pix **Dinâmico (`cob` - Cobrança Imediata)** e Pix **Cobrança com Vencimento (`cobv`)**. --- ## 1. Visão Geral e Recursos - **Endpoint Único e Auto-Detecção**: O endpoint `POST /v2/charge/pix` analisa os atributos informados no payload para identificar automaticamente se a solicitação trata-se de um Pix **Estático**, **Dinâmico (COB)** ou **Cobrança com Vencimento (COBV)**. - **Convenção Unificada de Valores ("Centavos")**: Todos os valores monetários e percentuais da API (como `amount`, `late_fee_amount`, `late_fee_percentage`, `interest_amount`, `interest_percentage`, `abatement_amount` e `discount[].amount`) devem ser enviados como **inteiros representando duas casas decimais** (sem ponto ou vírgula). Exemplo: `15000` = R$ 150,00; `200` = R$ 2,00 ou 2,00%; `100` = R$ 1,00 ou 1,00%. - **Provisionamento e Cache Automático de Chaves Pix**: O sistema verifica se o estabelecimento vendedor (`seller`) possui uma chave Pix cadastrada. Se não houver, a chave é obtida ou gerada automaticamente e salva em cache para garantir performance máxima. - **Suporte a Idempotência**: Requisições de mutação aceitam o cabeçalho `IdempotencyKey` (UUID) para evitar duplicidade de cobranças em cenários de re-tentativa por instabilidade de rede. - **Integração a Webhooks**: Quando o pagamento do Pix é confirmado pela rede bancária, um evento de webhook é automaticamente enviado para a URL cadastrada no seu marketplace. > **Nota de Compatibilidade (Legado):** Formatos anteriores de parâmetros (como `discount_percentage` e `discount_limit_date` diretamente em `billing_instructions`) permanecem 100% funcionais por retrocompatibilidade. Para novas integrações, utilize a estrutura padronizada documentada abaixo. --- ## 2. Autenticação e Rotas Todas as requisições para a API Pix exigem autenticação via **JWT (Bearer Token)** assinado com algoritmo RS256 ou **Basic Auth** com o Token no campo `username`. | Método | Endpoint | Autenticação | Descrição | | :--- | :--- | :--- | :--- | | `POST` | `/v2/charge/pix` | Basic Auth / JWT | Criação de cobrança Pix (`static`, `cob` ou `cobv`) | | `GET` | `/v2/charge/pix/{id}` | Basic Auth / JWT | Consulta de uma cobrança Pix por ID (`id_pix`) ou `txid` | | `GET` | `/v2/charge/pix/{id}/payments` | Basic Auth / JWT | Consulta de detalhes de pagamentos e devoluções do QR Code no liquidante com conciliação ativa | | `GET` | `/v2/charge/pix/{id}/history` | Basic Auth / JWT | Histórico de eventos da cobrança Pix | | `GET` | `/v2/charge/pix` | Basic Auth / JWT | Listagem paginada de cobranças Pix com filtros | | `GET` | `/v2/charge/pix/all` | Basic Auth / JWT | Consulta consolidada de cobranças Pix diretamente no liquidante | --- ## 3. Regras de Auto-Detecção da Modalidade Pix ``` POST /v2/charge/pix │ ┌───────────────────┴───────────────────┐ ▼ ▼ `payment_type` == "static"? Possui `customer` E │ `payment_method.expiration_date`? SIM ───┴─── NÃO │ │ │ SIM ───┴─── NÃO ▼ │ │ │ [ESTÁTICO] └───────────────────────────► ▼ (QR Code Fixo) ▼ [COB] [COBV] (Dinâmico (Vencimento) Imediato) ``` 1. **Cobrança com Vencimento (`cobv`)**: - **Critério**: O campo `payment_method.expiration_date` está preenchido (`>= hoje`) **E** os dados do pagador (`customer` com `taxpayer_id` e `name`) foram informados (ou `payment_type: "cobv"`). - **Data Limite (`payment_limit_date`)**: Opcional. Caso omitida, assume automaticamente `expiration_date + 90 dias`. - **Instruções Financeiras (`billing_instructions`)**: Aceita multa (`late_fee_amount` ou `late_fee_percentage`), juros (`interest_amount` ou `interest_percentage`), descontos (`discount`) e abatimento (`abatement_amount`), todos representados como inteiros em "centavos" (2 casas decimais). 2. **Cobrança Dinâmica / Imediata (`cob`)**: - **Critério**: Padrão quando `expiration_date` não é informado (ou `payment_type: "cob"`). - **Opções em `payment_method`**: - `expiration_seconds` (int, opcional): Tempo de expiração em segundos (`1` a `86400`, padrão `86400` = 24h). - `allow_amount_change` (bool, opcional): Permite que o pagador altere o valor na leitura (padrão `false`). - `payer_request` / `description` (string, opcional): Texto exibido ao pagador no momento da leitura do QR Code. - `additional_info` (objeto `{ "name": "...", "value": "..." }`, opcional): Campo adicional exibido no comprovante. 3. **QR Code Estático (`static`)**: - **Critério**: Quando `payment_type` é definido como `"static"`. --- ## 4. Referência de Campos (`POST /v2/charge/pix`) | Campo | Tipo | Obrigatório | Descrição | | :--- | :--- | :--- | :--- | | `seller` | `string` | Sim | Identificador (`seller_id`) do estabelecimento recebedor. | | `amount` | `integer` | Sim | Valor nominal da cobrança em centavos (mínimo `100` = R$ 1,00). | | `reference_id` | `string` | Não | Identificador externo de conciliação do parceiro. | | `installment` | `object` | Não | Objeto de identificação da parcela da venda (`{ "number": 1, "total": 12 }`). | | `installment.number` | `integer` | Condicional | Número da parcela atual (`>= 1` e `<= installment.total`; obrigatório se `installment` for enviado). | | `installment.total` | `integer` | Condicional | Quantidade total de parcelas da venda (`>= 1`; obrigatório se `installment` for enviado). | | `payment_type` | `string` | Não | Força a modalidade: `"cobv"`, `"cob"` ou `"static"`. | | `tags` | `array` | Não | Lista de strings para categorização da cobrança. | | `customer` | `object` | Condicional | Obrigatório para `cobv`, opcional para `cob`. Contém `taxpayer_id` (CPF/CNPJ) e `name` (além de endereço/contato opcionais). | | `payment_method.expiration_date` | `string` | Condicional | Data de vencimento (`YYYY-MM-DD`). Obrigatório para `cobv`. | | `payment_method.payment_limit_date` | `string` | Não | Data limite para pagamento após vencimento (`YYYY-MM-DD`). Padrão: `+90 dias` após `expiration_date`. | | `payment_method.expiration_seconds` | `integer` | Não | Expiração em segundos para `cob` (`1` a `86400`, padrão `86400`). | | `payment_method.allow_amount_change` | `boolean` | Não | Permite alteração do valor pelo pagador no `cob` (padrão `false`). | | `payment_method.billing_instructions.late_fee_amount` | `integer` | Não | Multa fixa em centavos (ex: `200` = R$ 2,00). Mutuamente exclusivo com `late_fee_percentage`. | | `payment_method.billing_instructions.late_fee_percentage` | `integer` | Não | Multa percentual em base centesimal (ex: `200` = 2,00%). Máx: `10000` (100,00%). | | `payment_method.billing_instructions.late_fee_date` | `string` | Não | Data de início da multa (`YYYY-MM-DD`, `> expiration_date`). Padrão: `expiration_date + 1 dia`. | | `payment_method.billing_instructions.interest_amount` | `integer` | Não | Juros em valor fixo por dia em centavos (ex: `100` = R$ 1,00/dia). Mutuamente exclusivo com `interest_percentage`. | | `payment_method.billing_instructions.interest_percentage` | `integer` | Não | Juros percentual em base centesimal (ex: `100` = 1,00%). | | `payment_method.billing_instructions.interest_mode` | `string` | Não | Modalidade de apuração dos juros no `cobv`: `"amount_calendar_days"` (Valor por dia corrido — padrão para `interest_amount`, BMP tipo `1`), `"amount_business_days"` (Valor por dia útil, BMP tipo `6`), `"percentage_daily"` (Percentual ao dia corrido, BMP tipo `2`), `"percentage_monthly"` (Percentual ao mês em dias corridos — padrão para `interest_percentage`, BMP tipo `3`), `"percentage_monthly_business"` (Percentual ao mês em dias úteis, BMP tipo `8`) ou `"exempt"` (Isento, BMP tipo `5`). | | `payment_method.billing_instructions.interest_date` | `string` | Não | Data de início dos juros (`YYYY-MM-DD`, `> expiration_date`). Padrão: `expiration_date + 1 dia`. | | `payment_method.billing_instructions.abatement_amount` | `integer` | Não | Valor de abatimento em centavos (ex: `500` = R$ 5,00). | | `payment_method.billing_instructions.discount` | `array` | Não | Array de descontos (`[{ "limit_date": "YYYY-MM-DD", "mode": "...", "amount": 500 }]`). Modos suportados em `mode`: `"fixed"` (Valor fixo até a data — BMP tipo `1`), `"percentage"` (Percentual até a data — BMP tipo `2`), `"anticipation_fixed_calendar"` (Valor por dia corrido de antecipação — BMP tipo `3`), `"anticipation_fixed_business"` (Valor por dia útil de antecipação — BMP tipo `4`), `"anticipation_percentage_calendar"` (Percentual por dia corrido de antecipação — BMP tipo `5`), `"anticipation_percentage_business"` (Percentual por dia útil de antecipação — BMP tipo `6`) e `"exempt"` (Isento — BMP tipo `0`). O campo `amount` segue a convenção em centavos (`500` = R$ 5,00 ou 5,00%). | --- ## 5. Exemplos de Integração ### 5.1. Criar Cobrança Pix (`POST /v2/charge/pix`) #### Exemplo A: Pix Cobrança com Vencimento (`cobv`) **Requisição (`POST /v2/charge/pix`):** ```json { "seller": "9519f68914bb40359a045ec8a142b75f", "amount": 15000, "reference_id": "PEDIDO-2026-001", "installment": { "number": 1, "total": 12 }, "tags": [ "Venda Online", "Plano Anual" ], "customer": { "taxpayer_id": "36160560042", "name": "Maria Oliveira", "email": "maria@exemplo.com", "phone_number": "11999887766", "street_line": "Av. Paulista, 1000", "street_line2": "Conjunto 42", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "postal_code": "01310100" }, "payment_method": { "expiration_date": "2026-12-31", "payment_limit_date": "2027-03-31", "billing_instructions": { "late_fee_percentage": 200, "interest_percentage": 100, "abatement_amount": 500, "discount": [ { "limit_date": "2026-12-20", "mode": "percentage", "amount": 500 } ] } } } ``` **Resposta (`200 OK`):** ```json { "id_pix": "f8a9e1d2-3c4b-5a6f-7e8d-9c0b1a2f3e4d", "txid": "7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b", "modality": "cobv", "status": "registered", "amount": 15000, "reference_id": "PEDIDO-2026-001", "installment": { "number": 1, "total": 12 }, "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b5204000053039865405150.005802BR5915ESTABELECIMENTO6009SAO PAULO62070503***6304A1B2", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "12345678000195", "name": "Loja Exemplo LTDA", "chave_pix": "02a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" }, "customer": { "taxpayer_id": "36160560042", "name": "Maria Oliveira", "email": "maria@exemplo.com", "phone_number": "11999887766", "street_line": "Av. Paulista, 1000", "street_line2": "Conjunto 42", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "postal_code": "01310100" }, "payment_method": { "expiration_date": "2026-12-31", "payment_limit_date": "2027-03-31", "billing_instructions": { "late_fee_percentage": 200, "interest_percentage": 100, "abatement_amount": 500, "discount": [ { "limit_date": "2026-12-20", "mode": "percentage", "amount": 500 } ] } }, "created_at": "2026-08-14T08:30:00-03:00" } ``` --- #### Exemplo B: Pix Dinâmico COB (Cobrança Imediata) **Requisição (`POST /v2/charge/pix`):** ```json { "seller": "9519f68914bb40359a045ec8a142b75f", "amount": 5000, "reference_id": "PIX-IMEDIATO-123", "payment_method": { "expiration_seconds": 3600, "payer_request": "Pagamento do Pedido #123" } } ``` **Resposta (`200 OK`):** ```json { "id_pix": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "txid": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d", "modality": "cob", "status": "registered", "amount": 5000, "reference_id": "PIX-IMEDIATO-123", "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cob/9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d520400005303986540550.005802BR5915ESTABELECIMENTO6009SAO PAULO62070503***6304C3D4", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "12345678000195", "name": "Loja Exemplo LTDA", "chave_pix": "02a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" }, "payment_method": { "expiration_seconds": 3600, "payer_request": "Pagamento do Pedido #123" }, "created_at": "2026-08-14T08:31:00-03:00" } ``` --- #### Exemplo C: Pix Estático (QR Code Fixo/Estático) **Requisição (`POST /v2/charge/pix`):** ```json { "seller": "9519f68914bb40359a045ec8a142b75f", "amount": 2500, "reference_id": "BALCAO-001", "payment_type": "static" } ``` **Resposta (`200 OK`):** ```json { "id_pix": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e", "txid": "a1b2c3d4e5f60123456789ab", "modality": "static", "status": "registered", "amount": 2500, "reference_id": "BALCAO-001", "emv": "00020101021126580014br.gov.bcb.pix013602a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c520400005303986540525.005802BR5915ESTABELECIMENTO6009SAO PAULO62070503***6304E5F6", "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...", "seller": { "seller_id": "9519f68914bb40359a045ec8a142b75f", "taxpayer_id": "12345678000195", "name": "Loja Exemplo LTDA", "chave_pix": "02a9b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" }, "created_at": "2026-08-14T08:32:00-03:00" } ``` --- ### 5.2. Buscar Cobrança Pix (`GET /v2/charge/pix/{id}`) - `{id}`: Identificador único (`id_pix`) ou o `txid` da cobrança. ### 5.3. Listar Cobranças Pix (`GET /v2/charge/pix`) #### Parâmetros da Query String (Filtros) - `seller_id` (string): Filtrar por hash do vendedor. - `seller_ein` (string): Filtrar por CPF/CNPJ do vendedor. - `reference_id` (string): Filtrar por referência externa. - `txid` (string): Filtrar pelo identificador de transação Pix. - `status` (string): Status da cobrança (`created`, `registered`, `paid`, `canceled`). - `created_date_gte` / `created_date_lte` (string): Período de criação (`YYYY-MM-DD`). - `updated_date_gte` / `updated_date_lte` (string): Período de atualização (`YYYY-MM-DD`). - `page` (int): Número da página desejada (padrão: `1`). - `limit` (int): Quantidade de itens por página (máximo: `300`). ### 5.4. Consultar Todos os Pix no Liquidante (`GET /v2/charge/pix/all`) Permite consultar diretamente na instituição liquidante as cobranças Pix dinâmicas emitidas para um determinado `seller_id`. #### Parâmetros da Query String - `seller_id` (string, **obrigatório**): Hash identificador do seller. - `start_date` / `end_date` (string, opcionais): Filtro de período (`YYYY-MM-DD`). - `status` (string, opcional): Filtro de status. - `page` / `limit` (int, opcionais): Paginação. --- ### 5.5. Consultar Detalhes de Pagamento e Conciliação Ativa de QR Code (`GET /v2/charge/pix/{id}/payments`) Consulta diretamente na instituição liquidante (BMP `GET /api/v2/QRCode/{codigoQRCode}/DetalhesPagamento`) todos os pagamentos recebidos para o QR Code da cobrança (`e2e_id` / `numeroOperacao`, `receipt_id` / `codigoRecebimento`, `movement_id` / `codigoMovimento`, `amount`, `payment_date`) e eventuais devoluções (`refunds`). - **Conciliação Ativa Automática (Fallback)**: Caso a cobrança esteja com status diferente de `paid` na base local mas a instituição liquidante retorne pagamento confirmado para o QR Code, a API concilia automaticamente o título para `status: "paid"`, grava o histórico e enfileira o webhook `pix.paid` (caso ainda não tenha sido entregue). Para apenas consultar sem conciliar, envie `?reconcile=false`. **Resposta (`200 OK`):** ```json { "id_pix": "f8a9e1d2-3c4b-5a6f-7e8d-9c0b1a2f3e4d", "txid": "7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b", "codigo_qrcode": "b1c2d3e4-f5a6-4789-8a9b-0c1d2e3f4a5b", "status": "paid", "reconciled": true, "total_payments": 1, "total_paid_amount": 15000, "total_refunded_amount": 0, "payments": [ { "e2e_id": "E1337083520261108172030123456789", "receipt_id": "f1e2d3c4-b5a6-4987-8c9d-0e1f2a3b4c5d", "movement_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "txid": "7c9e1b2a3f4d5e6f7a8b9c0d1e2f3a4b", "amount": 15000, "payment_date": "2026-11-08T14:20:30", "refunds": [] } ] } ``` --- ## 6. Eventos de Webhook do Pix As cobranças criadas em `/v2/charge/pix` disparam automaticamente os seguintes eventos para o webhook configurado no seu marketplace (consulte `WEBHOOKS.md` para detalhes completos): - **`pix.created`**: Disparado imediatamente após o registro da cobrança em `POST /v2/charge/pix` (`status: "registered"`), contendo `id_pix`, `txid`, `modality` (`static`, `cob`, `cobv`), `amount`, `reference_id`, `emv`, `qrcode` e `payment_method`. - **`pix.paid`**: Disparado quando o pagamento do Pix puro é confirmado (`status: "paid"`), contendo `id_pix`, `txid`, `e2e_id` (`NumeroOperacao`), `movement_id` (`CodigoMovimento`), `transaction_id` (`CodigoTransacao`), `amount`, `total_amount`, `interest`, `discount`, `payment_date`, `credit_date` e `payer` (dados do pagador). --- # Apêndice C: Especificação Detalhada de Chaves Públicas RSA (JWT RS256) # Gerenciamento de Chaves Públicas Assimétricas (API v2) Documentação técnica oficial para cadastro, listagem, revogação e rotação segura de **Chaves Públicas Assimétricas (RSA / RS256)** utilizadas na autenticação JWT B2B da **LURI**. --- ## 1. Visão Geral e Princípios de Segurança A autenticação assimétrica RS256 elimina a necessidade de trafegar credenciais estáticas nas requisições da API. O cliente assina seus tokens JWT com sua **Chave Privada** e a LURI valida a assinatura utilizando a correspondente **Chave Pública** cadastrada previamente. ### Diretrizes e Regras Gerais - **Escopo Exclusivo**: Todas as rotas estão centralizadas exclusivamente em `/v2/auth/public-keys`. - **Canal Seguro Obrigatório**: Conexão obrigatória via HTTPS com **TLS 1.2 ou superior**. Requisições em canal inseguro são rejeitadas com `HTTP 403 Forbidden`. - **Formato Aceito**: Exclusivamente **PEM** (`-----BEGIN PUBLIC KEY-----` ou `-----BEGIN RSA PUBLIC KEY-----`). - **Força Criptográfica**: Exige algoritmo **RSA** com tamanho mínimo de **2048 bits**. - **Bloqueio Sumário de Chaves Privadas**: O cofre da LURI rejeita imediatamente requisições que contenham chaves privadas (`BEGIN PRIVATE KEY`, `BEGIN RSA PRIVATE KEY`, etc.) com `HTTP 400 Bad Request`. - **Retrocompatibilidade Ativa**: Chaves legadas presentes na coluna `public_key` da tabela `api_boleto_marketplace` permanecem **100% ativas e funcionais** (identificadas na listagem com o KID `legacy-default`). - **Notificações em Tempo Real**: Cada evento de criação ou revogação dispara notificações de segurança via **Webhook** para a URL configurada no marketplace. --- ## 2. Matriz de Endpoints e Autenticação | Método | Rota | Método de Autenticação | Descrição | | :--- | :--- | :--- | :--- | | **POST** | `/v2/auth/public-keys` | **Basic Auth** | Cadastra uma nova chave pública RSA (2048+ bits). | | **GET** | `/v2/auth/public-keys` | **JWT** (`Bearer `) | Lista todas as chaves cadastradas (ativas, revogadas e legadas). | | **DELETE** | `/v2/auth/public-keys/{kid}` | **JWT** (`Bearer `) | Revoga uma chave pública (exige chave diferente para autorizar). | --- ## 3. Especificação Detalhada das Chamadas ### 3.1. Cadastrar Chave Pública Cadastra uma nova chave pública PEM associada à conta do marketplace. - **Rota**: `POST /v2/auth/public-keys` - **Canal**: HTTPS (TLS 1.2+) - **Autenticação**: **Basic Auth** - Username: `{secret_marketplace}` (token/credencial do marketplace) - Password: em branco - Cabeçalho HTTP: `Authorization: Basic {base64(secret_marketplace:)}` - **Content-Type**: `application/json` #### Parâmetros do Payload (JSON) | Campo | Tipo | Obrigatório | Descrição | | :--- | :--- | :--- | :--- | | `public_key` | `string` | **Sim** | Conteúdo da chave pública no formato PEM. | | `kid` | `string` | Não | Identificador único da chave (de 3 a 128 caracteres: alfanuméricos, hífen, underline ou ponto). Se omitido, a LURI gerará um `kid` seguro automaticamente. | #### Exemplo de Requisição (cURL) ```bash curl -X POST "https://api.luri.io/v2/auth/public-keys" \ -H "Authorization: Basic YWJjMTIzNDU2Nzg5MA==" \ -H "Content-Type: application/json" \ -d '{ "kid": "prod-key-2026-v1", "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyQKhZOSn8W/7x+is46OV\nJxiX30yXg79OWUicGOZkbC7GXjZ5UEIN8Xqo0GfXsiEOcz5L5RsJ7jGxTU3Niuu0\nVf1QHJek9vY+pGuPRKK4sVEWESK7CmX7n0jGqvXIgLBpSTXfjurkys2pkvaZGPlq\nyxrEbYf4pQApB8+HoxMHVZ2xBd/0Cb3sXQGoSaHL9qhVtRCegNYAk3crNySrBiVb\ncgZz0pImQ+FIgmpn+pG147fFCY7PeeBv1rQ65ibOJ+X1GG7uCBGPNk/tl+0kPt0n\nE21hX4OjxQaYZPNkkahSFLkDXP8wGtQBzsxGyAIowR845Q5QLg6KCyPEh3d0mE9N\nAgMBAAE=\n-----END PUBLIC KEY-----" }' ``` #### Exemplo de Resposta de Sucesso (`HTTP 201 Created`) ```json { "success": true, "message": "Chave pública cadastrada com sucesso.", "data": { "kid": "prod-key-2026-v1", "algorithm": "RS256", "key_type": "RSA", "key_size": 2048, "fingerprint_sha256": "4b68e982d6fc5732c4d622955f269389e1b2123d24268e3b5df51a84f506ee4f", "status": "active", "created_at": "2026-10-23T16:30:00Z" } } ``` --- ### 3.2. Listar Chaves Públicas Retorna a relação de todas as chaves públicas (ativas, revogadas e chaves legadas) vinculadas ao marketplace emissor do token JWT. - **Rota**: `GET /v2/auth/public-keys` - **Canal**: HTTPS (TLS 1.2+) - **Autenticação**: **Obrigatoriamente JWT** - Cabeçalho HTTP: `Authorization: Bearer ` - *(Requisições com Basic Auth ou sem cabeçalho Authorization são rejeitadas com HTTP 401).* #### Exemplo de Requisição (cURL) ```bash curl -X GET "https://api.luri.io/v2/auth/public-keys" \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ``` #### Exemplo de Resposta de Sucesso (`HTTP 200 OK`) ```json { "success": true, "data": [ { "kid": "prod-key-2026-v2", "algorithm": "RS256", "key_type": "RSA", "key_size": 2048, "fingerprint_sha256": "4b68e982d6fc5732c4d622955f269389e1b2123d24268e3b5df51a84f506ee4f", "is_legacy": false, "status": "active", "created_at": "2026-10-23T16:30:00Z", "revoked_at": null, "last_used_at": "2026-10-23T16:35:10Z" }, { "kid": "prod-key-2026-v1", "algorithm": "RS256", "key_type": "RSA", "key_size": 2048, "fingerprint_sha256": "8a7c293817498127394872938471923847192837491827394817293847192837", "is_legacy": false, "status": "revoked", "created_at": "2026-09-01T10:00:00Z", "revoked_at": "2026-10-23T16:20:00Z", "last_used_at": "2026-10-23T16:19:40Z" }, { "kid": "legacy-default", "algorithm": "RS256", "key_type": "RSA", "key_size": 2048, "fingerprint_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "is_legacy": true, "status": "active", "created_at": null, "revoked_at": null, "last_used_at": null } ] } ``` --- ### 3.3. Revogar Chave Pública (Key Revocation) Invalida logicamente uma chave pública, bloqueando instantaneamente qualquer autenticação futura assinada por ela. - **Rota**: `DELETE /v2/auth/public-keys/{kid}` - **Canal**: HTTPS (TLS 1.2+) - **Autenticação**: **Obrigatoriamente JWT** - Cabeçalho HTTP: `Authorization: Bearer ` > [!IMPORTANT] > **Regra Crítica de Segurança na Rotação (Anti-Lockout)** > O token JWT utilizado para autorizar a requisição de revogação **NÃO** pode ter sido assinado com a mesma chave (`kid`) que está sendo excluída! > Se você tentar revogar o mesmo `kid` com o qual assinou a chamada, o sistema rejeitará a operação com **HTTP 403 Forbidden**. > > **Fluxo de Rotação sem Downtime (Zero Downtime Rotation)**: > 1. Cadastre a chave pública nova via `POST /v2/auth/public-keys`. > 2. No seu backend, passe a assinar suas requisições com a nova chave privada (enviando o novo `kid` no cabeçalho JWT). > 3. Dispare a requisição `DELETE /v2/auth/public-keys/{kid_antigo}` utilizando o JWT assinado com a chave nova. #### Exemplo de Requisição (cURL) ```bash curl -X DELETE "https://api.luri.io/v2/auth/public-keys/prod-key-2026-v1" \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ``` #### Exemplo de Resposta de Sucesso (`HTTP 200 OK`) ```json { "success": true, "message": "Chave pública revogada com sucesso. Tokens futuros assinados com este kid serão rejeitados.", "data": { "kid": "prod-key-2026-v1", "status": "revoked", "revoked_at": "2026-10-23T16:40:00Z" } } ``` #### Exemplo de Bloqueio por Auto-Revogação (`HTTP 403 Forbidden`) ```json { "status": "Forbidden", "status_code": 403, "message": "Operação não permitida: Não é permitido revogar a mesma chave pública ('prod-key-2026-v1') utilizada para assinar o token desta requisição. Realize a rotação utilizando outra chave ativa." } ``` --- ## 4. Como Utilizar o `kid` nas Requisições JWT Quando o seu sistema emitir um JWT para autenticação em qualquer endpoint da API v2 (ex: pagamentos, consultas de saldo, conciliações), inclua o `kid` no cabeçalho do token: ### 1. Cabeçalho (Header) do Token ```json { "alg": "RS256", "typ": "JWT", "kid": "prod-key-2026-v1" } ``` ### 2. Corpo (Payload) do Token ```json { "iss": "4b7e010c54a048efab973279355dbc51", "iat": 1713361200, "exp": 1713361500 } ``` ### Como a LURI Valida: 1. Extrai o `iss` (`hash_marketplace`) do payload e o `kid` do cabeçalho. 2. Localiza no cofre a chave pública ativa correspondente àquele par `(hash_marketplace, kid)`. 3. Valida a integridade da assinatura matemática (RS256). 4. Se o `kid` for omitido (tokens legados), o validador utiliza a chave pública configurada na coluna legada `api_boleto_marketplace.public_key` ou a chave ativa mais recente. --- ## 5. Notificações de Segurança via Webhook Sempre que uma chave pública for cadastrada ou revogada, a LURI dispara um evento HTTP POST seguro para a `url_webhook` configurada no marketplace. ### Estrutura do Payload Enviado ```json { "event": "public_key.created", "request_id": "req_a1b2c3d4e5f67890", "timestamp": "2026-10-23T16:30:00Z", "data": { "hash_marketplace": "4b7e010c54a048efab973279355dbc51", "kid": "prod-key-2026-v1", "algorithm": "RS256", "key_size": 2048, "fingerprint_sha256": "4b68e982d6fc5732c4d622955f269389e1b2123d24268e3b5df51a84f506ee4f", "status": "active", "created_at": "2026-10-23T16:30:00Z", "ip_address": "177.18.25.10" } } ``` #### Eventos Possíveis: - `public_key.created`: Emitido imediatamente após o cadastro de uma nova credencial assimétrica. - `public_key.revoked`: Emitido imediatamente após a revogação de uma credencial existente. --- ## 6. Tabela de Códigos de Retorno e Diagnóstico | Código HTTP | Causa Provável | Ação Recomendada | | :--- | :--- | :--- | | **200 OK** | Operação realizada com sucesso (Listagem ou Revogação). | — | | **201 Created** | Chave pública cadastrada com sucesso. | Armazene o `kid` retornado para envio nos cabeçalhos JWT. | | **400 Bad Request** | Formato de chave PEM inválido, chave fraca (< 2048 bits) ou chave privada enviada. | Verifique se você enviou apenas a chave pública (`BEGIN PUBLIC KEY`) e se ela possui no mínimo 2048 bits RSA. | | **401 Unauthorized** | Falha no Basic Auth (ao cadastrar) ou JWT ausente/inválido (ao listar/revogar). | Confirme as credenciais enviadas no cabeçalho `Authorization`. | | **403 Forbidden** | Conexão sem HTTPS/TLS 1.2+ ou tentativa de auto-revogação da mesma chave do token. | Conecte via HTTPS e use outra chave ativa para assinar o token de revogação. | | **404 Not Found** | O `kid` informado para exclusão não foi encontrado para este marketplace. | Liste as chaves via `GET /v2/auth/public-keys` para confirmar os identificadores existentes. | | **409 Conflict** | Já existe uma chave ativa ou revogada com este mesmo `kid`. | Utilize um novo `kid` único ou deixe em branco para auto-geração. |