Saltar para o conteúdo
Oráculo

Enviar informação ao Oráculo

Para qualquer plataforma que consiga fazer um pedido HTTP. Não é preciso instalar nada nem configurar regras no Oráculo: o teu sistema diz o que quer mostrar (abrir ou fechar uma pendência ou um incidente, ou registar uma actividade) e o Oráculo mostra-o no painel.

Contrato oraculo.event.v1.

Antes de começar

Precisas de dois valores, que quem administra o Oráculo te dá depois de criar a ligação (próximo passo):

ValorExemploNota
URL do webhookhttps://oraculo.exemplo.org/v1/hooks/uJyRbKodieoLHXTCCada integração tem o seu.
Credencialorc_wh_4f2a…Só aparece uma vez. Se se perder, gera-se outra e a anterior deixa de funcionar.

Trata a credencial como uma palavra-passe: guarda-a numa variável de ambiente ou num cofre, nunca no código nem num repositório.

Criar a organização e a ligação

Faz-se uma vez, na aplicação do Oráculo:

  1. Cria a organização em Criar a minha organização, ou pede ao administrador da tua.
  2. Instala a aplicação (Windows ou macOS). A ligação para a transferir está na página inicial.
  3. Abre-a, escolhe Configurar esta estação e entra com o email e a palavra-passe do passo 1.
  4. Em Configurações > Projectos, cria um projecto. O nome é o que aparece no ecrã.
  5. Em Configurações > Integrações, escolhe o projecto e toca em Nova integração. Deixa Contrato Oráculo (recomendado), dá um nome e cria.
  6. Copia o URL do webhook e a credencial. A credencial só aparece agora. No separador Ligação há também um «Código pronto» em PHP, C#, JavaScript, PowerShell e curl, já com o URL desta integração.

Os contadores não se declaram: nascem com o primeiro aviso, com o nome e o ícone que o aviso trouxer. Depois podes renomeá-los no separador Contadores.

O pedido

POST {URL do webhook}
Authorization: Bearer {credencial}
Content-Type: application/json
  • A credencial também pode ir no cabeçalho X-Oraculo-Key: {credencial}.
  • O corpo é um objecto JSON (não uma lista), até 256 KiB, em UTF-8.
  • O Content-Type tem de ser application/json.
  • Usa um limite de tempo curto (3 s) e nunca deixes uma falha do Oráculo estragar o pedido do teu utilizador (ver Boas práticas).

Os três tipos de aviso

Abrir uma pendência ou um incidente

{
  "eventId": "denuncia-142-criada",
  "kind": "pending",
  "state": "open",
  "counter": "denuncias",
  "label": "Denúncias por responder",
  "icon": "flag",
  "recordId": "142",
  "title": "Denúncia #142"
}

Fechar o mesmo registo

Mesmo counter e mesmo recordId, com "state": "resolved":

{
  "eventId": "denuncia-142-respondida-9",
  "kind": "pending",
  "state": "resolved",
  "counter": "denuncias",
  "recordId": "142"
}

Registar uma actividade

Não tem estado nem contador. Aparece na lista de actividade recente:

{
  "eventId": "produtor-5521-novo",
  "kind": "activity",
  "label": "Novo produtor",
  "icon": "user",
  "company": "AgroSul",
  "title": "Produtor registado em Chókwè"
}

Os campos

