Ajuda ao cliente

Usando a API

Como clientes técnicos aprovados usam a API.

Publico-alvo

Para integradores aprovados e operadores técnicos.

A API de integração foi projetada para clientes externos aprovados que precisam de acesso de máquina aos dados e fluxos de trabalho da conta MZ Bank.
O caminho base público é /api/v1/integrations/*.
O acesso à API é separado do login Discord e da sessão normal do portal do cliente.

As chaves de API estão vinculadas a um perfil de cliente MZ Bank ativo e verificado.
Um administrador MZ Bank cria a chave e escolhe os escopos permitidos.
As assinaturas de webhook também são criadas por um administrador e usam um segredo de assinatura separado.

Envie a chave API como um token de portador no cabeçalho Authorization.
Cada chave tem escopo limitado. Por exemplo, accounts:read cobre visualizações de contas, enquanto transfers:write permite a criação de transferências.
As chaves podem ser rotacionadas ou revogadas sem alterar o site normal do cliente ou o acesso ao bot.

Os clientes podem ler contas visíveis, saldos, histórico de transações, extratos, beneficiários, preferências de notificação, aplicativos e visualizações da família de negócios quando os escopos corretos estiverem presentes.
As respostas da conta reconhecem as subcontas e incluem identificadores da família raiz quando relevante.
As respostas empresa-família incluem subcontas secundárias, beneficiários efetivos, concessões de acesso ativo e recursos de chamada.

A API oferece suporte a solicitações operáveis pelo cliente, como transferências, criação de subcontas, aplicativos de contas, gerenciamento de beneficiários, atualizações de preferências de notificação, solicitações de retirada e solicitações de depósito.
As rotas de movimentação de dinheiro ainda devem satisfazer as mesmas regras de autorização, limite de taxa e razão aplicadas pelo bot e pelo portal.
As solicitações de gravação devem usar chaves de idempotência sempre que a rota exigir, para que novas tentativas seguras não criem atividades duplicadas.

As rotas empresariais-familiares usam as mesmas regras de propriedade e acesso delegado que o portal.
As respostas com reconhecimento de subconta incluem o ID da conta folha e o ID da conta empresarial familiar raiz.
Os operadores delegados só podem usar as contas e ações permitidas pela sua função e limites atuais.

As assinaturas do Webhook podem receber eventos de ciclo de vida de depósito, retirada e transferência.
Os webhooks de transferência são emitidos separadamente para os lados da conta de saída e de entrada, para que os consumidores conscientes da subconta e da família possam processar cada lado corretamente.
Cada webhook é assinado com x-mzb-signature-256 e os consumidores devem verificar a assinatura em relação ao corpo bruto exato.

As rotas de lista de extratos e de exportação de extratos fornecem o mesmo histórico de extratos publicados que o cliente pode acessar por meio da Central de extratos.
As rotas de notificação expõem as preferências salvas e os resultados recentes da entrega.
A atividade da API deve ser reconciliada com o estado do portal, declarações e eventos de webhook para o mesmo cliente ou família de negócios.

Peça a um administrador MZ Bank para emitir uma chave de teste com escopo apenas com os recursos de leitura e gravação que seu cliente realmente precisa.
Valide o tratamento de webhook em um endpoint de captura descartável antes de enviar eventos para um URL de retorno de chamada de produção.
Se você precisar de uma referência completa do operador para endpoints, escopos e solução de problemas, peça a um administrador a documentação de integrações internas.