RPG API V1

RPG for Developers

A API da RPG permite que aplicativos autorizados leiam e escrevam dados operacionais de uma loja. O acesso é delegado pelo lojista e limitado por scopes.

Base URL
https://rpgcapital.com.br/api/public/v1

Autenticação

Gere uma Secret API Key no Dashboard. Ela é exibida uma única vez e começa com rpg_dev_live_. A chave identifica o aplicativo; ela não concede acesso a uma loja sozinha.

Authorization: Bearer rpg_dev_live_<prefix>_<secret>
X-RPG-Connection-Id: <connection_uuid>

Nunca envie a Secret API Key ao navegador, ao lojista ou em uma URL. Guarde-a somente no backend do seu aplicativo.

RPG Connect

RPG Connect é o fluxo de autorização delegada entre seu aplicativo e uma loja RPG. No Dashboard, gere um link de conexão escolhendo os scopes desejados. O lojista entra na RPG, escolhe a loja, revisa as permissões e autoriza somente o que desejar.

Developer cria um aplicativo.
Developer gera uma Secret API Key com os scopes máximos daquela credencial.
Developer gera um link de conexão com os scopes que deseja pedir.
Owner/admin da loja abre o link e concede uma lista de scopes.
A RPG cria um Connection ID.
Em cada request, a RPG exige que o scope esteja tanto na chave quanto na conexão.

curl https://rpgcapital.com.br/api/public/v1/products \
  -H "Authorization: Bearer $RPG_API_KEY" \
  -H "X-RPG-Connection-Id: $RPG_CONNECTION_ID"

Scopes

Scope	Acesso
`products:read`	Ler produtos
`products:write`	Criar e alterar produtos
`inventory:read`	Ler estoque e movimentos
`inventory:write`	Registrar movimentos de estoque
`sales:read`	Ler vendas
`sales:ingest`	Registrar vendas externas
`finance:read`	Ler financeiro
`pricing:read`	Ler histórico e recomendações de preço
`pricing:write`	Aplicar alterações de preço
`webhooks:manage`	Gerenciar webhooks

Endpoints

Método	Endpoint	Scope
GET	`/api/public/v1/products`	`products:read`
GET	`/api/public/v1/products/{id}`	`products:read`
GET	`/api/public/v1/inventory`	`inventory:read`
GET	`/api/public/v1/inventory/movements`	`inventory:read`
GET	`/api/public/v1/sales`	`sales:read`
GET	`/api/public/v1/sales/{id}`	`sales:read`
GET	`/api/public/v1/finance/transactions`	`finance:read`
GET	`/api/public/v1/finance/summary`	`finance:read`
GET	`/api/public/v1/pricing/history`	`pricing:read`
POST	`/api/public/v1/imports/products`	`products:write`
POST	`/api/public/v1/imports/inventory-movements`	`inventory:write`
POST	`/api/public/v1/imports/sales`	`sales:ingest`
POST	`/api/public/v1/pricing/recommendations/{id}/apply`	`pricing:write`

Escrita e idempotência

Requests de escrita exigem Idempotency-Key. Use um identificador único e estável por operação. Repetir a mesma operação com a mesma chave devolve o resultado anterior; reutilizar a chave com outro conteúdo gera conflito.

POST /api/public/v1/imports/inventory-movements
Authorization: Bearer $RPG_API_KEY
X-RPG-Connection-Id: $RPG_CONNECTION_ID
Idempotency-Key: movement_872918

Erros

A API usa status HTTP e um objeto error. Códigos comuns: invalid_api_key, connection_required, invalid_connection, missing_scope, rate_limited e idempotency_conflict.

{
  "error": {
    "code": "missing_scope",
    "message": "A conexão precisa da permissão inventory:write."
  }
}

Documentação para IA

Esta documentação é indexável e possui representações legíveis por máquinas. Agentes podem consultar /openapi.json, /llms.txt e /llms-full.txt.