CampoQuandoRegra
eventIdsempreIdentifica este acontecimento, estável e único (até 200 caracteres). Se reenviares o mesmo acontecimento, usa o mesmo eventId: o Oráculo ignora a repetição.
kindsemprepending (pendência), incident (incidente) ou activity (actividade recente).
statepending, incidentopen ou resolved.
counterpending, incidentChave do contador: minúsculas, números, - e _, até 60 caracteres (denuncias, armazem-offline). Um contador é só de pendências ou só de incidentes.
recordIdpending, incidentIdentifica o registo (até 200). Abrir e fechar o mesmo registo usam o mesmo recordId.
labelrecomendadoNome mostrado no painel (até 60). Em activity é o nome da actividade.
iconnãoflag question message warehouse sprout clipboard alert bell truck user box bolt check clock
severitynãocritical, high, medium, low ou info. Por omissão: incidente high, pendência medium. Um incidente critical ou high põe o cartão do projecto em estado crítico.
titlenãoTexto do cartão (até 300). Só referências, nunca conteúdo sensível.
companynãoAgrupa o painel por empresa (nos projectos que o usam).
occurredAtnãoData do acontecimento, ISO 8601 (2026-11-14T08:12:00Z).
versionrecomendadoInteiro crescente, até 15 dígitos (por exemplo milissegundos desde 1970).
urlnãoLigação http(s) para abrir o registo no teu sistema (fica atrás do teu login).
contractnãooraculo.event.v1. Com outro valor o evento é recusado.

Campos desconhecidos (por exemplo um meta teu) são ignorados e, por omissão, não são guardados.

Contadores

Nascem com o primeiro aviso que os menciona, com o label e o icon desse aviso. Não há nada para declarar antes. Depois, o administrador pode renomear, mudar o ícone e reordenar no Oráculo; o que ele editar prevalece sobre o que os avisos seguintes trouxerem.

O que o Oráculo responde

CódigoSignificadoO que fazer
202Aceite. O campo outcome diz o efeito: opened, updated, resolved, activity ou ignored_stale.Nada.
200 com "status": "duplicate"Já tinha recebido este eventId.Nada: não conta duas vezes.
401 invalid_webhook_credentialCredencial em falta, errada, revogada ou de outra integração.Confirmar a credencial.
403 integration_disabledA integração está desligada no Oráculo.Pedir ao administrador que a ligue.
415 / 400 invalid_jsonNão é application/json, ou o JSON está partido, ou não é um objecto.Corrigir o pedido.
400 invalid_encodingO corpo não é UTF-8 válido (acentos enviados em Latin-1).Enviar o JSON em UTF-8. Ver a nota do curl no Windows, em Exemplos.
413 payload_too_largeCorpo acima do limite.Enviar menos.
422 invalid_eventO evento tem erros. A mensagem lista todos de uma vez.Corrigir (não repetir sem alterar).
422 counter_kind_mismatchO contador já existe como pendência e enviaste incidente (ou o contrário).Usar outro counter ou corrigir o kind.
5xx ou falha de redeProblema temporário.Repetir com o mesmo eventId.

Exemplo de erro (422):

{ "statusCode": 422, "code": "invalid_event",
  "message": "«state» tem de ser «open» ou «resolved». Falta «recordId»: liga a abertura e o fecho do mesmo registo." }

Ordem e repetições

  • Repetir é seguro. O mesmo eventId nunca conta duas vezes.
  • Ordem. Se dois avisos sobre o mesmo registo chegarem trocados, o Oráculo guarda o mais recente. Para decidir usa version; se não houver, occurredAt; se também não houver, a ordem de chegada. Envia version sempre que puderes.
  • Fechar antes de abrir. Se o fecho chegar primeiro, fica registado e a abertura atrasada (mais antiga) é ignorada (ignored_stale).
  • Reabrir. Um open mais recente do que o resolved reabre o mesmo registo.
  • Vários avisos do mesmo registo. Cada acontecimento tem o seu eventId (denuncia-142-respondida-9, denuncia-142-respondida-10). Fechar um registo já fechado não muda nada.

Boas práticas

  • Envia depois de a tua base de dados confirmar a alteração, nunca antes.
  • Limite de tempo curto (3 s) e try/catch à volta: uma falha do Oráculo não pode estragar o que o teu utilizador estava a fazer.
  • Regista a falha sem dados pessoais (por exemplo só o eventId).
  • Repete só 5xx e falhas de rede, com o mesmo eventId. Não repitas 4xx.
  • Não enviar conteúdo sensível: nem o texto de um relato, nem nome, e-mail, telefone, nem códigos de acompanhamento (funcionam como credenciais). Uma referência, um tipo, um distrito e as datas chegam.
  • Não há limite de frequência nesta versão; se enviares muitos avisos por segundo, agrupa ou espaça os pedidos.

