Lumedocs

Changelog

Toda mudança no contrato da API aparece aqui, com data.

Próxima versão

  • mudouX-Client-Location deixou de ser opcional nas operações que passam pelo provedor financeiro: ele a exige em toda chamada feita em nome da pessoa. Ausente ou mal formada, continua sem 400, mas a operação não sai e responde 503 PROVIDER_ERROR com details.reason LOCATION_REQUIRED, sem nada enviado ao banco: permita a localização e repita. A leitura que só complementa com o provedor (o saldo e as listas) leva a localização quando o cliente já a tem e, sem ela, segue com o dado do Lume. No Pix retido para análise, a localização do pedido fica guardada, com 4 casas, até a decisão (no máximo 72 horas).
  • novoTarifas por serviço (funcionalidade service_fees, em construção; só existe onde há internal_transfer). GET /v1/fees devolve a tabela vigente para o público da conta (PF ou PJ), sempre com os oito serviços do catálogo (PIX_OUT, PIX_IN_QR, TED_OUT, INTERNAL_OUT, BILLET_ISSUE, BILLET_SETTLED, BILL_PAYMENT, TOPUP): preço fixo ou percentual, isenção por norma e o próximo preço já agendado. GET /v1/fees/quote, com service e amountCents, cota a tarifa de uma operação sem gravar nada: feeCents, totalCents, reason e o consumo da cesta do plano em planUsage. As duas servem à sessão e à chave de API com accounts:read, que passa a abri-las. Desligada, 403 FEATURE_DISABLED, e nenhuma operação cobra tarifa.
  • mudouCom service_fees ligada, POST /v1/pix/transfers e POST /v1/pix/brcode/pay por chave de API exigem expectedFeeCents, a tarifa cotada em GET /v1/fees/quote: sem ele, 422 INVALID_REQUEST antes do segundo fator, nada reservado e a Idempotency-Key livre. Na sessão o campo é opcional, e vale também em POST /v1/ted/transfers, POST /v1/billets/pay e POST /v1/topups. Tarifa real maior que a enviada responde 409 CONFLICT com details.reason FEE_CHANGED (details.feeCents, details.expectedFeeCents e details.feeReason) antes de reservar qualquer valor. Essa recusa não fica gravada sob a Idempotency-Key: cote de novo e repita com a mesma chave e um novo X-Step-Up. Saldo que cobre o valor mas não a tarifa responde 422 INSUFFICIENT_FUNDS com details.amountCents, details.feeCents e details.totalCents, e details.pendingFeesCents quando há tarifa de entrada pendente na conta.
  • novoA tarifa entra no extrato como lançamento próprio (kind TARIFF, com feeOf apontando para a operação que a gerou) e é estornada junto quando a operação falha (kind REVERSAL, também com feeOf). Transaction ganhou feeCents (0 é isenta; ausente é sem decisão de tarifa), feeTransactionId, feeReason (EXEMPT_BY_RULE, COVERED_BY_PLAN, TABLE ou FREE) e feeStatus (CHARGED, PENDING, REVERSED ou FAILED); GET /v1/transactions/{id} traz também fee, com o detalhe.
  • mudouO X-Step-Up com purpose "transfer" passa a valer também pela soma do dia: o envio que leva a soma do dia a R$ 1.000,00 exige o segundo fator, ainda que ele mesmo fique abaixo desse valor, e responde 403 STEP_UP_REQUIRED sem reservar nada. No Pix, a soma junta o envio por chave, por agência e conta, por QR Code e a devolução; o pagamento de contas e a recarga têm cada um a sua soma. GET /v1/limits ganhou stepUpDailyThresholdCents, o teto da soma, que a instalação pode configurar.
  • novoGET /v1/pix/lookup devolve recipientRef, uma referência opaca do titular mostrado; ausente quando o arranjo não permite provar o titular. Repita-a em expectedRecipientRef em POST /v1/pix/transfers (só com key) e em POST /v1/schedules/pix: se a chave tiver passado a outro titular, a operação é recusada com 409 CONFLICT e details.reason RECIPIENT_CHANGED, ou RECIPIENT_UNVERIFIED quando o titular não pôde ser confirmado, sem nada reservado. A recusa não fica gravada sob a Idempotency-Key: consulte a chave, mostre o titular novo e repita com o recipientRef novo e um novo X-Step-Up. Na chave de API o campo é opcional e recomendado; ausente, o envio não confere o titular.
  • mudouPOST /v1/ted/transfers: a janela passou a ser das 08h às 16h30 em dias úteis (antes, das 06h30), e o details.window da recusa fora da janela traz "08:00-16:30". Destino na própria instituição do banco parceiro, que só leva TED para outras instituições, é recusado com 422 INVALID_REQUEST e details.field bankIspb: para essa conta, use Pix.
  • mudouURLs base novas: https://sandbox.api.lumecoding.com no sandbox e https://api.lumecoding.com em produção, no lugar de sandbox.api.lume.com.br e api.lume.com.br. Os prefixos da chave (lume_sk_sandbox_ e lume_sk_live_) não mudam. O suporte a desenvolvedores passa a ser https://docbank.lumecoding.com e [email protected].
  • novoIdempotency-Key é lembrada por 90 dias a partir da primeira requisição. Repetir depois disso conta como operação nova.
  • mudouWebhooks para a sua URL: conta que não está ativa não recebe evento. Com a conta bloqueada ou ainda em análise, os eventos ficam guardados, sem envio e sem contar tentativa, e começam a sair em até 15 minutos depois que a conta volta a ficar ativa. Conta encerrada: os eventos são abandonados sem envio.
  • novotransaction.updated passa a cobrir a tarifa cobrada ou estornada (TARIFF e REVERSAL, na conta que pagou) e o repasse de tarifa recebido ou estornado (na conta de destino), e data.kind passa a ser um valor de TransactionKind. TransactionKind ganhou FEE_SHARE_RECEIVED, o repasse de uma tarifa ou mensalidade que a instituição rateia com a conta (entrada, COMPLETED, descrição "Repasse · ...", sem counterparty: o pagador nunca aparece), e FEE_SHARE_REVERSED, o estorno dele (saída). O evento do repasse leva só id, tipo, estado e valor do lançamento do destino.
  • novoTransactionKind ganhou os lançamentos do cartão pré-pago: CARD_PURCHASE (compra, saque ou pagamento com o cartão: saída, com o estabelecimento em counterparty.name), CARD_REFUND (estorno de uma compra: entrada) e CARD_FEE (tarifa de saque do emissor, à parte da compra: saída). Todos COMPLETED e lançados uma única vez por transação do emissor, mesmo que o aviso se repita. A compra que o emissor já autorizou entra mesmo que o saldo fique negativo; a recusada não vira lançamento.
  • mudouTransaction.counterparty.pixKey vem sempre mascarada, na mesma forma da consulta de chave, e vazia quando o destino não foi uma chave Pix (TED, QR dinâmico, Pix por agência e conta, boleto).
  • mudouGET /v1/me: com provedor financeiro que mantém a conta, account.branch e account.number são a agência e o número do provedor, e vêm vazios enquanto ele não os informa (numberPending true, cadastro em análise) ou quando não puderam ser lidos agora (numberUnavailable true: tente de novo). account ganhou accountType (CHECKING, SAVINGS, PAYMENT ou SALARY) e bank (ispb, code e name, pela lista oficial de participantes do Banco Central).
  • novoCartões, só com sessão de cliente (nenhuma rota aceita chave de API): GET e POST /v1/cards, POST /v1/cards/terms/{termId}/accept, POST /v1/cards/onboarding, PATCH /v1/cards/{id}/block, POST /v1/cards/{id}/cancel, POST /v1/cards/{id}/secure-view, POST /v1/cards/{id}/reveal e GET /v1/cards/{id}/transactions. model diz o produto da instalação: CREDIT, o crédito com fatura, ou PREPAID, o pré-pago de um emissor parceiro, que debita o saldo. No pré-pago o titular aceita o termo, passa pela análise do emissor (até 3 dias úteis) e pede o cartão virtual com Idempotency-Key obrigatória; número, validade e código de segurança só aparecem na página segura do emissor, por uma URL de uso único (secure-view). Desbloquear, cancelar, secure-view e reveal exigem X-Step-Up com purpose "card"; bloquear não. Cancelar exige também Idempotency-Key.
  • novoError.code ganhou os códigos do cartão: CARD_TERMS_REQUIRED, CARD_ELIGIBILITY_REQUIRED e CARD_KIND_UNAVAILABLE (422); CARD_BLOCKED_BY_INSTITUTION, CARD_NOT_ACTIVE, CARD_USE_REVEAL e CARD_USE_SECURE_VIEW (409).
  • novoPortabilidade e reivindicação de chave Pix pelo titular (funcionalidade pix_key_claims, em construção e desligada por padrão; só existe com pix_keys). POST /v1/pix/keys/portability traz de outra instituição uma chave CPF, CNPJ, e-mail ou telefone (a aleatória não se porta: 422). POST /v1/pix/keys/{id}/claim age sobre o processo em andamento com action ACCEPT, REJECT, OPEN, CANCEL ou COMPLETE. Só com sessão de cliente, com Idempotency-Key e X-Step-Up com purpose "pix_key" em toda chamada. Respondem 202, e o andamento vem pela lista de chaves. UNKNOWN é a outra ponta sem resposta a tempo: não repita; um novo pedido para a mesma chave é 409 CONFLICT até o andamento chegar.
  • mudouGET /v1/pix/keys, com pix_key_claims ligada e na sessão, traz claimActions (as ações que cabem à chave agora) e claimRequest (o pedido do titular ainda sem desfecho). Com a funcionalidade ligada, a chave em ACTION_REQUIRED se resolve em POST /v1/pix/keys/{id}/claim; desligada, o statusDetail continua orientando a procurar o atendimento.
  • novoO plano passa a ser uma cesta de serviços. GET /v1/subscription-plans traz quotas (a cota de cada serviço do catálogo por período pago; included 0 e unlimited falso é não incluído), planVersion (a vigência da composição) e scheduledQuotas; o plano de GET /v1/subscription traz quotas. POST /v1/subscription e POST /v1/subscription/plan-change aceitam expectedPlanVersion, opcional: composição vigente diferente responde 409 com details.reason PLAN_CHANGED e details.currentPlanVersion. GET /v1/subscription/usage mostra o período pago corrente e, por serviço, o incluído, o usado, o que resta e a tarifa avulsa do excedente (excessPrice), além de feesPaidInPeriodCents. Só de sessão.
  • novoDia de cobrança escolhido pelo titular: POST /v1/subscription/billing-day (day de 1 a 28) agenda a troca para a próxima mensalidade ainda não gerada, que sai proporcional, e POST /v1/subscription/billing-day/cancel a desfaz. Uma troca por período, e nada é debitado na hora. Os dois exigem sempre Idempotency-Key e X-Step-Up com purpose "subscription". Subscription ganhou pendingBillingDay, billingDayChangeFrom, billingDayChangeAmountCents, canChangeBillingDay, billingDayChangeBlockedReason e graceUntil; com troca pendente, nextAmountCents é a cobrança proporcional. SubscriptionCharge ganhou kind (MONTHLY ou PRORATA) e periodStart. Nas adesões novas, billingDay vai de 1 a 28.
  • mudouConta de empresa passa a ter planos: GET /v1/subscription-plans mostra os planos PJ à empresa e os PF à pessoa física. GET /v1/subscription não emite mais blockedReason ACCOUNT_TYPE.
  • mudouAgendamentos com service_fees ligada: o Pix agendado (POST /v1/schedules/pix) e o pagamento de contas que o Lume executa na data pagam a tarifa vigente no dia da execução, cobrada junto; nada é cobrado ao agendar, e na data o saldo precisa cobrir valor e tarifa, senão o agendamento vira failed sem débito. No agendamento de boleto feito no banco parceiro (só bill_schedule ligada), a tarifa é reservada com o valor no dia de agendar e devolvida no cancelamento ou na falha: POST /v1/schedules/billet aceita expectedFeeCents, e tarifa maior responde 409 com details.reason FEE_CHANGED, sem nada reservado.
  • mudouPOST /v1/billets: a conta tem teto diário de emissão, em quantidade de boletos, valor somado e pagadores distintos no dia. Acima dele, 422 LIMIT_EXCEEDED com a mensagem dizendo qual teto, sem chamar o arranjo. A recusa fica gravada sob a Idempotency-Key: no dia seguinte, emita com outra chave.
  • corrigidoPOST /v1/approvals/{id}/approve (aprovação conjunta da conta PJ, funcionalidade approvals) passa a constar no contrato. Só de sessão, com X-Step-Up purpose "transfer" e selfie quando a instalação a exige: executa na hora o Pix ou o pagamento de boleto pedido por outro representante e responde 200 com o desfecho. Com service_fees ligada, quem aprova manda em expectedFeeCents a tarifa cotada; ausente vale zero, e tarifa da execução maior responde 409 com details.reason FEE_CHANGED, com o pedido ainda esperando.
  • corrigidoRecarga de celular (funcionalidade topup) passa a constar no contrato: GET e POST /v1/topups, POST /v1/topups/offers e GET /v1/topups/{id}. Só de sessão. POST /v1/topups exige Idempotency-Key, responde 202 e devolve em transaction a reserva, com a tarifa TOPUP. Sem fornecedor de recarga configurado, a lista responde available false e as demais rotas, 503.
  • novoBiometria facial do titular: GET /v1/security/biometrics (situação, valor a partir do qual a selfie é exigida e troca agendada), POST /v1/security/biometrics (cadastra ou troca, com X-Step-Up purpose "biometrics") e DELETE /v1/security/biometrics/pending (cancela a troca agendada). Só de sessão. Sem rosto cadastrado, vale na hora (201). Com rosto cadastrado, a troca na hora exige o X-Step-Up emitido com selfie; só com o código, ela fica agendada para 24 horas depois (202, com effectiveAt). O titular recebe um e-mail em toda troca.
  • novoOs banners de GET /v1/marketplace ganharam theme, backgroundColor e textColor (cores já resolvidas, com contraste de pelo menos 4,5:1), imageUrl e imagePosition (lado ou fundo); nulos ou ausentes, o visual padrão. imageUrl é o caminho relativo à API de GET /v1/marketplace/banners/{id}/image, que serve a imagem em PNG sem sessão, para uso direto num img, com ETag e 304; com marketplace desligada, 403 FEATURE_DISABLED.
  • novoGET /v1/app/versions, pública e sem credencial como GET /v1/features: por plataforma (ios, android), a versão mais nova do app anunciada, a mínima que ainda opera e o endereço para atualizar. Plataforma não configurada não vem; sem nenhuma, o corpo é {}.
  • novoTrês funcionalidades novas no catálogo de GET /v1/features: business_opening_own (abertura de empresa MEI e EI na tela própria; em construção, desligada por padrão, só com account_opening), pix_key_claims (portabilidade de chave Pix pelo titular; em construção, desligada por padrão, só com pix_keys) e service_fees (tarifas por serviço; em construção, só com internal_transfer). accountOpening ganhou emailConfirmation: falso só em instalação de teste com a confirmação do e-mail desligada; ausente é verdadeiro.
  • mudouPOST /v1/auth/login e POST /v1/auth/mfa podem responder 200 sem sessão: o titular que ainda está abrindo conta (contas em abertura, cadastro não enviado) recebe onboarding true, com onboardingToken, mode e stage, e segue para a abertura. O token só alcança as rotas de /v1/onboarding. Comportamento provisório.
  • novoPOST /v1/onboarding/resume, pública: com o documento e a senha escolhida na abertura, e o código do autenticador para quem já o configurou, devolve um onboardingToken novo para continuar a abertura parada na coleta. Não abre sessão nem dá acesso à conta. Abertura já enviada responde 409; documento inexistente responde como senha errada (401), e as tentativas contam com as do login (429). Provisória.
  • mudouPOST /v1/onboarding: os campos de texto ganharam tamanho máximo (name 120, document 24, email 254, phone 32, city 80, no máximo 10 representatives), e passar dele é 422 INVALID_REQUEST. O documento de quem ainda está abrindo conta responde 409 com details.reason ONBOARDING_IN_PROGRESS (siga por POST /v1/onboarding/resume), ou 201 com onboarding true quando a senha é a mesma do cadastro e não há autenticador. Nos modos do provedor, celular ou e-mail já cadastrados lá respondem 409 CONFLICT com details.field (phone ou email), e a confirmação do e-mail é consumida.
  • novoAbertura própria de empresa MEI ou EI (funcionalidade business_opening_own): POST /v1/onboarding aceita CNPJ com businessType MEI ou EI e exatamente um representante (LTDA, SA e TS: 422). POST /v1/onboarding/documents envia o documento da empresa (kind LEGAL_DOCUMENTS, PDF em base64 de até 3 MB), que vai direto ao provedor e não fica guardado no Lume; até 10 envios por abertura em 24 horas (429). PUT /v1/onboarding/profile ganha, na empresa, birthDate e occupation do representante e business, com a faixa de faturamento e o endereço comercial. GET /v1/onboarding traz documents e businessType para a tela retomar.
  • mudouGET /v1/onboarding/terms devolve urls, a lista dos documentos de termos a mostrar e aceitar (até 5); url repete o primeiro. POST /v1/onboarding/complete aceita termsUrls, a lista inteira e na mesma ordem; termsUrl sozinho só vale com um documento, e com mais de um responde 422. A conclusão exige uma sessão de biometria pedida em POST /v1/onboarding/biometrics/session para esta abertura (409 sem ela).
  • mudouPUT /v1/onboarding/profile, pessoa física: birthDate, occupation e business são recusados (400). Mãe, PEP, endereço e renda, depois de aceitos pelo provedor, passam a ficar gravados também no Lume; o nome social vai só ao provedor. O primeiro envio pede ao provedor o processo biométrico, e sem a biometria do provedor configurada na instalação responde 503.
  • mudouTrava de tentativas (429 TOO_MANY_ATTEMPTS) nas etapas por identificador público (senha no login e recuperação de senha): o documento sozinho não trava mais. Trava, e escalona, a combinação documento e origem (endereço) de quem erra, e de outra origem o titular continua entrando. Os erros somados de todas as origens avisam o titular por e-mail a partir do segundo degrau. O erro da senha atual em POST /v1/auth/password conta para a trava do login a partir da mesma origem. Nas etapas que exigem a posse de um fator, a trava continua por identidade.
  • mudouPOST /v1/auth/password/reset: quem ainda não é cliente de fato (sem autenticador, com todas as contas em abertura e o cadastro não enviado) troca a senha só com o código do contato, e totpCode pode ir vazio. POST /v1/auth/password/setup/request e POST /v1/auth/password/reset/request não enviam código novo enquanto o anterior vale, com teto de 2 por hora e 3 por dia ao mesmo destino.
  • mudouPOST /v1/sandbox/keys ganhou teto por endereço de origem, além das cinco chaves por e-mail por dia: dez de imediato e depois uma por minuto (429 com Retry-After). company (até 120 caracteres) e label (até 80) não aceitam quebra de linha nem caractere de controle.
  • novoGET /v1/security/events: kind ganhou CARD_TERMS (a resposta ao termo do cartão), TRANSACTION_HELD e SCHEDULE. Tipo novo pode aparecer: ignore o que não conhecer.
  • novoWebhooks para a sua URL: o banco cadastra, a seu pedido e com a aprovação de um segundo operador, um endereço https que recebe cada mudança de estado de transação da conta como transaction.updated (e o evento de teste ping). Corpo magro, sem dado da contraparte, com amountCents no mesmo sinal de GET /v1/transactions/{id}. Assinatura HMAC-SHA256 em X-Lume-Signature sobre "<X-Lume-Timestamp>.<corpo>", id do evento em X-Lume-Event-Id para deduplicar, retentativa por até 24 horas. TLS 1.2 ou superior; o banco apresenta certificado de cliente para quem exige mTLS, e aceita a CA própria do seu servidor informada no cadastro. Descritos na seção webhooks do contrato.
  • mudouChave de API de conta bloqueada ou encerrada responde 403 FORBIDDEN a toda chamada. A chave não é revogada: reativada a conta, ela volta a valer.
  • novoChave de API com lista de origens: a chave emitida com endereços ou redes de origem responde 403 FORBIDDEN a chamadas de fora da lista. O ritmo por chave vale até 120 requisições por minuto.
  • novoQuatro módulos novos no catálogo de GET /v1/features: subscriptions (planos e assinaturas), merchant_portal (portal do estabelecimento), affiliate_network (rede de indicação) e marketplace (benefícios e vitrine). Cada um é uma funcionalidade que a instalação liga ou desliga; todos nascem desligados, em construção. Desligado, as rotas do módulo respondem 403 FEATURE_DISABLED com details.feature dizendo qual. subscriptions só existe onde há internal_transfer; affiliate_network só com referrals ligada.
  • novoAssinaturas (funcionalidade subscriptions): GET /v1/subscription-plans, GET e POST /v1/subscription, GET /v1/subscription/charges e POST /v1/subscription/cancel. Só de sessão: chave de API recebe 403 FORBIDDEN. Aderir debita a primeira mensalidade do saldo na hora, sem débito parcial (422 INSUFFICIENT_FUNDS); aderir e cancelar exigem sempre Idempotency-Key e X-Step-Up com purpose "subscription". expectedAmountCents diferente do preço em vigor responde 409 com details.reason PRICE_CHANGED. A mensalidade aparece no extrato como TARIFF. Com a funcionalidade desligada, ver o plano vivo (GET /v1/subscription) e cancelá-lo continuam valendo.
  • novoPOST /v1/auth/step-up aceita purpose "subscription", o da adesão e do cancelamento de plano.
  • novoRede de indicação (funcionalidades referrals e affiliate_network): GET /v1/referrals/network (resumo até dois níveis), GET /v1/referrals/network/direct (indicados diretos, paginado) e GET /v1/referrals/commissions (ganhos e totais por situação). Só leitura e só de sessão. O indicado indireto aparece só em número, nunca com nome. Nada aqui credita saldo: o cashback pago aparece no extrato como CASHBACK.
  • corrigidoGET /v1/referrals (código, caminho do convite e indicações de quem está na sessão) passa a constar no contrato. A rota já respondia; só de sessão, com a funcionalidade referrals.
  • novoPortal do estabelecimento (funcionalidade merchant_portal): GET /v1/merchant/dashboard, GET /v1/merchant/sales, GET /v1/merchant/sales/{id} e GET /v1/merchant/receivables. Só leitura e só de sessão. Vendas e recebíveis são uma cópia do adquirente, atualizada por rotina (merchant.lastSyncAt); do cartão, no máximo a bandeira e os quatro últimos dígitos. Conta ainda não credenciada recebe 404 NOT_FOUND.
  • novoVitrine de benefícios (funcionalidade marketplace): GET /v1/marketplace, com banners, ofertas de parceiros por categoria e o link da loja, já filtrados para a conta da sessão. Só leitura e só de sessão. Nada move dinheiro: o cashback de oferta é o que o parceiro promete, e o banco não credita valor nenhum.
  • novoGET e PUT /v1/notifications/whatsapp: o aceite do titular para receber avisos pelo WhatsApp. Só da sessão do próprio titular. A caixa nasce desmarcada; sair nunca é recusado; aceitar com o canal desligado nesta instalação responde 409. Não é funcionalidade do catálogo: available diz se o canal está ligado.

