Referência Técnica

Mapa de endpoints — API v2

Visão geral das rotas públicas documentadas no portal (só paths /api/v2 e /api/v1 de terminais)

Visão resumida das rotas públicas da API Nuvende. O contrato detalhado (schemas, exemplos) está na Referência API. Guias de fluxo na documentação técnica.

Autenticação: Bearer token obtido em login, com scopes adequados. A conta da operação é a associada ao token: não envie header de conta.

Auth

Método	Path	Técnica
POST	`/api/v2/auth/login`	Login
POST	`/api/v2/auth/logout`	Logout
POST	`/api/v2/auth/refresh`	Refresh
POST	`/api/v2/auth/user`	Usuário

Contas

Método	Path	Scope	Técnica
GET	`/api/v2/contas`	`contas.read`	Dados da conta
GET	`/api/v2/contas/saldo`	`contas.saldo.read`	Saldo
GET	`/api/v2/contas/extrato`	`contas.extrato.read`	Extrato
GET	`/api/v2/contas/chaves`	`contas.chaves.read`	Chaves Pix

Cobranças Pix (QR dinâmico, Cobv e webhooks)

Método	Path	Scope	Técnica
GET	`/api/v2/cobranca/cob`	`cob.read`	Listar Cob
POST	`/api/v2/cobranca/cob`	`cob.write`	Criar Cob (POST)
PUT	`/api/v2/cobranca/cob/{txid}`	`cob.write`	Criar QR Code
GET	`/api/v2/cobranca/cob/{txid}`	`cob.read`	Consultar QR Code
GET	`/api/v2/cobranca/cobv`	`cobv.read`	Listar Cobv
PUT	`/api/v2/cobranca/cobv/{txid}`	`cobv.write`	Criar Cobv
GET	`/api/v2/cobranca/cobv/{txid}`	`cobv.read`	Consultar Cobv
PATCH	`/api/v2/cobranca/cobv/{txid}`	`cobv.write`	Atualizar Cobv
GET	`/api/v2/cobranca/webhooks/{chave}`	`webhooks.read`	Webhooks
PUT	`/api/v2/cobranca/webhooks/{chave}`	`webhooks.write`	Webhooks (cria; máx. 3/evento)
PATCH	`/api/v2/cobranca/webhooks/{id}`	`webhooks.write`	Atualiza URL/autorização
DELETE	`/api/v2/cobranca/webhooks/{id}`	`webhooks.write`	Remove pelo `id`

Webhook Pix: eventos recebimento, pagamento, pagamento-falha e devolucao. PUT cria (não upsert); no evento, POST para todas as URLs daquele evento. Guias: Recebimento · Pagamento / falha.

Limitação (Cobv): rotas Cobv exigem cobv.read e cobv.write. Enquanto esses scopes não estiverem vinculados à aplicação no ambiente, o token não os carrega e a API tende a 403 Insufficient scope. Não use cob.* no lugar.

Pagamentos Pix (cash-out)

Método	Path	Scope	Técnica
GET	`/api/v2/pix/pagamentos`	`pix.read`	Listar
GET	`/api/v2/pix/pagamentos/{id}`	`pix.read`	Consultar
POST	`/api/v2/pix/pagamentos/manual`	`pix.write`	Manual
POST	`/api/v2/pix/pagamentos/chave`	`pix.write`	Por chave
POST	`/api/v2/pix/pagamentos/qrcode`	`pix.write`	Por QR Code
POST	`/api/v2/pix/pagamentos/confirmar`	`pix.write`	Confirmar

Devoluções Pix

Método	Path	Scope	Técnica
GET	`/api/v2/pix/devolucoes`	`pix.refunds.read`	Listar
GET	`/api/v2/pix/{e2eid}/devolucoes/{txid}`	`pix.refunds.read`	Consultar
PUT	`/api/v2/pix/{e2eid}/devolucoes/{txid}`	`pix.refunds.write`	Solicitar

Webhook de efetivação/falha: PUT /api/v2/cobranca/webhooks/{chave} com eventos: ["pagamento"] e/ou ["pagamento-falha"]. Ver Webhook de pagamento.

KYC

Método	Path	Scope
GET	`/api/v2/kyc/background-check/natural-person/{cpf}`	`kyc.background-check.natural-person`
GET	`/api/v2/kyc/background-check/legal-person/{cnpj}`	`kyc.background-check.legal-person`

Pagamentos via Terminais

Estabelecimentos (merchants), terminais POS, transações e comprovantes. Rotas CRUD em /api/v1/pagamentos/...; documentos em /api/v2/pagamentos/documents/. Token Mundo Digital com scopes merchants.*, terminals.* e transactions.* (login). Contrato na Referência API, grupo Pagamentos via Terminais.

Estabelecimentos

Guia: Estabelecimentos.

