# MIVY > Documentação oficial para assistentes de IA implementarem integrações com a Mivy: depósitos Pix, saldo da conta, webhooks e WebSocket, com confirmação de pagamento e entrega sem duplicidade. A Mivy conecta lojas e suas carteiras a sistemas externos. Esta documentação descreve contratos existentes. Consulte o OpenAPI e as páginas abaixo antes de implementar. O domínio desta documentação serve conteúdo; as chamadas financeiras vão ao backend oficial. ## Referência principal - [Autenticação e visão geral](https://docs.mivy.com.br/docs/api): chaves, permissões, erros e limites. - [Depósitos Pix](https://docs.mivy.com.br/docs/depositos-api): criar, listar e consultar recebimentos. - [Saldo da conta](https://docs.mivy.com.br/docs/consultar-saldo): consultar o saldo disponível da loja. - [Webhooks](https://docs.mivy.com.br/docs/webhooks): eventos, assinatura HMAC, persistência e novas tentativas. - [WebSocket](https://docs.mivy.com.br/docs/websocket): autenticação, eventos, cursor e reconexão. - [OpenAPI 3.1](https://docs.mivy.com.br/openapi.json): contrato de requisições e respostas REST. ## Como implementar e entregar uma integração 1. Identifique a loja, o pedido e a entrega que o sistema do vendedor precisa realizar. Use as rotas documentadas; não invente endpoints, campos ou respostas. 2. Coloque a chave da API apenas no servidor, em variável privada. O navegador chama o servidor da integração, que chama a Mivy. Nunca inclua chaves em bundles, URLs, logs, capturas ou exemplos publicados. 3. Gere um UUID para Idempotency-Key e persista-o junto ao pedido ANTES de criar o Pix. Persista também valor esperado, moeda, loja e o id retornado pela Mivy. Em falha de rede ou nova tentativa, reutilize exatamente o UUID e o corpo originais. 4. Mostre pixCode, qrCode e expiresAt retornados pela API. Trate campos ausentes e estados pendentes. Criar um Pix não confirma pagamento nem credita saldo imediatamente. 5. Receba eventos em um endpoint HTTPS do sistema do vendedor. Verifique a assinatura sobre os bytes originais, persista a entrega e só então responda com sucesso. Execute a entrega comercial em um processamento separado e recuperável. 6. Antes da entrega comercial, consulte GET /payments/{id} no servidor e confirme status PAID, id vinculado ao pedido, loja da chave, moeda e valores esperados. amount é o valor cobrado; requestedAmount é o valor solicitado; fee e netAmount representam taxa e líquido. Considere passFee ao comparar valores. 7. Faça a transição do pedido e o registro da entrega de forma idempotente e persistente. Deduplicate tanto o evento quanto a ação de negócio por pedido/pagamento. Se um serviço externo entregar o produto, use sua chave de idempotência e reconcilie falhas antes de repetir. 8. Implemente estados de carregamento, pendente, confirmado, expirado e erro; reconexão com espera progressiva; histórico e conciliação. Não transforme erros ou timeouts em sucesso. 9. Entregue código conectado às rotas reais, instruções das variáveis privadas e validações executadas. Identifique dependências de configuração e testes ainda pendentes. Não afirme que houve pagamento real ou publicação sem verificar. O depósito da API é um recebimento da carteira. Ele não cria automaticamente um pedido de checkout, não reserva estoque e não entrega produtos da loja. Esse vínculo e a entrega precisam ser implementados no sistema do vendedor. Nunca entregue por ter gerado o Pix, exibido o QR Code, recebido uma captura/comprovante, voltado de um redirecionamento ou observado uma mudança de saldo. endpoint.test e connection.test testam transporte; não autorizam entrega. ## REST Base URL: https://api.mivy.com.br/api/v1 Autenticação: Authorization: Bearer . Crie a chave em https://mivy.com.br/dashboard/api. Cada chave pertence a uma loja; habilite somente as permissões necessárias. - GET /status: valida autenticação e informa permissões. - POST /payments: permissão payments:create; cabeçalho Idempotency-Key com UUID obrigatório. - GET /payments: permissão payments:read; page de 1 a 1000, limit de 1 a 100. - GET /payments/{id}: permissão payments:read; consulta somente pagamentos de origem API da loja da chave. - GET /balance: permissão balance:read; retorna data.availableBalance em reais e data.currency igual a BRL. POST /payments aceita apenas amount, currency, description, passFee e validityMinutes. amount é um número positivo em reais com até duas casas decimais; currency é BRL; description tem até 80 caracteres; passFee é booleano; validityMinutes aceita 30, 60, 360, 1440, 2880 ou 10080. O total com taxa não pode exceder R$ 1.000 e o líquido precisa ser positivo. Consulte o OpenAPI para valores padrão e o esquema completo. A mesma chave de idempotência com o mesmo corpo reutiliza o pagamento (201 na criação e 200 na repetição); um corpo diferente retorna 409. Status públicos: CREATING, PENDING, PAID, EXPIRED e FAILED. Use PAID para confirmação. Uma confirmação posterior do provedor pode prevalecer sobre a expiração. O limite é 120 requisições por minuto por chave. Em 429, respeite Retry-After. Trate erros HTTP e o corpo com error e code quando disponível. Não há rota pública de saque, transferência ou reembolso com essas chaves. ## Webhooks e entrega confiável Cadastre a URL HTTPS do seu próprio receptor em https://mivy.com.br/dashboard/webhooks. Guarde o segredo whsec_ em variável privada. Cabeçalhos: X-Mivy-Event, X-Mivy-Delivery e X-Mivy-Signature. A assinatura tem o formato t=,v1=. Calcule HMAC-SHA256 com o segredo sobre timestamp + "." + corpo bruto original e compare em tempo constante; aceite no máximo cinco minutos de diferença. Não serialize JSON novamente para verificar a assinatura. O envelope contém id, type, createdAt, storeId e data. Para recebimentos da API, data inclui paymentId e source igual a api. Eventos de checkout podem conter orderId e precisam de tratamento próprio. Eventos de pagamento: payment.created, payment.approved, payment.expired, payment.failed. Também existe deposit.approved: ele pode representar o mesmo depósito de payment.approved; não faça uma segunda entrega ou crédito. A carteira é creditada pelo backend da Mivy, não pelo receptor da integração. Deduplicate X-Mivy-Delivery ao persistir e event.id ao processar. Responda 2xx somente após persistência durável. A Mivy tenta até cinco vezes, com novas tentativas aproximadamente após 1 minuto, 5 minutos, 15 minutos e 1 hora. A assinatura pode mudar entre tentativas; o corpo e o identificador permanecem os mesmos. Reconciliar pela API cobre interrupções do receptor. ## WebSocket Endpoint: wss://api.mivy.com.br/api/realtime/ws Crie uma credencial própria mivy_ws_ em https://mivy.com.br/dashboard/websocket. Ela não substitui a chave REST e deve ficar no servidor. Envie em até 10 segundos a primeira mensagem: {"op":"auth","token":""}. Para retomar, inclua after com o último sequence persistido como string. Sem after, a conexão começa nos eventos atuais. O servidor envia ready e event. Em event, processe event.id sem duplicidade e persista sequence somente após concluir o processamento. Não converta sequence em Number. Reconecte com espera progressiva e retome do cursor salvo. Use REST para consultar saldo, criar Pix e reconciliar pagamentos. Não envie tokens na URL ou exponha a credencial ao navegador. WebSocket e webhook podem entregar o mesmo evento. Compartilhe a deduplicação de negócio entre os transportes. Uma conexão em tempo real não substitui a confirmação e a persistência da entrega. ## Exemplos oficiais - [Cliente REST Node.js](https://docs.mivy.com.br/integrations/mivy-client.mjs): autenticação, saldo, recebimentos e idempotência. - [Validação de assinatura](https://docs.mivy.com.br/integrations/mivy-webhook-signature.mjs): HMAC sobre o corpo original. - [Receptor de webhook](https://docs.mivy.com.br/integrations/mivy-webhook-receiver.mjs): persistência antes da resposta; o consumidor implementa a entrega comercial. - [Cliente WebSocket](https://docs.mivy.com.br/integrations/mivy-realtime.cjs): autenticação, reconexão e cursor. Valide formatos e erros com testes locais. Execute operações financeiras reais somente quando autorizadas. Nunca use dados simulados como prova de que uma integração em produção funcionou. ## Optional - [Início rápido](https://docs.mivy.com.br/docs/inicio-rapido): preparar a loja. - [Produtos](https://docs.mivy.com.br/docs/produtos): catálogo da loja. - [Checkout](https://docs.mivy.com.br/docs/checkout): jornada de compra. - [Personalização](https://docs.mivy.com.br/docs/personalizacao): identidade da loja. - [Perguntas frequentes](https://docs.mivy.com.br/docs/perguntas-frequentes): dúvidas gerais.