Primeira chamada
Da credencial até a primeira resposta, em quatro passos.
1. Gere uma credencial
O dono ou um administrador do workspace gera a credencial em Gerenciar conta e plano → API pública. A tela mostra duas coisas:
- a API Key (
mdk_…), que identifica a credencial e aparece de novo na lista; - o Secret (
mds_…), que aparece uma única vez. Guarde-o num cofre de segredos.
Escolha o papel Leitor se a integração só consulta, ou Escritor se ela também cria ou altera dados.
2. Troque a credencial por um token
curl -s -X POST https://app.meudinheiroweb.com.br/api/public/v1/auth/token \
-H 'Content-Type: application/json' \
-d '{"api_key": "mdk_…", "api_secret": "mds_…"}'{
"access_token": "mda_…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "mdr_…",
"refresh_expires_in": 2592000
}O access token vale 1 hora. Antes de ele vencer, renove pelo refresh token — o par antigo deixa de valer:
curl -s -X POST https://app.meudinheiroweb.com.br/api/public/v1/auth/refresh \
-H 'Content-Type: application/json' \
-d '{"refresh_token": "mdr_…"}'3. Chame a API
curl -s https://app.meudinheiroweb.com.br/api/public/v1/me \
-H 'Authorization: Bearer mda_…'{
"workspace": {"id": 123, "name": "Minha empresa"},
"credential": {"name": "ERP", "api_key": "mdk_…", "roles": [{"id": "leitor", "name": "Leitor", "system": true}], "expires_at": null}
}4. Leia uma lista
Toda listagem é paginada por cursor: repasse o next_cursor até ele vir nulo.
curl -s 'https://app.meudinheiroweb.com.br/api/public/v1/categorias?tipo=despesa&limit=100' \
-H 'Authorization: Bearer mda_…'{
"data": [
{"id": 1001, "nome": "Alimentação", "nome_completo": "Alimentação", "tipo": "despesa", "categoria_pai_id": null, "status": "active", "sistema": false},
{"id": 1042, "nome": "Delivery", "nome_completo": "Alimentação/Delivery", "tipo": "despesa", "categoria_pai_id": 1001, "status": "active", "sistema": false}
],
"next_cursor": "eyJpZCI6MTA0Mn0"
}Os outros cadastros seguem o mesmo formato: GET /contas (tipo, moeda e banco de cada conta),
/centros, /formas-pagamento, /tags, /projetos (com período e metas) e /contatos (clientes e fornecedores, com documento,
e-mail, telefones e endereço). Cada um tem também a consulta por id, como GET /contatos/9120.
O que pode dar errado
| Resposta | Causa comum |
|---|---|
400 bad_request | parâmetro inválido (limit, cursor, filtro); o message diz qual |
401 unauthorized | token vencido (renove), credencial revogada ou secret errado |
403 forbidden | chamada que o papel da credencial não cobre (escrita com Leitor, por exemplo), conta somente leitura, workspace fora do acesso antecipado ou desativado |
429 rate_limited | mais de 120 chamadas no minuto; espere o Retry-After |
Todo erro vem como {"error": {"code": "...", "message": "..."}} — trate pelo code.