Método	Path	Scope	Referência
GET	`/api/v1/pagamentos/merchants`	`merchants.read`	Listar
POST	`/api/v1/pagamentos/merchants`	`merchants.write`	Cadastrar
PUT	`/api/v1/pagamentos/merchants/{id}`	`merchants.write`	Atualizar
DELETE	`/api/v1/pagamentos/merchants/{id}`	`merchants.write`	Excluir

Terminais

Guia: Terminais.

Método	Path	Scope	Referência
GET	`/api/v1/pagamentos/terminals`	`terminals.read`	Listar
POST	`/api/v1/pagamentos/terminals`	`terminals.write`	Criar
PUT	`/api/v1/pagamentos/terminals/{id}`	`terminals.write`	Atualizar

Transações

Guia: Transações.

Método	Path	Scope	Referência
GET	`/api/v1/pagamentos/transactions`	`transactions.read`	Listar
POST	`/api/v1/pagamentos/transactions`	`transactions.write`	Criar
GET	`/api/v1/pagamentos/transactions/{id}`	`transactions.read`	Exibir
PUT	`/api/v1/pagamentos/transactions/{id}`	`transactions.write`	Atualizar
DELETE	`/api/v1/pagamentos/transactions/{id}`	`transactions.write`	Excluir

Documentos (comprovante)

Guia: Impressão de comprovante.

Método	Path	Scope	Referência
POST	`/api/v2/pagamentos/documents/`	`transactions.write`	Criar
PUT	`/api/v2/pagamentos/documents/{id}`	`transactions.write`	Atualizar

Scope documentos: não existe documents.read nem documents.write no login. Criar e atualizar comprovantes exige transactions.write no token Mundo Digital (mesmo grupo de Pagamentos via Terminais).