1.2.0

  • novoPOST /v1/transactions/{id}/refund devolve, total ou parcialmente, um Pix recebido a quem pagou. Só com sessão de cliente e Idempotency-Key obrigatório; responde 202 com a devolução em PROCESSING, e o desfecho vem pelo status da transação. Nunca passa do valor recebido, conta nos limites de Pix e pede X-Step-Up pelo valor, como um envio. Desligada junto com a funcionalidade pix_transfer.
  • novoTransactionKind ganhou PIX_REFUND_SENT (a devolução que a conta enviou: saída) e PIX_REFUND_RECEIVED (a devolução que a conta recebeu de um Pix que enviou: entrada). Transaction ganhou refundOf, o Pix de origem da devolução, e refundableCents, quanto de um Pix recebido ainda pode ser devolvido.
  • novoTransactionKind ganhou TED_RECEIVED: a TED que outra instituição enviou à conta, com o remetente em counterparty (documento sempre mascarado). Só aparece depois que o banco parceiro libera o valor, e uma única vez.
  • novoBillet ganhou compensatedAt (o pagador pagou, mas o valor ainda não está na conta) e settlements, com valor, data e transação de cada pagamento creditado. Um título pago em parte continua REGISTERED e vai a PAID só quando quitado.
  • mudouBillet.paidAmountCents passa a ser o acumulado recebido, e não só o valor de uma liquidação única. Para títulos creditados a partir desta versão, é a soma de settlements; os anteriores trazem o valor sem settlements. POST /v1/billets/{id}/cancel responde 409 também para título já pago pelo pagador e ainda não liquidado (compensatedAt preenchido).

