Orbita API — Referência

API REST para integração com dados financeiros do Orbita. Autenticada por API key, todos os endpoints retornam JSON.

Base URL: http://seu-orbita:3000
Versão: v1
Formato: JSON
Auth: API Key
Visão geral

A API pública do Orbita permite que você acesse seus dados financeiros programaticamente. É ideal para:

  • Alimentar dashboards e ferramentas de BI externas
  • Integrar o Orbita com outros ERPs ou sistemas
  • Automatizar relatórios e alertas
  • Exportar dados para análise em Python/Excel/Power BI
# Exemplo rápido com curl
curl -H "X-Api-Key: ok_seutoken" \
     https://seu-orbita.com/api/v1/info
Autenticação

Todas as requisições à API pública precisam de uma API key válida. Gere a chave em Configurações → API Keys.

Formas de enviar a chave

# Opção 1: header X-Api-Key (recomendado)
X-Api-Key: ok_abc123...

# Opção 2: Authorization Bearer
Authorization: Bearer ok_abc123...
Importante: A chave começa sempre com ok_. Guarde em local seguro — não é possível recuperá-la após a criação.

Escopos

Cada chave tem escopos que definem quais endpoints ela pode acessar:

EscopoEndpoints
read:dre/dre, /nfs
read:cashflow/cashflow
read:inventory/inventory
read:comercial/comercial
read:margin/margin
Erros

Todos os erros retornam JSON com "ok": false e um campo "error" descritivo.

HTTPSignificado
200Sucesso
400Parâmetro inválido
401API key não fornecida ou inválida
403Escopo insuficiente para o endpoint
500Erro interno do servidor
 
// Exemplo de resposta de erro
{
  "ok": false,
  "error": "Escopo 'read:dre' não autorizado para esta chave."
}
Rate limit

A API pública do Orbita limita 300 requisições por minuto por IP. Ao exceder, retorna HTTP 429 com a mensagem abaixo.

{
  "ok": false,
  "error": "Limite de requisições por minuto atingido."
}

Adicionalmente, as sincronizações com o Tiny ERP são limitadas a ~30 req/min pela API do Tiny.

Workspace
GET /api/v1/info Informações do workspace associado à chave

Retorna o workspace associado à API key e os escopos disponíveis. Útil para validar a chave.

Resposta

{
  "ok": true,
  "workspace": {
    "id": 3,
    "name": "Matriz iBob"
  },
  "scopes": ["read:dre", "read:inventory"],
  "version": "1.0.0"
}
DRE
GET /api/v1/dre DRE do mês read:dre

Query params

ParamTipoDescrição
monthstringMês no formato YYYY-MM. Padrão: mês atual.
Retorna totais brutos de NFs e contas a pagar do mês. Para o DRE processado completo (com cálculo de margens, despesas agrupadas etc.) use a interface interna GET /api/dre com JWT.

Resposta

{
  "ok": true,
  "month": "2026-03",
  "saidas": {
    "count": 412,
    "totalNota": 2506876.14,
    "totalProd": 2480000.00
  },
  "entradas": {
    "count": 38,
    "totalNota": 310200.00,
    "totalProd": 298000.00
  },
  "contas_pagar": {
    "count": 24,
    "total": 187450.00
  }
}
Fluxo de Caixa
GET /api/v1/cashflow Fluxo de caixa do mês read:cashflow

Query params

ParamTipoDescrição
monthstringMês YYYY-MM. Padrão: mês atual.

Resposta

{
  "ok": true,
  "month": "2026-03",
  "entradas": 382450.00,
  "saidas": 310200.00,
  "saldo": 72250.00,
  "items": [
    {
      "date": "2026-03-05",
      "descricao": "NF 12345 — Cliente XYZ",
      "tipo": "entrada",
      "valor": 8500.00
    }
  ]
}
Estoque
GET /api/v1/inventory Posição de estoque com alertas de ruptura read:inventory

Query params

ParamTipoDescrição
windowDaysnumberJanela de dias para calcular média de vendas. Padrão: 30.

Resposta

{
  "ok": true,
  "windowDays": 30,
  "alerts": {
    "out": 3,
    "critical": 7,
    "low": 12,
    "ok": 248,
    "total": 270
  },
  "items": [
    {
      "codigo": "LN151261330",
      "descricao": "Produto Exemplo",
      "saldoAtual": 45,
      "avgDayQty": 8.8,
      "daysRemaining": 5,
      "alertLevel": "critical",
      "needsReorder": true,
      "reorderQty": 264
    }
  ]
}
BI Comercial
GET /api/v1/comercial Métricas de vendas por SKU read:comercial

Query params

ParamTipoDescrição
windowDaysnumberJanela de análise em dias. Padrão: 30.

Resposta

{
  "ok": true,
  "windowDays": 30,
  "skus": [
    {
      "codigo": "LN151261330",
      "totalQty": 265,
      "totalVendas": 52000.00,
      "avgDayQty": 8.8,
      "activeDays": 28,
      "ticketMedio": 196.20
    }
  ]
}
Margem
GET /api/v1/margin Dados de margem do mês read:margin

Query params

ParamTipoDescrição
monthstringMês YYYY-MM. Padrão: mês atual.

Resposta

{
  "ok": true,
  "month": "2026-03",
  "nfCount": 142,
  "marketplaceCosts": { /* custos salvos por NF */ }
}
Notas Fiscais
GET /api/v1/nfs Lista de NFs com paginação read:dre

Query params

ParamTipoDescrição
monthstringFiltra por mês YYYY-MM. Opcional.
limitnumberMáximo de registros. Padrão: 100. Máx: 500.
offsetnumberPular N registros (paginação). Padrão: 0.

Resposta

{
  "ok": true,
  "total": 1842,
  "offset": 0,
  "limit": 100,
  "nfs": [ /* array de NFs */ ]
}
Gerenciar API Keys
Esses endpoints usam autenticação JWT (login normal), não API key. São usados pela interface do Orbita.
Requer: usuário com papel orbita_admin — não está disponível para administradores de empresa.
GET /api/apikeys Lista chaves do workspace JWT Admin

Headers

Authorization: Bearer <jwt_token>
X-Workspace-Id: 3

Resposta

{
  "ok": true,
  "keys": [
    {
      "id": 1,
      "label": "Power BI integration",
      "scopes": ["read:dre", "read:inventory"],
      "created_at": "2026-03-06T10:00:00Z",
      "last_used_at": "2026-03-06T14:22:00Z"
    }
  ]
}
POST /api/apikeys Cria nova API key JWT Admin

Body (JSON)

CampoTipoDescrição
labelstringNome descritivo da chave.
scopesstring[]Escopos autorizados. Omitir = todos os escopos.

Resposta

{
  "ok": true,
  "id": 1,
  "key": "ok_a1b2c3d4e5f6...",
  "message": "Guarde esta chave — ela não será exibida novamente."
}
Atenção: O campo key é retornado apenas nesta resposta. Não é possível recuperá-lo depois.
DEL /api/apikeys/:id Revoga uma API key JWT Admin

Path params

ParamTipoDescrição
idnumberID da chave a revogar.

Resposta

{
  "ok": true,
  "message": "Chave revogada."
}