Uma chave.
Do teste ao seu produto.
Crie sua chave no console e use a API RPG. A integração Malvo é realizada no servidor pela conta da RPG. Não é preciso cadastrar um site ou aplicativo.
Primeira chamada no sandbox
# 1. No console, crie uma chave de teste e guarde em RPG_API_KEY.
# 2. Crie uma conexão fictícia:
curl https://www.rpgcapital.com.br/api/connecta/v1/connections \
-H "Authorization: Bearer $RPG_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"provider":"rpg_simulator","scenario":"success"}'
# 3. Use o data.id retornado:
curl https://www.rpgcapital.com.br/api/connecta/v1/connections/CONNECTION_ID/accounts \
-H "Authorization: Bearer $RPG_API_KEY"Ambientes e autenticação
Chaves rpg_test_ pertencem ao sandbox; rpg_live_ pertencem à produção. Envie Authorization: Bearer no backend. X-RPG-Environment é opcional; quando informado, precisa corresponder à chave. Cada recurso pertence ao seu usuário e ao ambiente. Limite de 60 chamadas por minuto por chave, 10 chaves ativas e 20 conexões ativas por ambiente.
O simulador RPG é um ambiente próprio e fictício. O sandbox Malvo usa credenciais dedicadas e só aparece habilitado quando configurado. Produção requer ativação explícita no console e consentimento bancário. O gateway de pagamento está desativado nesta etapa.
Endpoints
| Método | Caminho | Uso |
|---|---|---|
| GET | /connections | Liste suas conexões no ambiente da chave. |
| POST | /connections | Crie uma conexão: provider=rpg_simulator no sandbox; provider=malvo para autorização bancária. |
| GET | /connections/{id} | Consulte estado e snapshot. |
| GET | /connections/{id}/accounts | Contas e saldos; offset opcional. |
| GET | /connections/{id}/transactions | Transações; offset e account_id opcionais. |
| POST | /connections/{id}/simulate | Sandbox RPG: scenario=success, pending, expired, unavailable ou partial. |
| POST | /connections/{id}/reconnect | Reabra o consentimento da conexão Malvo existente. |
| POST | /connections/{id}/sync | Atualize o snapshot. Na Malvo, consulta os dados já disponibilizados pelo provedor. |
| POST | /connections/{id}/complete | Vincule o item_id retornado pela Malvo. O servidor verifica o proprietário. |
| DELETE | /connections/{id} | Desconecte, revogue no provedor e remova o snapshot local. |
| GET | /events | Últimos 100 eventos do ambiente. |
| GET | /requests | Últimas 100 requisições registradas. |
Conexão com a Malvo
POST /connections com provider=malvo retorna data.id e connect_url. Abra connect_url para o titular autorizar no banco. O link é efêmero: não o registre nem envie a serviços que geram pré-visualização. A finalização hospedada verifica e vincula o item ao workspace quando a sessão do desenvolvedor estiver ativa. Em uma integração com seu próprio usuário final, seu backend conclui a vinculação chamando /complete com item_id. O vínculo só é aceito se o clientUserId do Item corresponder ao recurso criado pela RPG.
Enquanto o banco sincroniza, a conexão pode ficar pending. Consulte /sync para atualizar o snapshot de dados que o provedor já coletou. Dados incompletos retornam partial e meta.partial=true; esta versão limita o tempo da coleta e pagina o snapshot. Não presuma histórico completo quando houver sinalização de parcialidade. As atualizações automáticas da Malvo dependem de configurar o segredo HMAC do provedor.
Formato dos dados
As respostas usam data, meta ou pagination quando aplicável. Valores monetários: inteiros em centavos (balance_minor, amount_minor) e moeda explícita. Transações possuem id, account_id, date, description, category e tags. O campo category pode ser texto, objeto do provedor ou null. Filtros e tabelas do console não alteram o dado original. Erros incluem code, message e request_id; o mesmo ID aparece em X-Request-Id e no log.
Webhooks assinados
Configure um endpoint HTTPS público no console. Guarde o segredo exibido uma vez. Valide RPG-Signature: t=timestamp,v1=hex como HMAC-SHA256 de timestamp + ponto + corpo HTTP cru. Rejeite timestamps fora de cinco minutos e deduplique pelo id do evento. Cada ambiente tem sua configuração. Falhas ficam no histórico e podem ser reenviadas manualmente; retentativas automáticas ainda não estão ativadas.
A entrega é feita pelo servidor e aceita somente destinos HTTPS públicos. Eventos incluem identificador, tipo, ambiente, conexão, estado e data. Nunca incluem sua chave API. Os logs não armazenam o corpo das respostas financeiras.
Erros que ajudam a continuar
401: confira a chave. 403 environment_mismatch: troque o ambiente ou a chave. 404: recurso não pertence ao seu workspace ou não existe. 409 authorization_pending: conclua o consentimento. 429: aguarde Retry-After. 503 provider_not_configured: use o simulador ou configure o provedor. A API antiga de lojas continua separada em /developers/docs e /api/public/v1.