# Breaking Changes ## Informações gerais Este documento descreve todas as mudanças na API que requerem adequação dos consumidores. Destinado ao time de desenvolvimento do app mobile e a todos os parceiros integrados via API. Cada seção lista os campos renomeados, removidos e adicionados por endpoint. As tabelas comparam o comportamento da versão atual com a nova versão. A coluna "Ação" indica o que o consumidor precisa fazer para se adequar. As etiquetas `APP` `PARTNER` `API` ao lado de cada endpoint indicam quais tipos de cliente podem acessá-lo conforme a política de autorização (ActionPolicy). ## Saldo `GET /accounts/balance` `APP` `PARTNER` `API` ### Campos adicionados | Campo | Descrição | | ------------------- | ----------------------------------------------------------------------------- | | `available_balance` | Saldo disponível (current_balance - blocked_balance) em centavos — novo campo | ### Alterações | Versão atual | Nova versão | Ação | | -------------------- | ----------------------------- | -------------------------- | | `last_update` em UTC | `last_update` em BRT (-03:00) | Verificar parsing de datas | ## Extrato `GET /accounts/statement` `APP` `PARTNER` `API` ### Campos renomeados | Versão atual | Nova versão | Ação | | ------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- | | `transaction_id` | `id` | Atualizar referência | | `transaction_date` | `occurred_at` | Atualizar referência; agora em BRT (-03:00) em vez de UTC | | `transaction_type` (number) | `type` (string enum: PIX, BANK_SLIP, TED, INTERNAL_TRANSFER) | Atualizar mapeamento | | `debit_credit` ("C"/"D") | `direction` (CREDIT/DEBIT) | Atualizar mapeamento | | `balance` | `end_of_day_balance` | Atualizar referência (saldo ao fim do dia) | | `nsu` (number) | `nsu` (string) | Tratar como string | | `pix_qrcode` (string "true") | `is_pix_qr_code` (boolean) | Atualizar referência e tipo | | `transaction_description` | `operation_description` | Renomeado — descrição da operação gerada pelo sistema | | `client_operation_id` | `reference_id` | Atualizar referência | | `client_description` | `description` | Renomeado — texto livre do cliente | | `from_name` / `to_name` | `counterparty_name` | Usar campo unificado | | `to_document` | `counterparty_document` | Atualizar referência | | `from_bank_code` | `counterparty_bank_code` | Atualizar referência | | `from_branch_code` | `counterparty_branch_code` | Atualizar referência | | `from_account_number` / `to_account_number` | `counterparty_account_number` | Usar campo unificado | ### Campos removidos | Campo | Ação | | -------------------------------- | ------------------------------------------------ | | `transaction_code` | Removido; usar `id` ou `provider_transaction_id` | | `transaction_identifier` | Removido | | `transaction_type_code` (number) | Removido; usar `type` (string) | | `movement_code` | Removido | | `complement` | Removido | ### Campos adicionados | Campo | Descrição | | ----------------------------------------------------------- | ------------------------------------------------------- | | `status` (PENDING, PROCESSING, COMPLETED, FAILED, REVERSED) | Usar na exibição | | `fee_amount` | Valor da tarifa (opcional) | | `provider_transaction_id` | ID da transação na instituição financeira (informativo) | | `provider_movement_id` | ID do movimento na instituição financeira (informativo) | | `end_to_end_id` | ID ponta a ponta Pix BACEN (opcional) | | `control_number` | Número de controle (opcional) | | `page_info` (objeto com `has_next_page` e `next_cursor`) | Paginação cursor-based (quando há mais páginas) | ### Query params alterados (Entrega 5) Os filtros do extrato foram padronizados ao formato BACEN / Open Banking Brasil. | Parâmetro atual | Novo parâmetro | Ação | | ------------------- | ----------------------------------------- | -------------------------------------------- | | `year` (number) | **Removido** | Usar `start_date` | | `month` (number) | **Removido** | Usar `start_date` | | `from_day` (number) | **Removido** | Usar `start_date` | | `to_day` (number) | **Removido** | Usar `end_date` | | — | `start_date` (ISO 8601, ex: 2026-05-01) | **Novo** — data inicial do período | | — | `end_date` (ISO 8601, ex: 2026-05-23) | **Novo** — data final do período | | — | `types[]` (PIX, TED, TEF, BANK_SLIP, FEE) | **Novo** — filtro por tipo (opcional) | | — | `directions[]` (CREDIT, DEBIT) | **Novo** — filtro por direção (opcional) | | — | `cursor` (string) | **Novo** — paginação cursor-based (opcional) | | — | `limit` (number, default 100, max 500) | **Novo** — quantidade por página (opcional) | **Exemplo:** ``` # Antes GET /accounts/statement?year=2026&month=5&from_day=1&to_day=23 # Depois GET /accounts/statement?start_date=2026-05-01&end_date=2026-05-23 GET /accounts/statement?start_date=2026-05-01&end_date=2026-05-23&types=PIX&directions=CREDIT&limit=50 ``` ### Semântica do período e da ordenação (data econômica) O extrato passou a filtrar e ordenar pela **data econômica** da transação (`processed_at` — liquidação no provider), não mais pela data de criação interna (`created_at`). Os efeitos: - `start_date`/`end_date` selecionam o intervalo pela data econômica (extrato bancário por data de liquidação, padrão de mercado). - As transações vêm ordenadas por `processed_at` (decrescente) — o `running_balance` "fecha" linha a linha, mesmo quando um webhook econômica-antigo chega atrasado. - O extrato lista **apenas transações concluídas** (COMPLETED). Pendentes/em processamento não aparecem no extrato (não têm saldo nem data de liquidação). - O `cursor` de paginação agora é ancorado em `processed_at`. Cursores emitidos antes da virada não devem ser reutilizados após o deploy (reinicie a paginação). No caminho feliz (webhook em tempo real) `created_at ≈ processed_at`, então o resultado é praticamente idêntico ao anterior; a diferença aparece em transações com liquidação retroativa. ### Período deixou de ser obrigatório — e `start_date`/`end_date` da RESPOSTA passam a poder vir nulos `start_date` e `end_date` continuam funcionando exatamente como antes quando enviados. O que mudou é que **agora podem ser omitidos**: sem período, o extrato devolve as **últimas `limit` transações concluídas** da conta, independente de quando ocorreram, e a rolagem para o passado segue pelo `cursor`, igual. Motivação: numa conta parada há meses, a consulta por janela recente devolvia lista vazia e a tela abria em branco. | Parâmetro | Antes | Agora | | ------------------------- | ------------------------ | ----------------------------------------------------------------- | | `start_date` / `end_date` | **Obrigatórios** | **Opcionais — mas é AMBOS ou NENHUM** (só um dos dois → `400`) | ⚠️ **Ação para o consumidor — o único ponto que exige código novo:** os campos `start_date` e `end_date` **da resposta** passam a ser `string | null`. A chave continua sempre presente; o valor é nulo num caso só: consulta **sem** período **e** página vazia (conta sem nenhum movimento concluído). Cliente com desserialização estrita (`String` não-nulo) precisa relaxar esses dois campos. Quando há valor, ele significa: | Consulta | `start_date` / `end_date` da resposta | | -------------- | ------------------------------------------------------------------------------ | | Com período | **Ecoam o período pedido** — comportamento inalterado | | Sem período | Derivados da **página**: data da transação mais antiga / mais recente devolvida | | Sem período, página vazia | `null` nos dois | ⚠️ **O export não mudou.** `GET /accounts/statement/export` continua **exigindo** `start_date` e `end_date`, com o teto de 90 dias e 10.000 transações — lá a janela é o que limita o lote, e não há cursor para substituí-la. **Exemplo:** ``` # Últimas 100 transações, sem filtro de data GET /accounts/statement # Últimas 50, ainda filtrando por tipo GET /accounts/statement?types=PIX&limit=50 # 400 — meio período não é aceito GET /accounts/statement?start_date=2026-05-01 ``` O mesmo vale para o extrato da superfície de backoffice (`GET /backoffice/accounts/{accountId}/statement`, consumido pelo BFF do painel), que serve o mesmo usecase. ## Comprovante `GET /accounts/transactions/:id/receipt` `APP` `PARTNER` `API` ### Campos renomeados | Versão atual | Nova versão | Ação | | --------------------------------------- | --------------------------- | ----------------------------------------- | | `transaction_id` | `id` | Atualizar referência | | `transaction_amount` | `amount` | Atualizar referência | | `transaction_date` / `sent_date` | `occurred_at` | Atualizar referência; agora em BRT | | `transaction_type` | `type` (string enum) | Atualizar mapeamento | | `authentication_code` | removido (usar `auth_code`) | Atualizar referência | | `due_amount` | `amount_due` | Padronização amount\_\* | | `description` (texto do sistema) | `operation_description` | Descrição da operação gerada pelo sistema | | Estrutura `from`/`to`: `owner_name` | `holder_name` | Atualizar referência | | Estrutura `from`/`to`: `owner_document` | `holder_document` | Atualizar referência | ### Campos removidos | Campo | Ação | | -------------------------------- | ------------------------------------------------------ | | `transaction_code` | Usar `provider_transaction_id` | | `movement_code` | Removido | | `operation_number` | Removido | | `transaction_type_code` (number) | Removido; usar `type` (string) | | `authentication_code` | Removido; usar `auth_code` | | `sent_date` | Removido; usar `occurred_at` | | `control_number` | Removido | ### Campos adicionados | Campo | Descrição | | -------------------------- | ------------------------------------------------------- | | `direction` (CREDIT/DEBIT) | Usar na exibição | | `status` (COMPLETED, etc.) | Usar na exibição | | `fee_amount` | Valor da tarifa (opcional) | | `provider_transaction_id` | ID da transação na instituição financeira (informativo) | | `provider_movement_id` | ID do movimento na instituição financeira (informativo) | | `end_to_end_id` | ID ponta a ponta Pix (opcional) | | `pix_key` | Chave Pix utilizada (opcional) | | `amount_due` | Valor devido do título (boleto, opcional) | | `due_date` | Data de vencimento (boleto, opcional) | | `digitable_line` | Linha digitável (boleto, opcional) | | `operation_description` | Descrição da operação gerada pelo sistema (opcional) | | `from`/`to`: `bank_ispb` | ISPB do banco separado de `bank_code` | | `from`/`to`: `bank_code` | Código COMPE do banco (agora preenchido corretamente) | | `nsu` | NSU — identificador único da operação | | `txid` | Identificador Pix (txid) | | `pix_key_type` | Tipo da chave Pix | | `refund_reason` | Motivo da devolução Pix | | `description` | Descrição livre informada pelo cliente | | `reference_id` | Referência de conciliação do cliente | | `interest_amount` | Juros pagos no boleto (centavos) | | `fine_amount` | Multa paga no boleto (centavos) | | `discount_amount` | Desconto aplicado no boleto (centavos) | | `rebate_amount` | Abatimento aplicado no boleto (centavos) | | `beneficiary_name` | Nome do cedente/beneficiário (boleto) — reintroduzido | | `beneficiary_document` | CPF/CNPJ do cedente/beneficiário (boleto) — reintroduzido | | `issuer_name` | Nome do emissor do boleto pago | | `issuer_document` | CPF/CNPJ do emissor do boleto pago | | `issuer_bank_code` | Código do banco do emissor do boleto pago | | `our_number` | Nosso número do boleto | | `document_number` | Número do documento do boleto | | `purpose_code` | Código de finalidade da TED/TEF | | `purpose_description` | Descrição legível da finalidade da TED/TEF | | `initiation_type` | Forma de iniciação do Pix | | `additional_info` | Mensagem do pagador (Pix) | | `return_detail` | Detalhe da devolução (TED) | | `reversal_of_id` | ID da transação original (em devoluções) | | `balance_after` | Saldo da conta após a transação (centavos) | ### Alteração de estrutura | Versão atual | Nova versão | Ação | | ------------------------------------- | ----------------------------------------- | -------------------------------- | | Objeto `from`/`to` com strings vazias | Omitido quando todos os campos são vazios | Tratar `from`/`to` como nullable | ## Detalhes `GET /accounts/transactions/:id/details` `APP` `PARTNER` `API` ### Campos renomeados | Versão atual | Nova versão | Ação | | -------------------------------- | ----------------------- | ----------------------------------------- | | `transaction_id` | `id` | Atualizar referência | | `transaction_amount` | `amount` | Atualizar referência | | `transaction_date` | `occurred_at` | Atualizar referência; agora em BRT | | `transaction_type` | `type` (string enum) | Atualizar mapeamento | | `description` (texto do sistema) | `operation_description` | Descrição da operação gerada pelo sistema | | `client_operation_id` | `reference_id` | Atualizar referência | | `client_description` | `description` | Texto livre do cliente | ### Campos removidos | Campo | Ação | | ------------------ | --------- | | `transaction_code` | Usar `id` | | `movement_code` | Removido | | `control_number` | Removido | ### Campos adicionados O `/details` é a visão completa da transação (independe do status). Além de `direction`, passa a expor os campos enriquecidos por tipo e a camada de ciclo de vida/auditoria. **Comuns** | Campo | Descrição | | -------------------------- | ------------------------------------------------------- | | `direction` (CREDIT/DEBIT) | Usar na exibição | | `status` | Status da transação | | `fee_amount` | Valor da tarifa (centavos, opcional) | | `auth_code` | Código de autorização | | `nsu` | NSU — identificador único da operação | | `counterparty_name` | Nome da contraparte | | `counterparty_document` | Documento da contraparte (CPF/CNPJ) | | `provider_transaction_id` | ID da transação na instituição financeira | | `provider_movement_id` | ID do movimento na instituição financeira | | `balance_after` | Saldo da conta após a transação (centavos) | **Pix** | Campo | Descrição | | ----------------------- | ---------------------------------- | | `end_to_end_id` | ID ponta a ponta Pix (BACEN) | | `pix_key` | Chave Pix utilizada | | `pix_key_type` | Tipo da chave Pix | | `operation_number` | Número da operação no SPI | | `txid` | Identificador da cobrança Pix | | `initiation_type` | Forma de iniciação do Pix | | `refund_reason` | Motivo da devolução Pix | | `rejection_reason` | Motivo da rejeição do Pix | | `rejection_description` | Descrição da rejeição do Pix | | `additional_info` | Mensagem do pagador | **Boleto** | Campo | Descrição | | -------------------- | ----------------------------------------------- | | `barcode` | Código de barras | | `digitable_line` | Linha digitável | | `due_date` | Data de vencimento (BRT) | | `amount_due` | Valor nominal do título (centavos) | | `interest_amount` | Juros pagos (centavos) | | `fine_amount` | Multa paga (centavos) | | `discount_amount` | Desconto aplicado (centavos) | | `rebate_amount` | Abatimento aplicado (centavos) | | `beneficiary_name` | Nome do beneficiário | | `beneficiary_document` | Documento do beneficiário | | `issuer_name` | Nome do emissor do boleto pago | | `issuer_document` | CPF/CNPJ do emissor do boleto pago | | `issuer_bank_code` | Código do banco do emissor | | `our_number` | Nosso número | | `document_number` | Número do documento | | `wallet_number` | Número da carteira | | `paid_at` | Data/hora do pagamento (BRT) | | `payment_limit_date` | Data limite de pagamento (BRT) | | `is_hybrid` | Boleto com QR Code Pix embutido | **TED/TEF** | Campo | Descrição | | --------------------- | ---------------------------------------- | | `purpose_code` | Código de finalidade | | `purpose_description` | Descrição legível da finalidade | | `return_detail` | Detalhe da devolução (TED) | | `reversal_of_id` | ID da transação original (em devoluções) | **Contraparte — dados bancários** | Campo | Descrição | | ----------------------------- | ------------------------ | | `counterparty_bank_code` | Código COMPE do banco | | `counterparty_bank_ispb` | ISPB do banco | | `counterparty_bank_name` | Nome do banco | | `counterparty_branch` | Agência | | `counterparty_branch_digit` | Dígito da agência | | `counterparty_account_number` | Número da conta | | `counterparty_account_digit` | Dígito da conta | | `counterparty_account_type` | Tipo da conta | **Ciclo de vida / auditoria** | Campo | Descrição | | -------------- | ----------------------------------------------- | | `created_at` | Data/hora de criação (BRT) | | `updated_at` | Data/hora da última atualização (BRT) | | `processed_at` | Data/hora de processamento/conclusão (BRT) | | `scheduled_at` | Data/hora de agendamento (BRT) | | `failed_at` | Data/hora de falha (BRT) | | `reversed_at` | Data/hora de reversão/devolução (BRT) | | `requested_by` | Membership que solicitou a transação | | `approved_at` | Data/hora da aprovação (BRT) | | `approved_by` | Membership que aprovou a transação | | `rejected_at` | Data/hora da rejeição (BRT) | | `rejected_by` | Membership que rejeitou a transação | ## Transferência TEF `POST /accounts/transfers/tef` `APP` `PARTNER` ### Campos renomeados no request | Versão atual | Nova versão | Ação | | --------------------- | -------------- | -------------- | | `client_operation_id` | `reference_id` | Renomear campo | | `client_description` | `description` | Renomear campo | ### Campos removidos no request | Campo | Ação | | ---------- | --------------------------------------------------------------------------------------------------------------- | | `approval` | Removido — toda transação é criada como `AWAITING_APPROVAL`. Aprovação via endpoint dedicado | | `step_up` | Removido da criação — step-up agora exigido apenas na aprovação (`PATCH /accounts/approvals/transactions/{id}`) | ### Campos renomeados no response | Versão atual | Nova versão | Ação | | --------------------- | ------------------------------ | -------------------- | | `transaction_id` | `id` | Atualizar referência | | `transaction_amount` | `amount` | Atualizar referência | | `transaction_fee` | `fee_amount` | Atualizar referência | | `to_account` (objeto) | `destination_account` (objeto) | Renomear objeto | ### Alteração de estrutura no response | Versão atual | Nova versão | Ação | | ------------------------------------------------- | -------------- | ----------------------------------------- | | `destination_account.branch_code` sempre presente | Agora opcional | Omitido quando vazio (antes string vazia) | ### Campos removidos no response | Campo | Ação | | ------------------ | ------------------------------------------------------------------- | | `transaction_code` | Removido | | `movement_code` | Removido | | `auth_code` | Removido da criação — disponível apenas após aprovação e liquidação | ### Campos adicionados no response | Campo | Descrição | | -------- | ---------------------------------------------------------------------------------------------- | | `status` | Sempre retorna `AWAITING_APPROVAL` — aprovar via `PATCH /accounts/approvals/transactions/{id}` | ## Transferência TED `POST /accounts/transfers/ted` `APP` `PARTNER` ### Campos renomeados no request | Versão atual | Nova versão | Ação | | --------------------- | -------------- | -------------- | | `client_operation_id` | `reference_id` | Renomear campo | | `client_description` | `description` | Renomear campo | ### Campos alterados no request | Versão atual | Nova versão | Ação | | ----------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------- | | `beneficiary.account_digit` (obrigatório) | `beneficiary.account_digit` (opcional) | Para conta PAYMENT, omitir — `account_number` já inclui dígito | | `beneficiary.branch_digit` (obrigatório) | `beneficiary.branch_digit` (opcional) | Agora opcional | | `beneficiary.account_number` | Formato depende do tipo de conta | PAYMENT: número completo com dígito (ex: 02452282). CHECKING/SAVINGS: sem dígito | ### Campos removidos no request | Campo | Ação | | ---------- | --------------------------------------------------------------------------------------------------------------- | | `approval` | Removido — toda transação é criada como `AWAITING_APPROVAL`. Aprovação via endpoint dedicado | | `step_up` | Removido da criação — step-up agora exigido apenas na aprovação (`PATCH /accounts/approvals/transactions/{id}`) | ### Campos renomeados no response | Versão atual | Nova versão | Ação | | -------------------- | ------------ | -------------------- | | `transaction_id` | `id` | Atualizar referência | | `transaction_amount` | `amount` | Atualizar referência | | `transaction_fee` | `fee_amount` | Atualizar referência | ### Campos alterados no response | Versão atual | Nova versão | Ação | | --------------------------------------------- | -------------------------------------- | -------------------------- | | `beneficiary.branch_digit` (sempre presente) | `beneficiary.branch_digit` (opcional) | Pode ser omitido | | `beneficiary.account_digit` (sempre presente) | `beneficiary.account_digit` (opcional) | Omitido para conta PAYMENT | ### Campos removidos no response | Campo | Ação | | ------------------ | ------------------------------------------------------------------- | | `transaction_code` | Removido | | `movement_code` | Removido | | `auth_code` | Removido da criação — disponível apenas após aprovação e liquidação | ### Campos adicionados no response | Campo | Descrição | | -------- | ---------------------------------------------------------------------------------------------- | | `status` | Sempre retorna `AWAITING_APPROVAL` — aprovar via `PATCH /accounts/approvals/transactions/{id}` | ## Transferência Pix `POST /accounts/pix/transfers` `APP` `PARTNER` ### Campos alterados no request | Versão atual | Nova versão | Ação | | ------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------------------- | | `pix_account.owner_name` | `pix_account.holder_name` | Renomear campo | | `pix_account.owner_document` | `pix_account.holder_document` | Renomear campo | | `pix_account.payment_account` | Removido | Usar `account_number` com dígito para PAYMENT | | `pix_account.account_number` (opcional) | `pix_account.account_number` (obrigatório) | Agora obrigatório — para PAYMENT, informar com dígito | | `pix_account.account_digit` (obrigatório) | `pix_account.account_digit` (opcional) | Omitir para PAYMENT | | `pix_account.account_type` (opcional, default PAYMENT) | `pix_account.account_type` (obrigatório, enum) | Agora obrigatório com enum AccountType | | `pix_account.account_model` | `pix_account.account_model` (opcional, enum) | Novo enum AccountModel (MOVEMENT, ESCROW, LINKED) | ### Campos removidos no request | Campo | Ação | | ---------- | --------------------------------------------------------------------------------------------------------------- | | `approval` | Removido — toda transação é criada como `AWAITING_APPROVAL`. Aprovação via endpoint dedicado | | `step_up` | Removido da criação — step-up agora exigido apenas na aprovação (`PATCH /accounts/approvals/transactions/{id}`) | ### Campos renomeados no response | Versão atual | Nova versão | Ação | | ---------------- | ------------- | -------------------- | | `transaction_id` | `id` | Atualizar referência | | `sent_date` | `occurred_at` | Atualizar referência | ### Campos removidos no response | Campo | Ação | | ------------------ | ------------------------------------------------------------------- | | `transaction_code` | Removido | | `from_account` | Removido | | `auth_code` | Removido da criação — disponível apenas após aprovação e liquidação | ### Campos adicionados no response | Campo | Descrição | | ------------ | ---------------------------------------------------------------------------------------------- | | `fee_amount` | Valor da tarifa (opcional) | | `status` | Sempre retorna `AWAITING_APPROVAL` — aprovar via `PATCH /accounts/approvals/transactions/{id}` | ## Devolução Pix `POST /accounts/pix/refunds` `APP` `PARTNER` ### Campos alterados no request | Versão atual | Nova versão | Ação | | ------------------------ | ----------------------------- | ------------------------- | | `refund_reason` (number) | `refund_reason` (enum string) | Ver tabela abaixo | | `priority` | Removido | Campo não mais necessário | ### Campos removidos no request | Campo | Ação | | ---------- | --------------------------------------------------------------------------------------------------------------- | | `approval` | Removido — toda transação é criada como `AWAITING_APPROVAL`. Aprovação via endpoint dedicado | | `step_up` | Removido da criação — step-up agora exigido apenas na aprovação (`PATCH /accounts/approvals/transactions/{id}`) | ### Enum PixRefundReason | Valor | Significado | | ------------------- | ------------------------ | | `DUPLICATE_PAYMENT` | Pagamento duplicado | | `WRONG_AMOUNT` | Valor incorreto | | `FRAUD` | Fraude | | `SETTLEMENT_ERROR` | Erro de liquidação | | `RECEIVER_REQUEST` | Solicitação do recebedor | | `BANK_ERROR` | Erro do banco | | `PAYER_REQUEST` | Solicitação do pagador | | `UNAUTHORIZED` | Não autorizado | ### Campos renomeados no response | Versão atual | Nova versão | Ação | | ---------------- | ------------- | -------------------- | | `transaction_id` | `id` | Atualizar referência | | `sent_date` | `occurred_at` | Atualizar referência | ### Campos adicionados no response | Campo | Descrição | | -------- | ---------------------------------------------------------------------------------------------- | | `status` | Sempre retorna `AWAITING_APPROVAL` — aprovar via `PATCH /accounts/approvals/transactions/{id}` | ## Chaves Pix ### Listagem e detalhe `GET /accounts/pix/keys` `APP` `PARTNER` `API` e `GET /accounts/pix/keys/:id` `APP` `PARTNER` `API` ### Campos renomeados no response | Versão atual | Nova versão | Ação | | -------------------- | ----------------- | -------------------------------------- | | `owner_name` | `holder_name` | Atualizar referência | | `owner_document` | `holder_document` | Atualizar referência | | `owner_person_type` | `person_type` | Atualizar referência | | `owner_trading_name` | `trade_name` | Atualizar referência (apenas detalhe) | | `qrcode_emv` | `pix_emv` | Atualizar referência (apenas listagem) | | `qrcode_image` | `pix_qr_code` | Atualizar referência (apenas listagem) | ### Campos renomeados no response do banco (objeto `bank`) | Versão atual | Nova versão | Ação | | ------------ | ----------- | -------------------- | | `ispb` | `bank_ispb` | Atualizar referência | | `name` | `bank_name` | Atualizar referência | | `number` | `bank_code` | Atualizar referência | ### Enum pix_key_type | Versão atual | Nova versão | Ação | | -------------- | ----------- | -------------- | | `PHONE_NUMBER` | `PHONE` | Atualizar enum | | `RANDOM` | `EVP` | Atualizar enum | > **Nota:** Os valores `CPF`, `CNPJ` e `EMAIL` permanecem inalterados. A mudança de enum afeta todos os endpoints que usam `pix_key_type`: criação, listagem, detalhe, DICT e QR codes. ### Novo endpoint `POST /accounts/pix/keys/{pix_key}/qrcode` `APP` `PARTNER` Gera ou regenera o QR code estático de uma chave Pix existente. Retorna `pix_emv` e `pix_qr_code`. Útil para chaves que ainda não possuem QR code. ## QR code Pix: criação `POST /accounts/pix/qrcodes/static` `APP` `PARTNER` `API` `POST /accounts/pix/qrcodes/dynamic` `APP` `PARTNER` `API` `POST /accounts/pix/qrcodes/billing` `APP` `PARTNER` `API` ### Alteração de estrutura no response | Versão atual | Nova versão | Ação | | -------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------- | | Objeto aninhado `qrcode: { id, txid, emv, image }` | Campos no nível raiz: `id`, `txid`, `pix_emv`, `pix_qr_code` | Remover wrapper `qrcode`, acessar campos diretamente | ### Campos renomeados no response | Versão atual | Nova versão | Ação | | -------------- | ------------- | -------------------- | | `qrcode.emv` | `pix_emv` | Atualizar referência | | `qrcode.image` | `pix_qr_code` | Atualizar referência | ### Campos alterados no request (dinâmico e billing) | Versão atual | Nova versão | Ação | | -------------------------- | ----------------------- | -------------- | | `expires_at` (obrigatório) | `expires_at` (opcional) | Agora opcional | ### Campos adicionados no request (dinâmico e billing) | Campo | Descrição | | ------------ | -------------------------------------------------- | | `expires_in` | Expiração em segundos (alternativa a `expires_at`) | ### Campos renomeados no request (desconto/juros/multa do QR code) | Versão atual | Nova versão | Ação | | ------------ | ----------- | ----------------------------- | | `amount` | `value` | Renomear campo | | `type` | `code` | Renomear campo (agora string) | ## QR code Pix: leitura `GET /accounts/pix/qrcodes/:id` `APP` `PARTNER` `API` ### Campos renomeados no response | Versão atual | Nova versão | Ação | | ------------------------- | ----------------- | -------------------------------------------- | | `qrcode_type_name` | `qrcode_type` | Agora enum tipado (STATIC, DYNAMIC, BILLING) | | `owner_document` | `holder_document` | Atualizar referência | | `additional_informations` | `additional_info` | Atualizar referência | ### Campos que passaram a opcionais | Campo | Ação | | ----------------- | --------------------------------- | | `txid` | Antes obrigatório, agora opcional | | `url` | Antes obrigatório, agora opcional | | `merchant_name` | Antes obrigatório, agora opcional | | `merchant_city` | Antes obrigatório, agora opcional | | `holder_document` | Antes obrigatório, agora opcional | ## QR code Pix: status `GET /accounts/pix/qrcodes/:id/status` `APP` `PARTNER` `API` ### Campos renomeados no response | Versão atual | Nova versão | Ação | | ------------------ | ------------- | -------------------------------------------- | | `qrcode_type_name` | `qrcode_type` | Agora enum tipado (STATIC, DYNAMIC, BILLING) | ### Campos adicionados no response | Campo | Descrição | | ----------------- | ------------------------------------------------ | | `amount` | Valor do QR Code (centavos, opcional) | | `pix_key` | Chave Pix associada (opcional) | | `additional_info` | Informação adicional (opcional) | | `reference_id` | ID de referência do cliente (opcional) | | `payer_name` | Nome do pagador (preenchido após pagamento) | | `payer_document` | Documento do pagador (preenchido após pagamento) | | `paid_amount` | Valor efetivamente pago (centavos, opcional) | | `paid_at` | Data/hora do pagamento (opcional) | ## Boletos: registrar `POST /accounts/bank-slips` `APP` `PARTNER` `API` ### Campos renomeados no request | Versão atual | Nova versão | Ação | | -------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------- | | `invoice_amount` | `amount` | Renomear campo | | `your_number` | `our_number` | Renomear campo (nosso número) | | `payer.trading_name` | `payer.trade_name` | Renomear campo | | `guarantor.person_type` (INDIVIDUAL/BUSINESS) | `guarantor.type` (EXEMPT/CPF/CNPJ/PIS_PASEP/OTHER) | Renomear campo e mudar enum | | `guarantor.document_number` | `guarantor.document` | Renomear campo | | `interest.amount` / `fine.amount` / `discount.amount` | `interest.value` / `fine.value` / `discount.value` | Renomear campo | | `interest.code` / `fine.code` / `discount.code` (number) | Enums FEBRABAN (string) | Ver tabela abaixo | | `discount` (objeto único) | Removido — usar `discounts` (array) | Usar sempre array, mesmo para 1 desconto | | `payer.address.postal_code` | `payer.address.zip_code` | Renomear campo | ### Enums FEBRABAN para juros, multa e desconto Os campos `code` de juros, multa e desconto agora usam enums string em vez de códigos numéricos. **`interest.code`** (`InterestCode`): | Valor | Significado | `value` | | ------------------------ | ---------------------------- | -------------- | | `EXEMPT` | Isento de juros | — | | `FIXED_PER_DAY` | Valor fixo por dia de atraso | Centavos | | `PERCENTAGE_PER_MONTH` | Percentual ao mês | Ex: 2.5 = 2,5% | | `FIXED_PER_BUSINESS_DAY` | Valor fixo por dia útil | Centavos | **`fine.code`** (`FineCode`): | Valor | Significado | `value` | | ------------ | ------------------------ | ------------ | | `EXEMPT` | Isento de multa | — | | `FIXED` | Valor fixo | Centavos | | `PERCENTAGE` | Percentual sobre o valor | Ex: 2.0 = 2% | **`discount.code`** (`DiscountCode`) — cada item do array `discounts`: | Valor | Significado | `value` | | ------------------------ | -------------------------------------- | -------------- | | `EXEMPT` | Isento de desconto | — | | `FIXED_UNTIL_DATE` | Valor fixo até a data | Centavos | | `PERCENTAGE_UNTIL_DATE` | Percentual até a data | Ex: 5.0 = 5% | | `FIXED_PER_DAY` | Valor fixo por dia de antecipação | Centavos | | `PERCENTAGE_PER_DAY` | Percentual por dia de antecipação | Ex: 0.1 = 0,1% | | `FIXED_PER_BUSINESS_DAY` | Valor fixo por dia útil de antecipação | Centavos | > **Nota sobre `value`:** Para códigos fixos (FIXED*\*), `value` é em **centavos** (inteiro). Para percentuais (PERCENTAGE*\*), `value` é o **percentual direto** (decimal, ex: 2.5 = 2,5%). ### Campos adicionados no request | Campo | Descrição | | -------------------------------------------------------- | ---------------------------------------------------------- | | `discounts` (array de `{ code, date, value }`) | Novo campo para descontos (substituiu `discount` singular) | | `recurrence` (`{ type?, model, quantity?, fixed_day? }`) | Novo campo opcional para boletos recorrentes | ### Campos renomeados no response | Versão atual | Nova versão | Ação | | ----------------------------------------------- | ------------------------------------- | --------------------------- | | `invoice_amount` | `amount` | Renomear campo | | `identification_code` | Removido | Não depender deste campo | | `guarantor.person_type` | `guarantor.type` (GuarantorType enum) | Renomear campo e mudar enum | | `guarantor.document_number` | `guarantor.document` | Renomear campo | | `interest.amount` / `fine.amount` | `interest.value` / `fine.value` | Renomear campo | | `interest.code` / `fine.code` (number) | Enums FEBRABAN (string) | Ver tabela de enums | | `trading_name` | `trade_name` | Renomear campo | | `payer.address` | Agora opcional (pode ser omitido) | Tratar como nullable | | `guarantor` / `interest` / `fine` / `discounts` | Agora opcionais | Tratar como nullable | ## Boletos: pagar `POST /accounts/bank-slips/payments` `APP` `PARTNER` ### Campos renomeados no request | Versão atual | Nova versão | Ação | | --------------------- | -------------- | ------------------------------------------------------------------------------- | | `invoice_amount` | `amount` | Renomear campo (valor nominal do título — copiar do campo `amount` da consulta) | | `client_operation_id` | `reference_id` | Renomear campo | | `client_description` | `description` | Renomear campo | ### Campos adicionados no request | Campo | Descrição | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `payment_amount` | Valor efetivo do pagamento (copiar do campo `amount_due` da consulta, com descontos/juros) | | `issuer` | Objeto opcional com os dados do cedente/emissor, ecoados da consulta do boleto, para exibição no comprovante. Subcampos: `name`, `document_number`, `bank_code` (todos opcionais) | ### Campos removidos no request | Campo | Ação | | ---------- | --------------------------------------------------------------------------------------------------------------- | | `approval` | Removido — toda transação é criada como `AWAITING_APPROVAL`. Aprovação via endpoint dedicado | | `step_up` | Removido da criação — step-up agora exigido apenas na aprovação (`PATCH /accounts/approvals/transactions/{id}`) | ### Campos renomeados no response | Versão atual | Nova versão | Ação | | ---------------- | ----------- | ------------------------ | | `transaction_id` | `id` | Renomear campo | | `payment_amount` | `amount` | Renomear campo | | `movement_code` | Removido | Não depender deste campo | ### Campos adicionados no response | Campo | Descrição | | -------- | ---------------------------------------------------------------------------------------------- | | `status` | Sempre retorna `AWAITING_APPROVAL` — aprovar via `PATCH /accounts/approvals/transactions/{id}` | ## Boletos: consultar ### Listagem e detalhe `GET /accounts/bank-slips` `APP` `PARTNER` `API` e `GET /accounts/bank-slips/{id}` `APP` `PARTNER` `API` | Versão atual | Nova versão | Ação | | -------------------------------------------------------- | ---------------------------------------------------- | --------------------------- | | `invoice_amount` | `amount` | Renomear campo | | `discount` (objeto único) | Removido — usar `discounts` (array) | Sempre array | | `guarantor.person_type` | `guarantor.type` (GuarantorType enum) | Renomear campo e mudar enum | | `guarantor.document_number` | `guarantor.document` | Renomear campo | | `interest.amount` / `fine.amount` / `discount.amount` | `interest.value` / `fine.value` / `discount[].value` | Renomear campo | | `interest.code` / `fine.code` / `discount.code` (number) | Enums FEBRABAN (string) | Ver tabela de enums | | `trading_name` | `trade_name` | Renomear campo | | Campos vazios ("") | Omitidos do response (`undefined`) | Tratar ausência de campo | | `id` | Pode ser omitido na listagem (campo opcional) | Tratar como nullable | ### Campos adicionados no detalhe `GET /accounts/bank-slips/{id}` `APP` `PARTNER` `API` | Campo | Descrição | | ------------------- | ------------------------------------------- | | `registration_code` | Código de registro do boleto | | `registration_date` | Data de registro na CIP | | `title_species` | Espécie do título (código FEBRABAN) | | `payment_blocked` | Indica se pagamento está bloqueado | | `is_hybrid` | Indica se o boleto aceita pagamento via Pix | | `pix_emv` | Payload EMV para Pix copia e cola | | `pix_qr_code` | QR code Pix em base64 (PNG) | ### Consulta de terceiros `GET /accounts/bank-slips/consult` `APP` `PARTNER` `API` | Versão atual | Nova versão | Ação | | -------------------------------------- | ------------------------------------- | --------------------------- | | `total_amount` | Removido — usar `amount_due` | Atualizar referência | | `guarantor.person_type` | `guarantor.type` (GuarantorType enum) | Renomear campo e mudar enum | | `guarantor.document_number` | `guarantor.document` | Renomear campo | | `interest.amount` / `fine.amount` | `interest.value` / `fine.value` | Renomear campo | | `interest.code` / `fine.code` (number) | Enums FEBRABAN (string) | Ver tabela de enums | ### Campos adicionados na consulta de terceiros | Campo | Descrição | | ------------------------------------------------------------ | ------------------------------------------------------- | | `amount_due` | Valor atualizado (com juros/multa/desconto) em centavos | | `issue_date` | Data de emissão | | `dda_control_number` | Número de controle DDA | | `status` (BankSlipPaymentStatus: OPEN/WRITTEN_OFF/PROTESTED) | Status para pagamento | | `discounts` (array) | Descontos aplicáveis (substituiu posição fixa) | | `validations` (array de `{ message }`) | Alertas sobre o boleto (ex: "Boleto já baixado") | ### Bug fixes | Endpoint | Bug | Correção | | -------------------------------------- | ------------------------------------------------- | ----------------------- | | `POST /accounts/bank-slips` (response) | Campo `email` retornava o valor de `phone_number` | Corrigido | | `POST /accounts/bank-slips/payments` | HTTP 502 para erros de negócio | Corrigido para HTTP 422 | | `GET /accounts/bank-slips/consult` | Status `sitTitPgto: "12"` não mapeado | Mapeado para `OPEN` | ## Boletos: status O campo `status` nos endpoints de boleto utiliza enums diferentes dependendo do contexto: ### BankSlipPaymentStatus Consulta de boletos de terceiros (`GET /bank-slips/consult`). Perspectiva do DDA/câmara de compensação: "posso pagar este boleto?" | Valor | Significado | | ------------- | ------------------------------------------------------------------- | | `OPEN` | Boleto ativo, disponível para pagamento | | `WRITTEN_OFF` | Boleto baixado (pago, cancelado ou expirado) — não aceita pagamento | | `PROTESTED` | Boleto protestado em cartório | ### BankSlipRegistrationStatus Boletos registrados (`GET /bank-slips`, `GET /bank-slips/:id`, `POST /bank-slips`, `DELETE /bank-slips/:id`). Perspectiva do cedente/emissor: "o que aconteceu com meu boleto?" | Valor | Significado | | --------------------------- | -------------------------------------- | | `PENDING_REGISTRATION` | Aguardando registro na CIP | | `REGISTERED` | Registrado e disponível para pagamento | | `REGISTRATION_ERROR` | Falha no registro | | `PAID` | Pago pelo sacado | | `PARTIALLY_PAID` | Pago a menor, título ainda em aberto | | `WRITTEN_OFF` | Baixado (cancelado pelo cedente) | | `PAYMENT_LIMIT_EXPIRED` | Data limite de pagamento expirada | | `PENDING_WRITE_OFF` | Aguardando baixa | | `PENDING_PROTEST_WRITE_OFF` | Aguardando baixa de protesto | | `PROTESTED` | Protestado em cartório | | `PAID_AT_NOTARY` | Pago em cartório | > **Nota:** Um mesmo boleto pode ter status `WRITTEN_OFF` na consulta de terceiros e `PAID` na listagem de registros — são visões complementares do mesmo evento. ### Correção de 18/08/2026 — a implementação passou a seguir esta tabela Até esta data a persistência usava um conjunto **diferente** do documentado acima, e a divergência aparecia de duas formas: | Comportamento anterior | Agora | Ação | | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------ | | Boleto cancelado era devolvido como `CANCELLED` — valor que nunca constou desta tabela | `WRITTEN_OFF`, como já estava documentado | Quem tratava `CANCELLED` deve passar a tratar `WRITTEN_OFF` | | Filtrar `GET /accounts/bank-slips?status=` por 7 dos 10 valores documentados respondia **HTTP 500** | Todos os valores da tabela funcionam | Nenhuma — o filtro passa a responder o que a documentação sempre prometeu | | Valor inválido no filtro respondia 500 | HTTP 400, com a lista de valores aceitos | Nenhuma | Os valores `CANCELLED` e `EXPIRED` **deixam de existir**; o segundo nunca foi produzido. `PARTIALLY_PAID` entra como valor válido, ainda sem produtor no provider atual. ## Boletos: URLs | Versão atual | Nova versão | Ação | | ------------------------------------------------- | ----------------------------------------------------------- | ------------------------ | | `GET /accounts/bank-slips?barcode=` | `GET /accounts/bank-slips/consult?barcode=&digitable_line=` | Mudar URL | | `POST /accounts/bank-slips/registrations` | `POST /accounts/bank-slips` | Remover `/registrations` | | `GET /accounts/bank-slips/registrations` | `GET /accounts/bank-slips` | Remover `/registrations` | | `GET /accounts/bank-slips/registrations/{id}` | `GET /accounts/bank-slips/{id}` | Remover `/registrations` | | `GET /accounts/bank-slips/registrations/{id}/pdf` | `GET /accounts/bank-slips/{id}/pdf` | Remover `/registrations` | | `DELETE /accounts/bank-slips/registrations/{id}` | `DELETE /accounts/bank-slips/{id}` | Remover `/registrations` | ## Pix: URLs | Versão atual | Nova versão | Ação | | --------------------------------- | ----------------------------------- | ----------------------------------- | | `POST /accounts/pix/transactions` | `POST /accounts/pix/transfers` | Mudar URL | | `GET /accounts/pix/dict?pix_key=` | `GET /accounts/pix/keys/dict/{key}` | Chave no path em vez de query param | ## Onboarding Todos os endpoints de onboarding são exclusivos para o app mobile (`APP`). ### URLs e métodos alterados | Versão atual | Nova versão | Ação | | ------------------------------------ | --------------------------------------- | -------------------------------- | | `POST /onboarding/validate-invite` | `POST /onboarding/invites/validations` | Mudar URL | | `POST /onboarding/validate-document` | `POST /onboarding/documents/validations` | Mudar URL | | `POST /onboarding/register` | `POST /onboarding` | Mudar URL | | `POST /onboarding/{id}/send-otp` | `POST /onboarding/{id}/otp` | Mudar URL | | `POST /onboarding/{id}/verify-otp` | `POST /onboarding/{id}/otp/verification` | Mudar URL | | `POST /onboarding/{id}/submit` | `POST /onboarding/{id}/submission` | Mudar URL | | `POST /onboarding/{id}/cancel` | `DELETE /onboarding/{id}` | Mudar method (POST→DELETE) e URL | ⚠️ **Quatro linhas desta tabela estavam ERRADAS até 21/08** e foram corrigidas contra o controller: as duas de validação diziam `validation` no singular (a rota é plural), o verify-OTP dizia `PUT /onboarding/{id}/otp` (é `POST /onboarding/{id}/otp/verification`) e o submit dizia `PATCH /onboarding/{id}` (é `POST /onboarding/{id}/submission`). É a mesma classe do `x-security`: documentação que nenhum teste verifica, e que ninguém percebe estar errada porque parece plausível. A tabela agora reflete `onboarding.controller.ts`. ### Campos adicionados no request de dados pessoais `PUT /onboarding/{id}/personal-data` `APP` | Campo | Descrição | | ------------- | -------------------------------- | | `nationality` | Nacionalidade (opcional) | | `occupation` | Ocupação profissional (opcional) | ### Campos adicionados no fluxo de OTP `POST /onboarding/{id}/otp` (envio) — response agora inclui: | Campo | Descrição | | -------- | -------------------------------------------------------------- | | `otp_id` | Identificador do OTP enviado (deve ser enviado na verificação) | `PUT /onboarding/{id}/otp` (verificação) — request agora exige: | Campo | Descrição | | -------- | -------------------------------------- | | `otp_id` | Identificador do OTP recebido no envio | ## Perfil do usuário `GET /memberships/me` `APP` `INTERNET_BANKING` O endpoint (`GET /memberships/me`) foi atualizado com resposta enriquecida e padronizada. ### Campos removidos | Campo | Ação | | --------------------------------- | ----------------------------------------------------- | | `user.photo` | Removido (nunca implementado, sempre retornava vazio) | | `user.verified_at` | Removido; usar `user.is_verified` | | `user.account_access_level` | Removido; usar `membership.role` | | `user.account_membership_role` | Removido; usar `membership.role` | | `account.owner` (objeto aninhado) | Removido; campos promovidos para `account.*` | | `account.owner.document_number` | Usar `account.holder_document` | | `account.owner.email` | Removido do perfil | | `account.owner.landing_phone` | Removido do perfil | | `account.owner.mobile_phone` | Removido do perfil | | `device.is_verified` | Removido; usar `device.is_trusted` | ### Campos renomeados | Versão atual | Nova versão | Ação | | ----------------------------- | ----------------------------- | ----------------------------------- | | `user.user_status` | `user.status` | Atualizar referência | | `account.account_person_type` | `account.person_type` | Atualizar referência | | `account.owner.name` | `account.holder_name` | Campo promovido para nível da conta | | `account.owner.kyc_status` | `account.kyc_status` | Campo promovido para nível da conta | | `user.is_pin_set` | `membership.is_pin_set` | Movido para seção correta | | `device.is_totp_set` | `device.is_totp_enabled` | Padronização de booleanos (`is_`) | | `device.trust_level` (string) | `device.is_trusted` (boolean) | Tipo alterado: string → boolean | ### Campos adicionados | Campo | Descrição | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `user.birth_date` | Data de nascimento (YYYY-MM-DD, opcional) | | `user.is_verified` | Se o usuário foi verificado | | `user.created_at` | Data de criação do usuário | | `account.status` | Status da conta (PENDING_ACTIVATION, ACTIVE, BLOCKED, CLOSED, REJECTED) | | `account.account_digit` | Dígito da conta (opcional, null para contas PAYMENT) | | `account.currency` | Moeda da conta (sempre BRL) | | `membership` (novo bloco) | Dados do vínculo ativo: `id`, `role`, `status`, `is_pin_set`, `created_at` | | `session` (novo bloco) | Estado da sessão: `is_step_up_enabled` (indica se PIN + TOTP estão configurados, não se foram verificados) | | `available_memberships` (novo array) | Lista de vínculos para troca de conta | | `available_memberships[].membership_id` | ID do vínculo | | `available_memberships[].account_id` | ID da conta | | `available_memberships[].holder_name` | Nome do titular | | `available_memberships[].holder_document` | Documento do titular | | `available_memberships[].account_number` | Número da conta | | `available_memberships[].person_type` | Tipo de pessoa (INDIVIDUAL/BUSINESS) | | `available_memberships[].account_status` | Status da conta | | `available_memberships[].role` | Papel do usuário na conta | | `device.first_login_at` | Data do primeiro login no dispositivo | ### Padronização de booleanos (prefixo `is_`) Todos os campos booleanos na API agora seguem o padrão `is_` como prefixo: | Antes | Depois | Tipo | | -------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | | `totp_enabled` | `is_totp_enabled` | boolean | | `step_up_verified` | `is_step_up_enabled` | boolean — semântica alterada: indica se PIN + TOTP estão **configurados** (não se foram verificados no request) | | `trust_level` (string LOW/MEDIUM/HIGH) | `is_trusted` | boolean | | — | `is_verified` | boolean | | — | `is_pin_set` | boolean | ### Endpoint removido | Versão atual | Ação | | ------------------------ | -------------------------------------------------- | | `GET /memberships/me/v2` | Removido; usar `GET /memberships/me` (consolidado) | ## Fluxo de aprovação de transações Todos os endpoints de criação de transações financeiras agora criam com status `AWAITING_APPROVAL` em vez de executar diretamente. A aprovação é feita em um endpoint separado (PATCH). ### Mudança de ActionPolicy nos endpoints POST | Endpoint | Antes | Depois | Impacto | | ------------------------------------ | -------------------------------------- | ------------------------------------ | -------------------------------------------- | | `POST /accounts/pix/transfers` | `PIX_PAYMENT_APPROVE` (CRITICAL) | `PIX_PAYMENT_REQUEST` (MEDIUM) | Step-up e signature não obrigatórios no POST | | `POST /accounts/pix/refunds` | `PIX_REFUND_APPROVE` (CRITICAL) | `PIX_REFUND_REQUEST` (MEDIUM) | Idem | | `POST /accounts/transfers/tef` | `TRANSFER_TEF_APPROVE` (CRITICAL) | `TRANSFER_TEF_REQUEST` (MEDIUM) | Idem | | `POST /accounts/transfers/ted` | `TRANSFER_TED_APPROVE` (CRITICAL) | `TRANSFER_TED_REQUEST` (MEDIUM) | Idem | | `POST /accounts/bank-slips/payments` | `BANK_SLIP_PAYMENT_APPROVE` (CRITICAL) | `BANK_SLIP_PAYMENT_REQUEST` (MEDIUM) | Idem | **Impacto**: endpoints POST agora acessíveis com `min_account_role: OPERATOR` e `scope: payments:write` (antes exigiam ADMIN + payments:authorize + step-up). Os campos `approval` e `step_up` foram removidos do body dos endpoints POST. ### Fluxo obrigatório em dois passos Toda transação financeira é criada com status `AWAITING_APPROVAL`. Não existe mais execução direta (o campo `approval: "IMMEDIATE"` foi removido). O fluxo é sempre: 1. **Solicitação** (`POST`): cria a transação com status `AWAITING_APPROVAL`. Limite reservado, tarifa calculada. Sem step-up ou assinatura HMAC. 2. **Aprovação** (`PATCH /accounts/approvals/transactions/{id}`): aprova (executa) ou rejeita (cancela). Step-up obrigatório conforme actor type. ### Step-up por actor type (apenas na aprovação) O campo `required_step_up_methods` nas policies de segurança agora é configurado por actor type: | Actor Type | Métodos de step-up | Observação | | ---------------- | ------------------ | ------------------------------------------------------ | | APP | TOTP + PIN | Ambos obrigatórios | | INTERNET_BANKING | TOTP + PIN | Ambos obrigatórios | | PARTNER | TOTP | PIN não exigido (segurança compensada por mTLS + HMAC) | | ACCOUNT_API | — | Não acessa endpoints de aprovação | ### Novo status de transação | Status | Descrição | | ------------------- | -------------------------------------------------------------------------------------- | | `AWAITING_APPROVAL` | Transação criada, aguardando aprovação. Limite reservado. Expira em 24h (configurável) | ### Campos removidos do request dos endpoints POST | Campo | Ação | | ---------- | ----------------------------------------------------------- | | `approval` | Removido — toda transação é criada como `AWAITING_APPROVAL` | | `step_up` | Removido da criação — exigido apenas na aprovação via PATCH | ### Campos alterados no response dos endpoints POST | Campo | Descrição | | -------- | ------------------------------------------------------------------------------ | | `status` | Sempre retorna `AWAITING_APPROVAL` (não retorna mais `PROCESSING` diretamente) | ### Expiração automática Transações `AWAITING_APPROVAL` não aprovadas em 24h (configurável) são automaticamente canceladas. Limite reservado é devolvido. ## MFA: TOTP Todos os endpoints de MFA são exclusivos para o app mobile (`APP`). | Versão atual | Nova versão | Ação | | ----------------------------- | ----------------------------------- | -------------------------------- | | `POST /auth/mfa/totp/enroll` | `POST /auth/mfa/totp/enrollments` | Mudar URL | | `POST /auth/mfa/totp/confirm` | `PUT /auth/mfa/totp/enrollments` | Mudar method (POST→PUT) e URL | | `POST /auth/mfa/totp/disable` | `DELETE /auth/mfa/totp/enrollments` | Mudar method (POST→DELETE) e URL | ## Step-up (verificação de segundo fator) `POST /auth/step-up` `APP` Endpoint dedicado para validação de step-up (PIN + TOTP) sem executar nenhuma operação. Utilizado pelo app para confirmar a identidade antes de apresentar telas de operações sensíveis. | Versão atual | Nova versão | Ação | | --------------------------------------- | -------------------- | -------------------------------------- | | `POST /memberships/me/pin/verification` | `POST /auth/step-up` | Mudar URL. Body e response inalterados | ### Body ```json { "step_up": { "pin": "849271", "totp": "331809" } } ``` ### Responses | Status | Descrição | | ------ | ----------------------------------- | | 204 | Step-up validado com sucesso | | 403 | PIN ou TOTP incorreto | | 423 | Bloqueado por excesso de tentativas | ### Notas - Disponível apenas para `APP` (mobile). PARTNER e INTERNET_BANKING utilizam step-up inline no body da operação. - PIN: 6 dígitos numéricos. TOTP: 6 dígitos do authenticator. - Múltiplas tentativas incorretas resultam em bloqueio temporário. ## Campos gerais Mudanças que afetam múltiplos endpoints. ### Padronização de nomes de campos | Versão atual | Nova versão | Ação | | -------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------- | | `authorization_code` / `authentication_code` | `auth_code` | Atualizar referência em TEF, TED, Pix, comprovante, detalhes | | `postal_code` | `zip_code` em endereços (payer, customer) | Atualizar em POST /accounts/bank-slips e POST /accounts/charges | | `transaction_id` (response) | `id` | Atualizar em extrato, comprovante, detalhes, TEF, TED, Pix | | `transaction_amount` | `amount` | Atualizar em comprovante, detalhes, TEF, TED | | `invoice_amount`/`title_amount`/`due_amount` | `amount_due` | Atualizar em pagamento de boleto e comprovante | | `transaction_fee` | `fee_amount` | Atualizar em TEF, TED | | `transaction_date`/`sent_date` | `occurred_at` | Atualizar em extrato, comprovante, detalhes, Pix | | `transaction_code` e `movement_code` | Removidos dos responses | Não depender desses campos | ### Padronização de campos do cliente (request e response) | Versão atual | Nova versão | Semântica | Endpoints afetados | | ------------------------- | ----------------- | ----------------------------- | ----------------------------------------------------- | | `client_operation_id` | `reference_id` | ID de rastreamento do cliente | TEF, TED, Pix transfer, QR codes, pagamento de boleto | | `client_description` | `description` | Texto livre do cliente | TEF, TED, Pix transfer, pagamento de boleto | | `additional_informations` | `additional_info` | Campo Pix BACEN (infoPagador) | Pix transfer, QR codes, Pix refund | ### Padronização de campos do sistema (response) | Versão atual | Nova versão | Semântica | Endpoints afetados | | ------------------------------ | ----------------------- | ----------------------------------------- | ------------------------------ | | `description` (no extrato) | `operation_description` | Descrição da operação gerada pelo sistema | Extrato, comprovante, detalhes | | `additional_info` (no extrato) | `description` | Texto livre do cliente | Extrato | ### Padronização owner → holder | Versão atual | Nova versão | Endpoints afetados | | -------------------- | ----------------- | -------------------------------------------------------------------------- | | `owner_name` | `holder_name` | Chaves Pix, comprovante (from/to), Pix transfer (request) | | `owner_document` | `holder_document` | Chaves Pix, comprovante (from/to), Pix transfer (request), QR code leitura | | `owner_person_type` | `person_type` | Chaves Pix (listagem e detalhe) | | `owner_trading_name` | `trade_name` | Chaves Pix (detalhe) | ### Enums tipados (novos) Campos que antes eram strings livres agora usam enums tipados: | Campo | Valores | Endpoints afetados | | -------------- | ---------------------------------------------------------------------- | --------------------------------------------- | | `type` | PIX, BANK_SLIP, TED, TEF, FEE, REVERSAL, SPLIT, CARD_PURCHASE | Extrato, comprovante, detalhes | | `direction` | CREDIT, DEBIT | Extrato, comprovante, detalhes | | `status` | PENDING, PROCESSING, COMPLETED, FAILED, REVERSED, SCHEDULED, CANCELLED | Extrato, comprovante, detalhes, TEF, TED, Pix | | `qrcode_type` | STATIC, DYNAMIC, BILLING | QR code leitura e status | | `account_type` | CHECKING, SAVINGS, PAYMENT, SALARY, INVESTMENT | TED (beneficiary), Pix transfer (pix_account) | ### Enum pix_key_type | Versão atual | Nova versão | Endpoints afetados | | -------------- | ----------- | ---------------------------------------------- | | `PHONE_NUMBER` | `PHONE` | Criação, listagem, detalhe, DICT, QR codes Pix | | `RANDOM` | `EVP` | Criação, listagem, detalhe, DICT, QR codes Pix | ## Status HTTP: erros de autorização Mudança **transversal**: não renomeia campo nenhum e não altera corpo de resposta. O que muda é o **status HTTP** de uma família de erros — e status é parte do contrato. ### O que muda | Situação | Versão atual | Nova versão | Ação | | -------- | ------------ | ----------- | ---- | | Membership inexistente, de outro usuário ou **inativo** | `422 UNPROCESSABLE_ENTITY` | **`403 FORBIDDEN`** | Tratar 403 nos fluxos de autenticação | | **Conta inativa** (suspensa/bloqueada) | `422 UNPROCESSABLE_ENTITY` | **`403 FORBIDDEN`** | idem | | Usuário sem escopo para a conta | `422 UNPROCESSABLE_ENTITY` | **`403 FORBIDDEN`** | idem | | Role do membership sem permissão para criar credencial de API | `422 UNPROCESSABLE_ENTITY` | **`403 FORBIDDEN`** | Tratar 403 em `POST /accounts/api-credentials` | O campo `code` do corpo acompanha o status: era `UNPROCESSABLE_ENTITY`, passa a ser `FORBIDDEN`. A `message` **não muda**. ### Endpoints afetados Os quatro primeiros compartilham o mesmo resolvedor de contexto de membership: | Endpoint | Quando dispara | | -------- | -------------- | | `POST /auth/login` `APP` | Conta única (fluxo direto), membership ou conta inativa | | `POST /auth/login/complete` `APP` | Membership informado inexistente, de outro dono ou inativo | | `POST /auth/login/switch` `APP` | Troca para conta à qual o usuário não tem acesso | | **`POST /auth/refresh`** `APP` | ⚠️ **A cada renovação de sessão** de conta suspensa ou bloqueada | | `POST /accounts/api-credentials` `APP` | Role do membership abaixo de MASTER | ### ⚠️ O contrato publicado JÁ declarava 403 Os cinco endpoints acima **já listavam `403` no OpenAPI** antes desta mudança — quem integrou lendo a referência já precisava tratá-lo. O que mudou foi o **runtime passar a cumprir o que o contrato dizia**; a documentação não estava errada, a implementação é que divergia dela. Na prática isso reduz bastante o esforço: para quem seguiu o spec, não há adequação — há um caminho que passa a ser exercitado de verdade. A entrada continua aqui porque **quem programou contra o comportamento observado**, e não contra a referência, vai ver status novo. ### Por que a mudança O erro de aplicação que representa "proibido" **não estava mapeado** no filtro global e caía no default `422`. Existem duas classes homônimas em camadas diferentes — a de infraestrutura, usada pelos guards, sempre respondeu `403`; a de aplicação, usada pelos usecases, respondia `422`. O contrato afirmava uma coisa e o runtime fazia outra. Além de corrigir a resposta, isso remove uma armadilha: quem escrevesse `throw new ForbiddenError` num usecase recebia `422` sem perceber. ### Impacto medido, não estimado Antes de mudar, o volume real foi medido no OpenSearch (janela de 15 dias, que é a retenção do índice de segurança): | Métrica | Valor | | ------- | ----- | | Eventos de falha nestes caminhos — **todos os motivos** | **1** | | Os dois motivos do `/auth/refresh` (`INACTIVE_USER`, `INACTIVE_ACCOUNT`) | **0** | | Controle: total de eventos de segurança na janela | 2.416, com documento em todos os dias | Ou seja: hoje o caminho praticamente não é exercitado. ⚠️ **Isso é piso, não teto** — a suspensão de conta entrou em produção em 17–18/08, e o volume tende a crescer com o uso da funcionalidade. Foi justamente por isso que a correção foi feita agora, e não depois. ### ⚠️ Atenção para o app Muitos clientes tratam `403` como **sessão inválida → logout**. Para conta suspensa em `POST /auth/refresh`, esse comportamento é provavelmente o **correto** — mas é mudança de fluxo, não apenas de código de status. Confira o tratamento genérico de `403` antes de subir. ## Onboarding — `next_action` e a saída do `password_set` de `contact` (21/08) Afeta `GET /onboarding/{id}`, `POST /auth/login` e `POST /auth/login/complete`. ### Por que O app decidia a próxima tela **reimplementando** o predicado de completude do submit a partir de `contact` + `steps`. Duas cópias da mesma regra: quando o backend passou a exigir os dados da empresa no submit de PJ, o app não tinha como saber — descobria com um `400`. Agora o backend devolve o que falta, derivado da **mesma função** que o submit usa para barrar. ### Campos adicionados | Campo | Onde | O que é | | ---------------------------------------- | ------------------------------------------------------- | ------- | | `pending_requirements` (array de enum) | `GET /onboarding/{id}` | O que falta para submeter, **sem ordem imposta**. Vazio ⇒ o submit passa | | `next_action` (enum) | `GET /onboarding/{id}`, `onboarding` das duas rotas de login | O que fazer agora — a primeira pendência na ordem canônica, ou o que esperar | Valores de `pending_requirements`: `SAVE_PERSONAL_DATA`, `COMPLETE_COMPANY_DATA`, `SET_PHONE`, `VERIFY_PHONE`, `SET_EMAIL`, `VERIFY_EMAIL`, `SET_PASSWORD`. `next_action` acrescenta a esses: `SUBMIT`, `WAIT_KYC`, `WAIT_PROVISIONING`, `NONE`. ⚠️ **`next_action` é sugestão; `pending_requirements` é a verdade.** A coleta é flexível — quem dirige a ordem é o app. Um app que colete e-mail antes de telefone deve ler o array e ignorar o escalar. ### Campo movido (breaking) | Antes | Depois | Ação | | ----------------------- | --------------- | ------------------------ | | `contact.password_set` | `password_set` (raiz do objeto) | Mudar o caminho de leitura | Senha é credencial, não endereço de contato. O bloco `contact` só a carregava porque significava, na prática, "o que falta para submeter" — papel que agora tem campo próprio. `contact` ficou com os quatro campos de contato e passou a ser o **detalhe do que já foi coletado**. ### ⚠️ Atenção para o app Nenhuma regra de negócio mudou — o submit barra exatamente o que barrava antes, com os mesmos motivos. O que mudou é que agora dá para **saber antes de tentar**. Recomendado trocar a lógica local de "posso submeter?" por `pending_requirements.length === 0`; mantê-la é o que produz divergência na próxima mudança de requisito. ## Onboarding — status `EXPIRED` e ação `OPEN_WEBVIEW` (24/08) ### Por que Fechar a webview e demorar ~17 minutos **reprovava o cadastro**, e a pessoa perdia até o login (sem conta e sem onboarding ativo, o `/auth/login` responde `422`). Agora abandono de captura mantém o cadastro vivo e retomável, e o vencimento por inatividade ganhou desfecho próprio. ### Valores novos | Campo | Valor novo | O que significa | | ----- | ---------- | --------------- | | `status` | **`EXPIRED`** | Venceu por inatividade — a pessoa não voltou dentro da janela. **Terminal.** Não é `REJECTED` (ninguém julgou) nem `CANCELLED` (ela não desistiu) | | `next_action` | **`OPEN_WEBVIEW`** | Submetido, mas a captura não aconteceu: reabra chamando `POST /onboarding/{id}/submission` de novo (idempotente), que devolve `webview_url` nova | ⚠️ **`status` não é enum no OpenAPI** (está tipado como `string`), então `EXPIRED` **não aparece** na referência gerada. Quem trata status por `switch` precisa acrescentá-lo à mão — e quem tem `default` caindo em erro genérico vai vê-lo primeiro em produção. ### ⚠️ Atenção para o app `UNDER_REVIEW` deixou de significar sempre "aguarde". Com `next_action: OPEN_WEBVIEW`, o app deve **reabrir a captura** em vez de mostrar tela de espera — antes disso, o usuário ficava olhando "em análise" enquanto o cadastro caminhava para a morte. O número de reaberturas é limitado (tunável, default 3); ao estourar, aí sim vira reprovação de verdade. ## Resumo de esforço | Categoria | Qtd de mudanças | Complexidade | | ------------------------------------------------------------------------ | --------------- | --------------------------------------------- | | Campos renomeados (padrão de nomes) | ~72 | Média (atualizar parsing em múltiplos fluxos) | | Campos removidos | ~30 | Baixa (remover referências) | | Campos adicionados | ~140 | Baixa (consumir opcionalmente) | | Enums alterados (guarantor, refund_reason, pix_key_type) | 3 | Baixa | | Enums tipados novos (type, direction, status, qrcode_type, account_type) | 5 | Média (substituem strings livres) | | URLs renomeadas (Boletos + Pix + Onboarding + MFA) | 18 | Baixa (find & replace) | | Method HTTP alterado (POST→DELETE/PUT/PATCH) | 5 | Baixa | | Tipo de campo alterado (number→string, string→boolean, enum) | 5 | Baixa | | Estrutura alterada (QR code flat, from/to nullable, discount→array) | 6 | Média | | Campos condicionais por tipo de conta (PAYMENT vs CHECKING) | 3 | Média (account_digit, account_number formato) | | Novo endpoint (refresh QR code de chave Pix) | 1 | Baixa (aditivo) | | Endpoint consolidado (perfil V1+V2 → V2) | 1 | Média (estrutura do response mudou) | | Endpoint removido (/memberships/me/v2) | 1 | Baixa (usar /memberships/me) | | ActionPolicy alterada (APPROVE → REQUEST nos POST) | 5 | Alta (step-up e role mudaram) | | Campo `approval` adicionado nos POST (execução direta) | 5 | Média (opcional, retrocompatível se omitido) | | Novo status `AWAITING_APPROVAL` | 1 | Alta (apps devem tratar novo status) | | Step-up por actor type (PARTNER sem PIN) | 10 | Média (PARTNER envia só TOTP) | | Status HTTP 422 → 403 em erros de autorização | 5 endpoints | Baixa (403 já constava no OpenAPI dos 5) | > **Nota para contas tipo PAYMENT:** Em TEF, TED e Pix transfer por dados bancários, o campo `account_number` deve conter o número completo com dígito (ex: 02452282) e `account_digit` deve ser omitido. Para CHECKING/SAVINGS, `account_number` é sem dígito e `account_digit` é obrigatório.