API

O Olvano dispõe de uma API REST para ligar os seus próprios sistemas — crie e consulte faturas, gira contactos e receba eventos em tempo real via webhooks. Esta página leva-o de um token até à primeira chamada; a lista completa e executável de endpoints encontra-se na referência interativa.

Antes de começar

Precisa de duas coisas:

1. Uma conta no plano byznys (o plano free não tem API).
2. Um token de API associado a essa conta (ver abaixo).

Os tokens são criados pelo proprietário da conta. Cada token pertence a exatamente uma conta e tem as suas próprias permissões (âmbitos), pelo que pode emitir um token separado por integração.

Criar um token de API

Na aplicação, aceda a Definições → Tokens de API (/app/{slug}/settings/api-tokens), escolha Novo token, dê-lhe um nome e selecione as permissões. O token em texto simples é mostrado apenas uma vez — copie-o imediatamente e guarde-o num local seguro.

Os tokens têm o prefixo sg_. Apenas um resumo HMAC é guardado, pelo que o token nunca mais pode ser mostrado — se o perder, crie um novo e elimine o antigo.

Permissões (âmbitos)

A leitura (GET) de recursos comuns não requer âmbito; a escrita sim. As operações exclusivas do proprietário (gestão de tokens, webhooks e contas bancárias) nunca estão disponíveis para um token de API — mesmo um token emitido por um proprietário devolve 403.

Autenticação e URL de base

Autentique cada pedido com o token no cabeçalho Authorization:

Authorization: Bearer sg_your_token

O URL de base é o domínio da sua instância + /api. Os endpoints de conta têm o formato /api/accounts/{slug}/…. Os exemplos abaixo utilizam variáveis de ambiente:

export STARGATE="https://app.stargate.app"   # replace with your instance domain (locally http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

O seu primeiro pedido

Listar as faturas de uma conta:

curl "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN"

A resposta é uma lista paginada:

{
  "invoices": [ { "id": "…", "number": "2026-0001", "status": "open", "total": "3630.00" } ],
  "total": 128,
  "page": 1,
  "pageSize": 40
}

Paginação, ordenação e pesquisa

Os endpoints de listagem aceitam os seguintes parâmetros de consulta:

As faturas podem ainda ser filtradas por status, documentType e subjectId. Um parâmetro inválido nunca quebra a listagem — é utilizado o valor predefinido (p. ex. ?page=abc → 1). Cada resposta inclui total, page e pageSize, pelo que o número de páginas é fácil de calcular.

Criar uma fatura

curl -X POST "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "CUSTOMER_ID",
    "lines": [
      { "name": "Consulting", "quantity": 2, "unitPrice": "1500", "vatRate": 21 }
    ]
  }'

subjectId é o ID do cliente — obtenha-o a partir da lista de contactos (GET /api/accounts/$SLUG/subjects) ou crie um via POST …/subjects. Os campos obrigatórios são subjectId e pelo menos uma linha em lines (cada uma com name e unitPrice). Opcionalmente, pode enviar documentType, currency, variableSymbol, due, issuedOn e mais — esquema completo na referência interativa.

Em caso de sucesso, devolve 201 e a fatura criada:

{ "invoice": { "id": "…", "number": "2026-0002", "status": "open", "total": "3630.00" } }

Erros

Os erros partilham um envelope consistente — um estado HTTP mais JSON com statusMessage e um campo data para tratamento automatizado:

{
  "statusCode": 400,
  "statusMessage": "Invalid invoice",
  "data": { "formErrors": [], "fieldErrors": { "subjectId": ["Required"] } }
}

Para erros de domínio, data.code é um código legível por máquina (p. ex. subject_not_found) em que pode confiar mais do que no texto da mensagem.

Limites do plano

O plano free não permite chamadas à API (quota 0); o byznys tem a API e todas as funcionalidades. Quando um limite é excedido (p. ex. número de contactos), a API devolve 402 com plan_limit_reached; para uma funcionalidade fora do plano (webhooks, despesas…) devolve 403 com plan_feature_unavailable. Consulte os limites e a utilização atual da sua conta através de:

curl "$STARGATE/api/accounts/$SLUG/entitlements" -H "Authorization: Bearer $TOKEN"

Webhooks

Um webhook notifica-o de eventos em tempo real, em vez de ter de consultar a API repetidamente. Os webhooks são uma funcionalidade do plano byznys e são geridos pelo proprietário da conta.

Registe-os via API (ou nas definições da conta):

curl -X POST "$STARGATE/api/accounts/$SLUG/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/hooks/stargate",
    "events": ["invoice_paid", "invoice_sent"],
    "authHeader": "Bearer your-shared-secret"
  }'

Coloque nomes específicos em events, ou * para todos. Eventos disponíveis:

invoice_created, invoice_sent, invoice_paid, invoice_overdue, invoice_cancelled, invoice_uncollectible, invoice_viewed, invoice_reminder_sent, recurring_generator_invoice_created.

O Olvano envia um POST para o seu URL com o corpo:

{ "event_name": "invoice_paid", "body": { "…": "event data" } }

• Se definir authHeader, é enviado como cabeçalho Authorization — utilize-o para verificar que o pedido veio mesmo do Olvano.
• Cada entrega inclui um cabeçalho Idempotency-Key (UUID) — utilize-o para deduplicar.
• A entrega é repetida até 5× com recuo exponencial até receber uma resposta com estado 2xx. As entregas falhadas são listadas via GET …/webhooks/{id}/failed_deliveries.

Referência interativa

A lista completa e sempre atualizada de endpoints — com parâmetros, esquemas e a possibilidade de os chamar diretamente do navegador:

• Abrir a referência da API (/api-docs)
• Esquema OpenAPI legível por máquina: /api/_openapi.json