BaaS: Plataforma {#baas-plataforma}

Rotas operadas com token da plataforma BaaS. Visão geral: Sobre o BaaS. Guia: Plataforma BaaS.

Status

Método	Path	Scope	Referência
GET	`/api/v2/baas/status`	sem scope	Status BaaS

Onboarding

Guia: Onboarding.

Método	Path	Scope	Referência
GET	`/api/v2/baas/onboardings/proposals`	`baas.onboarding-proposals.read`	Listar propostas
POST	`/api/v2/baas/onboardings/proposals`	`baas.onboarding-proposals.write`	Criar proposta
GET	`/api/v2/baas/onboardings/proposals/{proposalId}`	`baas.onboarding-proposals.read`	Consultar proposta
PATCH	`/api/v2/baas/onboardings/proposals/{proposalId}`	`baas.onboarding-proposals.write`	Atualizar proposta
POST	`/api/v2/baas/onboardings/proposals/{proposalId}/resend-email`	`baas.onboarding-proposals.write`	Reenviar e-mail
POST	`/api/v2/baas/onboardings/proposals/{proposalId}/resend-sms`	`baas.onboarding-proposals.write`	Reenviar SMS
POST	`/api/v2/baas/onboardings/{proposalId}/natural-persons`	`baas.onboarding-natural-persons.write`	Cadastrar PF
GET	`/api/v2/baas/onboardings/{proposalId}/natural-persons/{personId}`	`baas.onboarding-natural-persons.read`	Consultar PF
PATCH	`/api/v2/baas/onboardings/{proposalId}/natural-persons/{personId}`	`baas.onboarding-natural-persons.write`	Atualizar PF
POST	`/api/v2/baas/onboardings/{proposalId}/legal-persons`	`baas.onboarding-legal-persons.write`	Cadastrar PJ
GET	`/api/v2/baas/onboardings/{proposalId}/legal-persons/{personId}`	`baas.onboarding-legal-persons.read`	Consultar PJ
PATCH	`/api/v2/baas/onboardings/{proposalId}/legal-persons/{personId}`	`baas.onboarding-legal-persons.write`	Atualizar PJ
POST	`/api/v2/baas/onboardings/{proposalId}/legal-persons/{personId}/resend-email`	`baas.onboarding-legal-persons.write`	Reenviar e-mail PJ

Webhooks da plataforma

Guia: Webhooks da plataforma.

Método	Path	Scope	Referência
GET	`/api/v2/baas/seller-webhooks`	`baas.seller-webhooks.read`	Listar
POST	`/api/v2/baas/seller-webhooks`	`baas.seller-webhooks.write`	Criar
GET	`/api/v2/baas/seller-webhooks/{id}`	`baas.seller-webhooks.read`	Consultar
PATCH	`/api/v2/baas/seller-webhooks/{id}`	`baas.seller-webhooks.write`	Atualizar
DELETE	`/api/v2/baas/seller-webhooks/{id}`	`baas.seller-webhooks.write`	Excluir

Contratos (catálogo plataforma)

Método	Path	Scope	Referência
GET	`/api/v2/baas/contracts`	`baas.contracts.read`	Listar contratos

BaaS: Conta titular

Rotas operadas com token da conta BaaS. Guia: Conta BaaS.

Saldo e extrato

Método	Path	Scope	Referência
GET	`/api/v2/baas/balances`	`baas.balances.read`	Consultar saldo
GET	`/api/v2/baas/balances/period`	`baas.balances.read`	Saldo por período
GET	`/api/v2/baas/statements`	`baas.statements.read`	Consultar extrato

Chaves Pix

Guia: Gerenciamento de chaves.

Método	Path	Scope	Referência
GET	`/api/v2/baas/key-managements`	`baas.key-managements.read`	Listar chaves
POST	`/api/v2/baas/key-managements`	`baas.key-managements.write`	Criar chave
POST	`/api/v2/baas/key-managements/consult`	`baas.key-managements.read`	Consultar no DICT
POST	`/api/v2/baas/key-managements/verification-code`	`baas.key-managements.write`	Validar código
POST	`/api/v2/baas/key-managements/resend-code`	`baas.key-managements.write`	Reenviar código
POST	`/api/v2/baas/key-managements/{id}/store-after-verification`	`baas.key-managements.write`	Confirmar após verificação
DELETE	`/api/v2/baas/key-managements/{id}`	`baas.key-managements.write`	Excluir chave

Pix cash-in

Guia: Cobranças.

Método	Path	Scope	Referência
POST	`/api/v2/baas/pix/cash-in`	`baas.pix-cash-in.write`	Criar cobrança Pix
GET	`/api/v2/baas/pix/cash-in/{txid}`	`baas.pix-cash-in.read`	Consultar cobrança

Pix cash-out

Guia: Pagamentos.

Método	Path	Scope	Referência
POST	`/api/v2/baas/pix/payments/key`	`baas.pix-payments.write`	Pagamento por chave
POST	`/api/v2/baas/pix/payments/payload`	`baas.pix-payments.write`	Pagamento por payload

Pix devolução

Guia: Devoluções.

Método	Path	Scope	Referência
GET	`/api/v2/baas/devolutions`	`baas.pix-refunds.read`	Listar
GET	`/api/v2/baas/devolutions/{id}`	`baas.pix-refunds.read`	Consultar
POST	`/api/v2/baas/devolutions`	`baas.pix-refunds.write`	Solicitar

Boletos

Guia: Pagamentos de boletos.

Método	Path	Scope	Referência
GET	`/api/v2/baas/bankslip-payments/barcode/{barcode}`	`baas.bankslip-payments.read`	Consultar por código de barras
GET	`/api/v2/baas/bankslip-payments/review/{reference}`	`baas.bankslip-payments.read`	Revisar pagamento
POST	`/api/v2/baas/bankslip-payments/update/{reference}`	`baas.bankslip-payments.write`	Atualizar agendamento
POST	`/api/v2/baas/bankslip-payments/confirm/{reference}`	`baas.bankslip-payments.write`	Confirmar pagamento

Conta (limites e encerramento)

Guia: Conta titular.

Método	Path	Scope	Referência
GET	`/api/v2/baas/accounts/limits`	`baas.accounts.read`	Listar limites
POST	`/api/v2/baas/accounts/limits`	`baas.accounts.write`	Alterar limite
POST	`/api/v2/baas/accounts/close`	`baas.accounts.write`	Encerrar conta

Contrato da conta

Método	Path	Scope	Referência
GET	`/api/v2/baas/contracts/{contractId}`	`baas.contracts.read`	Consultar contrato

Webhooks da conta

Guia: Webhooks da conta.

Método	Path	Scope	Referência
GET	`/api/v2/baas/webhooks`	`baas.webhooks.read`	Listar
POST	`/api/v2/baas/webhooks`	`baas.webhooks.write`	Criar
GET	`/api/v2/baas/webhooks/{id}`	`baas.webhooks.read`	Consultar
PATCH	`/api/v2/baas/webhooks/{id}`	`baas.webhooks.write`	Atualizar
DELETE	`/api/v2/baas/webhooks/{id}`	`baas.webhooks.write`	Excluir
POST	`/api/v2/baas/webhooks/resend`	`baas.webhooks.write`	Reenviar

Parceiros

Produto de integração com parceiros (solicitação de autorização de dados do cliente final). Distinto do contexto plataforma BaaS acima. Guia: Introdução.

Método	Path	Referência
POST	`/api/v2/partners/auth/login`	Login do parceiro
GET	`/api/v2/partners/application`	Listar aplicações
POST	`/api/v2/partners/application`	Criar aplicação
PATCH	`/api/v2/partners/application/{partnerApplicationId}`	Atualizar aplicação
GET	`/api/v2/partners/requests`	Listar solicitações
POST	`/api/v2/partners/requests`	Criar solicitação

Onde aprofundar

Rate limits

Limites de requisições, cabeçalhos HTTP e uso responsável da API Nuvende v2

Resolução de problemas — API v2

Sintomas comuns nas áreas Contas, Cobranças e Pagamentos Pix e o que verificar