API Docs · MadSSolutions

🔐 Autenticação

Todas as requisições usam Bearer token no header Authorization. Tokens são emitidos no painel da empresa em Configurações → API.

# Header obrigatório em toda chamada Authorization: Bearer mads_live_xxxxxxxxxxxxxxxx Content-Type: application/json X-Mads-Tenant: cnpj-da-empresa

Base URL: https://api.madssolutions.com.br

⚠️ Nunca exponha o token no frontend. Use proxy backend. Tokens vazados podem ser revogados em Configurações → API → Revogar.

🔬 Diagnóstico

POST/diagnostico/iniciar

Inicia novo diagnóstico para uma empresa. Retorna ID que vai ser usado nos passos seguintes.

POST /diagnostico/iniciar { "cnpj": "00000000000100", "razao_social": "Bar do João LTDA", "segmento": "bar", // bar | mini | clinica | salao "responsavel": "João Silva", "whatsapp": "5561999990000", "email": "joao@bardojoao.com.br", "consentimento_lgpd": true }

Response

{ "id": "diag_01HZ...", "status": "iniciado", "link_responder": "https://app.madssolutions.com.br/diag/01HZ...", "expira_em": "2026-05-09T12:00:00Z" }

📋 NF-e / NFS-e

POST/fiscal/nfse/emitir

Emite NFS-e via Focus NFe ou NFe.io (roteamento automático).

{ "prestador_cnpj": "00000000000100", "tomador": { "cpf_cnpj": "12345678900", "nome": "Maria Cliente" }, "servico": { "codigo_municipal": "4101", "descricao": "Consulta médica pediátrica", "valor": 280.00, "iss_aliquota": 3.0 } }

Campo	Tipo	Obrigatório
`prestador_cnpj`	string	sim
`tomador.cpf_cnpj`	string	sim
`servico.codigo_municipal`	string	sim
`servico.valor`	decimal	sim

🛡 Sentinela

POST/sentinela/evento

Recebe evento de câmera + faz cross-reference com PDV/estoque/histórico. Threshold 75% antes de notificar humano.

{ "camera_id": "cam-loja-pgdf-01", "timestamp": "2026-05-02T14:32:18Z", "frame_url": "https://r2.../frame.jpg", "deteccao": { "pessoa_id": "p_42", "acao": "item_no_bolso", "confianca": 0.84 } }

GET/sentinela/eventos

Lista eventos com filtros: ?desde=2026-04-01&tipo=furto&status=confirmado

GET/sentinela/dossie/:id

Dossiê completo de um perpetrador: histórico de eventos, frames, valor recuperável, score de reincidência.

💵 Vendas

POST/vendas/registrar

{ "pdv": "stone", "transacao_id": "stn_xyz123", "valor": 128.50, "itens": [ { "sku": "7891234567890", "qtd": 2, "preco": 12.50 } ], "pagamento": "cartao_credito", "timestamp": "2026-05-02T14:32:18Z" }

Efeitos colaterais: baixa estoque, lança no fiscal, atualiza DRE em tempo real.

📦 Estoque

GET/estoque/produtos

Filtros: ?abaixo_minimo=true&categoria=bebidas&vencendo_em=30

POST/estoque/entrada

Lança entrada de mercadoria a partir de NF-e (XML) ou manualmente.

🔔 Webhooks

Configure URL em Configurações → Webhooks. Eventos enviam POST com signature HMAC-SHA256 no header X-Mads-Signature.

Evento	Payload contém
`diagnostico.concluido`	id, score, top_3_oportunidades
`nfse.emitida`	id, numero, valor, link_pdf
`nfse.rejeitada`	id, motivo, codigo_sefaz
`sentinela.alerta_critico`	id, camera, perpetrador, frame_url
`estoque.ruptura`	sku, nome, ultimo_giro
`fiscal.das_vence_3d`	cnpj, valor, data_venc

Validação de signature

// Node.js example const sig = req.headers['x-mads-signature']; const expected = crypto.createHmac('sha256', SECRET) .update(JSON.stringify(req.body)) .digest('hex'); if (sig !== expected) return res.status(401).send('invalid');

⚠️ Códigos de erro

Status	Código	Significado
400	`VALIDATION_ERROR`	Payload inválido. Veja `details` no JSON de resposta.
401	`AUTH_INVALID`	Token ausente, expirado ou revogado.
403	`TENANT_FORBIDDEN`	Token não tem acesso a esse CNPJ.
404	`NOT_FOUND`	Recurso (id) não encontrado.
409	`CONFLICT`	Estado inconsistente (ex: NFS-e já emitida).
429	`RATE_LIMIT`	Excedeu 60 req/min. Aguarde 60s ou peça aumento.
500	`SERVER_ERROR`	Erro interno. Reportar com `request_id` do header.
503	`UPSTREAM_DOWN`	Focus NFe ou SEFAZ indisponíveis. Tente em 5min.

📚 SDKs e exemplos

Em desenvolvimento. Por enquanto, qualquer cliente HTTP funciona. Curl, Postman, Insomnia, Hoppscotch — todos OK.

Linguagem	Status
Node.js / TypeScript	✓ disponível · @madssolutions/sdk
Python	beta · pip install mads-sdk
PHP	em breve
Go	em breve

Postman collection: peça por WhatsApp

API REST · v1