1.1.0

  • novoGET /v1/features lista as funcionalidades ligadas nesta instalação e se ela abre conta. Pública, sem credencial: a tela de entrada consulta antes do login.
  • novoCódigo FEATURE_DISABLED (HTTP 403, com details.feature): a operação pertence a uma funcionalidade desligada nesta instalação. PIX, boleto e pagamento de contas podem respondê-lo; boleto com pixEnabled também, quando o PIX no boleto está desligado.
  • novoCabeçalho opcional X-Client-Location (latitude,longitude) nas operações de conta, PIX e boleto. O provedor financeiro o pede para o antifraude dele; ausente ou mal formado, a operação segue sem localização.
  • novoPOST /v1/ted/transfers envia TED para conta de outra instituição, com os dados do favorecido digitados. Só com sessão de cliente, Idempotency-Key obrigatório e X-Step-Up com purpose "ted" em toda TED. Só em dias úteis, das 06h30 às 16h30: fora da janela é recusada antes de qualquer débito. Responde 202; o desfecho vem pelo status da transação. GET /v1/limits já aplica tedDailyCents a ela.
  • novoPOST /v1/pix/brcode/pay paga um QR Code Pix (copia e cola), estático ou dinâmico, com Idempotency-Key. O servidor lê o código de novo na hora de pagar: o cliente manda o código e, quando o valor é dele, o valor. A transação tem kind PAYMENT_QRCODE. POST /v1/pix/brcode/parse passou a devolver qrType, amountEditable e document (sempre mascarado).
  • novoCobranças por QR Code: POST /v1/pix/qrcodes gera uma cobrança estática (valor fixo ou livre) ou dinâmica (valor e vencimento, uso único), GET /v1/pix/qrcodes lista as da conta com status OPEN, PAID, EXPIRED ou DELETED e o valor pago (paidCents), e DELETE /v1/pix/qrcodes/{id} exclui. Idempotency-Key obrigatório na criação; a chave Pix é da própria conta e a cidade vem do cadastro. Chave de API: pix:read para listar, pix:write para criar e excluir. A dinâmica só existe quando o provedor da instalação gera cobrança; sem ele, 501.
  • mudouPOST /v1/pix/brcode passa a registrar a cobrança estática pelo mesmo caminho de POST /v1/pix/qrcodes e compartilha com ele o espaço de Idempotency-Key da conta: a mesma chave com pedido diferente é 409 IDEMPOTENCY_KEY_REUSED. A cidade do pedido é ignorada; vale a do cadastro.
  • novoGET /v1/accounts/balance traz blockedCents (valor bloqueado por ordem judicial ou cautelar) e suspenseCents, lidos do provedor quando ele informa. Ausente não é zero: é "não sei". Nenhum dos dois entra em balanceCents, e asOf diz de quando é o dado mais antigo.
  • novoChaves PIX ganharam status (ACTIVE, PENDING, ACTION_REQUIRED, REMOVED) e statusDetail; a lista consulta o DICT pelo provedor. POST /v1/pix/keys aceita type EVP, sem key, para pedir uma chave aleatória, e verificationId para e-mail e telefone; CPF e CNPJ só do próprio titular; o teto é de 5 chaves (pessoa física) ou 20 (pessoa jurídica), e passar dele é 409 CONFLICT. A resposta da criação é a chave completa. A exclusão vale para as cinco espécies. Cadastro e exclusão entram no histórico de segurança com kind PIX_KEY.
  • novoExtrato: kind PIX_RECEIVED (Pix recebido, com o pagador em counterparty e o endToEndId) e kinds BLOCKAGE e BLOCKAGE_RELEASE (valor bloqueado por ordem externa e devolvido ao saldo no desbloqueio; o número do processo nunca aparece).
  • novoCobrança por boleto: GET e POST /v1/billets, GET /v1/billets/{id} e POST /v1/billets/{id}/cancel. Emitir não move saldo; o crédito chega como BILLING_RECEIVED no extrato quando o título é pago. Só com sessão de cliente (veja abaixo).
  • novoNotificações do provedor: POST /v1/webhooks/{provider}, que o provedor financeiro chama (não a sua integração), e GET /health e /ready. O esquema da Azify está descrito na rota: HMAC-SHA256 de JSON.stringify(corpo) + x-timestamp + x-nonce, e resposta assinada {"success":true,"message":"ok"}.
  • mudouA cobrança por boleto, POST /v1/ted/transfers, POST /v1/auth/step-up e POST /v1/transactions/{id}/review declaram security só de sessão (Authorization: Bearer). Chave de API nunca as alcançou: recebia 403 FORBIDDEN, e agora o contrato diz isso, sem escopo novo.
  • mudouGET /v1/pix/lookup devolve document sempre mascarado e responde 403 em conta bloqueada. POST /v1/pix/transfers e POST /v1/pix/brcode/pay respondem 503 PROVIDER_ERROR, antes de qualquer débito, quando o provedor da instalação exige sessão de cliente com aparelho identificado e a chamada veio por chave de API ou por sessão sem aparelho.
  • corrigidoError.code lista BIOMETRIC_REQUIRED (403: valor alto confirmado só com o código; a instalação exige também a selfie) e APPROVAL_REQUIRED (422: acima da alçada de aprovação conjunta da conta da empresa). O servidor já os emitia. POST /v1/auth/step-up documenta o campo selfie, que é como se resolve BIOMETRIC_REQUIRED, e o purpose "ted".
  • corrigidoGET /v1/security/events lista todos os kind que o servidor grava: ACCOUNT_STATUS, BIOMETRICS, PIX_KEY, INCOME_REPORT_EMAIL, ACCOUNT_ACCESS, CARD_ISSUED, CARD_STATUS, CARD_REVEALED e APPROVAL, além dos sete que já constavam. Tipo novo pode aparecer: ignore o que não conhecer.

1.0.0

  • novoChaves de API para integração servidor-a-servidor, no cabeçalho X-API-Key. Ambiente embutido no próprio texto da chave: uma chave de sandbox não funciona em produção nem o contrário.
  • novoPOST /v1/sandbox/keys emite chave e provisiona uma conta de testes isolada, com saldo fictício e segredo TOTP próprio. Sem cadastro e sem aprovação.
  • novoPortal do desenvolvedor no ar: referência gerada do openapi.yaml, console de testes contra o sandbox, coleção do Postman e llms.txt.
  • corrigidoX-Step-Up e X-API-Key passaram a constar em Access-Control-Allow-Headers. Sem eles, o navegador barrava a confirmação de segundo fator na verificação prévia, antes de a requisição sair da máquina do cliente.
  • novoPrimeira versão pública da v1: conta, extrato, PIX (chaves, consulta no DICT, transferência e BR Code), beneficiários, limites e eventos de segurança.