Testar sem gravar nada

Acrescenta o cabeçalho X-Oraculo-Dry-Run: 1. O Oráculo valida o evento e diz o que faria, sem criar contadores, sem gravar e sem avisar o painel:

curl -sS -X POST "$URL" \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -H "X-Oraculo-Dry-Run: 1" \
  -d '{"eventId":"teste-1","kind":"pending","state":"open","counter":"denuncias","recordId":"1"}'
{ "contract": "webhook.v1", "status": "dry_run",
  "preview": { "explanation": "Abre uma pendência em «Denuncias» para o registo 1.", "errors": [] } }

Se o evento tiver erros, a resposta é 422 com a lista, tal como num envio real. Na aplicação, o separador Testar da integração faz o mesmo com exemplos prontos.

Para um envio real, tira o cabeçalho. Em seguida confirma na aplicação, em Contadores e Entregas (cada aviso aparece com o efeito que teve), ou no painel.

Exemplos por linguagem

Substitui URL e CHAVE. Todos têm limite de 3 s e nunca lançam erros.

curl

curl -sS -m 3 -X POST "$URL" \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{"eventId":"denuncia-142-criada","kind":"pending","state":"open","counter":"denuncias","label":"Denúncias por responder","icon":"flag","recordId":"142","title":"Denúncia #142"}'

No Windows, o curl.exe envia em Latin-1 os acentos postos num argumento (-d '{"label":"Denúncias"}') e o Oráculo recusa o pedido com 400 invalid_encoding. Guarda o JSON num ficheiro UTF-8 e usa --data-binary @evento.json. Em Linux e macOS o exemplo de cima funciona tal como está.

JavaScript (Node 18 ou superior)

async function avisarOraculo(evento) {
  try {
    await fetch(process.env.ORACULO_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.ORACULO_CHAVE}` },
      body: JSON.stringify({ contract: "oraculo.event.v1", version: Date.now(), ...evento }),
      signal: AbortSignal.timeout(3000),
    });
  } catch (e) {
    console.warn("Oráculo não recebeu o evento", evento.eventId);
  }
}

await avisarOraculo({ eventId: "denuncia-142-criada", kind: "pending", state: "open",
  counter: "denuncias", label: "Denúncias por responder", icon: "flag", recordId: "142", title: "Denúncia #142" });

PowerShell

function Send-Oraculo([hashtable]$Evento) {
  $corpo = @{ contract = 'oraculo.event.v1'; version = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() } + $Evento
  try {
    Invoke-RestMethod -Method Post -Uri $env:ORACULO_URL -TimeoutSec 3 `
      -Headers @{ Authorization = "Bearer $env:ORACULO_CHAVE" } `
      -ContentType 'application/json; charset=utf-8' `
      -Body ([Text.Encoding]::UTF8.GetBytes(($corpo | ConvertTo-Json -Depth 5))) | Out-Null
  } catch { Write-Warning "Oráculo não recebeu o evento $($Evento.eventId)" }
}

Send-Oraculo @{ eventId = 'denuncia-142-criada'; kind = 'pending'; state = 'open'; counter = 'denuncias'
                label = 'Denúncias por responder'; icon = 'flag'; recordId = '142'; title = 'Denúncia #142' }

Em PowerShell 5.1, envia o corpo em bytes UTF-8, como acima, para os acentos não se estragarem.

PHP / Laravel

// O URL e a credencial vêm de config/services.php:
// 'oraculo' => ['url' => env('ORACULO_URL'), 'chave' => env('ORACULO_CHAVE')]
// Não uses env() aqui: com `php artisan config:cache` devolve null.
function oraculo(array $evento): void
{
    try {
        \Illuminate\Support\Facades\Http::withToken(config('services.oraculo.chave'))
            ->acceptJson()->connectTimeout(2)->timeout(3)
            ->post(config('services.oraculo.url'), $evento + [
                'contract' => 'oraculo.event.v1',
                'version' => (int) floor(microtime(true) * 1000),
            ]);
    } catch (\Throwable $e) {
        \Log::warning('Oráculo não recebeu o evento', ['event_id' => $evento['eventId'] ?? null]);
    }
}

oraculo(['eventId' => "denuncia-$id-criada", 'kind' => 'pending', 'state' => 'open',
         'counter' => 'denuncias', 'label' => 'Denúncias por responder', 'icon' => 'flag',
         'recordId' => (string) $id, 'title' => "Denúncia #$id"]);

C#

using System.Net.Http.Headers;
using System.Net.Http.Json;

var oraculo = new HttpClient { Timeout = TimeSpan.FromSeconds(3) };

async Task AvisarOraculo(object evento)
{
    try
    {
        using var pedido = new HttpRequestMessage(HttpMethod.Post, Environment.GetEnvironmentVariable("ORACULO_URL"))
        { Content = JsonContent.Create(evento) };
        pedido.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("ORACULO_CHAVE"));
        using var resposta = await oraculo.SendAsync(pedido);
    }
    catch (Exception) { /* registar o eventId, sem dados pessoais */ }
}

await AvisarOraculo(new { contract = "oraculo.event.v1", eventId = "denuncia-142-criada", kind = "pending",
    state = "open", counter = "denuncias", label = "Denúncias por responder", icon = "flag",
    recordId = "142", title = "Denúncia #142", version = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() });

Python

import os, time, requests

def avisar_oraculo(evento: dict) -> None:
    try:
        requests.post(
            os.environ["ORACULO_URL"],
            headers={"Authorization": f"Bearer {os.environ['ORACULO_CHAVE']}"},
            json={"contract": "oraculo.event.v1", "version": int(time.time() * 1000), **evento},
            timeout=3,
        )
    except requests.RequestException:
        print("Oráculo não recebeu o evento", evento.get("eventId"))

avisar_oraculo({"eventId": "denuncia-142-criada", "kind": "pending", "state": "open",
                "counter": "denuncias", "label": "Denúncias por responder", "icon": "flag",
                "recordId": "142", "title": "Denúncia #142"})

Lista de verificação

  • Tenho o URL e a credencial da integração, guardados fora do código.
  • Cada acontecimento tem um eventId estável (o mesmo acontecimento, o mesmo eventId).
  • Abrir e fechar o mesmo registo usam o mesmo counter e o mesmo recordId.
  • Cada contador é só de pendências ou só de incidentes.
  • Envio version (ou pelo menos occurredAt).
  • Envio depois de gravar na base de dados.
  • Limite de 3 s, try/catch, e a falha não estraga o pedido do utilizador.
  • Nenhum campo leva conteúdo sensível.
  • Testei com X-Oraculo-Dry-Run: 1 e depois com um envio real, e vi o contador em Contadores.

Problemas comuns

SintomaCausa provável
401Credencial errada, copiada com espaço ou de outra integração; ou revogada. Gera uma nova na aplicação.
422 com «counter…»O counter tem maiúsculas, espaços ou acentos. Usa denuncias, não Denúncias.
422 com «recordId…»Falta o recordId num pending ou incident.
422 counter_kind_mismatchO mesmo counter foi usado como pendência e como incidente.
O contador não desceO fecho usa outro counter ou outro recordId do que a abertura.
ignored_staleChegou um aviso mais antigo do que o último já aplicado a esse registo; é normal. Se for inesperado, confirma o version.
400 invalid_encoding ou acentos estragadosO corpo não foi enviado em UTF-8 (típico de curl.exe no Windows com o texto no argumento). Envia o JSON a partir de um ficheiro UTF-8.
Nada no painel, mas 202O projecto não está atribuído à estação do ecrã (Configurações > Estações).
200 duplicateJá tinha este eventId. É o comportamento certo.