Documentação ORQTA

1. Visão geral

A ORQTA entrega a inteligência sobre o mercado público de três formas:

Os scores são índices comparativos explicáveis, nunca probabilidade de compra. Toda resposta traz a fonte e a data.

2. Conectar ao CRM sem programar (webhooks)

Esse é o caminho mais rápido para receber alertas no Pipedrive, RD Station CRM, HubSpot, Google Sheets, Slack e outros.

Pré-requisitos: plano Business (3 webhooks) ou Agency (5); papel de dono da organização; conta numa plataforma de automação: Zapier, Make, n8n ou Pluga.

Passo a passo:

1. Na plataforma de automação, crie um gatilho do tipo webhook e copie a URL que ela gerar. Zapier: "Webhooks by Zapier → Catch Hook"; Make: "Webhooks → Custom webhook"; n8n: nó "Webhook"; Pluga: "Pluga Webhooks".
2. No console da ORQTA, abra Integrações → Novo webhook: cole a URL; escolha os alertas (nenhum marcado = todos); clique em Criar webhook.
3. Guarde o segredo que aparece. Ele é exibido uma única vez e serve para conferir a assinatura (seção 5.4). No Zapier, Make e Pluga essa conferência é opcional.
4. Clique em Enviar teste. A entrega sai no próximo ciclo, em até 5 minutos, com o alerta mais recente dos tipos que você escolheu, marcado com "test": true.
5. Na plataforma de automação, carregue o teste e crie a ação no destino usando os campos do bloco resumo (seção 5.2).
6. Ligue a automação.

3. API REST: primeiros passos

Endereço base:

https://api.orqta.com.br/functions/v1/api-v1

Chave de API: gere no console, em Chaves de API. O segredo aparece uma única vez; guardamos só o prefixo e um resumo criptográfico; nunca enviamos nem pedimos chaves por e-mail, mensagem ou telefone.

Autenticação — envie a chave em todo pedido:

Authorization: Bearer gi_<prefixo>.<segredo>

Primeira chamada (a rota de saúde não pede chave):

curl https://api.orqta.com.br/functions/v1/api-v1/v1/health

Perfil de um órgão, pelo código IBGE ou pelo id da ORQTA:

curl -H "Authorization: Bearer $ORQTA_API_KEY" \
  https://api.orqta.com.br/functions/v1/api-v1/v1/governments/2611606

Especificação OpenAPI 3.1: GET /v1/openapi.json, sem chave.

4. Referência da API

4.1 Rotas

4.2 Parâmetros

Listas (todas as rotas que devolvem lista): limit (padrão 50, máximo 200); offset (padrão 0).

GET /v1/events: since (data ISO 8601; só eventos a partir dela); event_types (lista separada por vírgula, ex.: NEW_PROCUREMENT,CONTRACT_EXPIRING); unread_only=true (só os não lidos).

POST /v1/opportunities/search (corpo JSON, todos os campos opcionais):

{ "product_profile_id": "<uuid>", "sphere": "municipal", "ufs": ["PE", "PB"], "limit": 50 }

Sem product_profile_id, a busca usa o perfil padrão da organização.

POST /v1/watchlists:

{ "name": "Prefeituras PE" }

POST /v1/webhooks:

{ "url": "https://...", "event_types": ["NEW_PROCUREMENT"], "description": "Pipedrive via Zapier" }

event_types também aceita texto separado por vírgula; sem event_types = todos os alertas.

CNPJ: 14 dígitos. Pontos e barras são ignorados.

4.3 Formato das respostas

Rotas de lista:

{
  "data": [ ... ],
  "pagination": { "limit": 50, "offset": 0, "returned": 50, "has_more": true },
  "meta": { "source": "...", "coverage_note": "...", "generated_at": "..." }
}

Rotas de item único: { "data": { ... }, "meta": { "generated_at": "..." } }.

Erros:

{ "error": { "code": "not_found", "message": "orgao nao encontrado" } }

Códigos: unauthorized (401); rate_limited (429, com Retry-After); invalid_cnpj, invalid_since, invalid_body e invalid_webhook (400); not_found (404); internal_error (500).

4.4 Limites e cabeçalhos

Toda resposta autenticada traz:

Webhooks pela API: o direito e o limite vêm do plano da organização (console ou API); a chave só precisa ser válida.

Os planos e valores ainda estão em validação comercial.

Ao passar do limite por minuto, a resposta é 429 com Retry-After. Ao atingir a cota do mês, os pedidos são recusados até o ciclo seguinte, sem cobrança de excedente na API inclusa.

Escopos de leitura: read:governments, read:companies, read:contracts, read:procurements, read:signals, read:events.

5. Webhooks: referência

5.1 Quando a ORQTA envia

Um alerta vira entrega quando é da sua organização e o tipo está entre os escolhidos no webhook. Os alertas da organização saem do perfil de produto, das categorias e das listas de monitoramento.

Frequência: a fila é montada e enviada a cada 5 minutos. A entrega chega alguns minutos depois de o alerta surgir.

5.2 Corpo da entrega (schema_version: 2)

O método é POST e o corpo é Content-Type: application/json. Exemplo real (entrega de teste de 25/09/2026):

{
  "schema_version": 2,
  "id": 3663670,
  "type": "SUPPLIER_AWARD",
  "test": true,
  "occurred_at": "2026-09-24T18:17:45.060302-03:00",
  "resumo": {
    "tipo": "Contrato assinado",
    "titulo": "Contratacao de empresa especializada para prestacao de servicos de cessao de uso de softwares para Gestao Publica, ...",
    "orgao": "SERVICO AUTONOMO DE AGUA E ESGOTO",
    "uf": "ES",
    "municipio": "Vargem Alta",
    "valor": 242100.00,
    "data_limite": "2027-09-14",
    "fornecedor": "E & L PRODUÇÕES DE SOFTWARE LTDA",
    "fornecedor_cnpj": "39781752000172",
    "categoria": "ERP / gestão pública, Software (geral)",
    "pncp_id": "31724255000120-2-000027/2026",
    "link": "https://app.orqta.com.br/governments/b84c9c50-...",
    "fonte": "pncp"
  },
  "subject": { "kind": "contract", "id": "38505946-..." },
  "government_id": "b84c9c50-...",
  "company_id": "a260dbc1-...",
  "category_codes": ["ti.software.erp_publico", "ti.software.geral"],
  "match_reason": ["CATEGORY_MATCH", "MIN_STRENGTH_MET"],
  "payload": { "...": "dados originais do evento, variam por tipo" },
  "organization_id": "..."
}

Campos do resumo, feitos para mapear direto no CRM. Um campo sem valor para aquele tipo de alerta não vem no corpo.

Tipos de alerta (type):

5.3 Cabeçalhos

5.4 Como conferir a assinatura

Calcule o HMAC sobre o corpo bruto, exatamente como chegou. Não refaça o JSON: a ordem das chaves e os espaços contam. Recuse também timestamps muito antigos, por exemplo com mais de 5 minutos, para evitar reenvio malicioso.

Node.js:

import crypto from "node:crypto";

function assinaturaValida(rawBody, headers, segredo) {
  const ts = headers["x-gi-timestamp"];
  const recebida = (headers["x-gi-signature"] || "").replace(/^sha256=/, "");
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const esperada = crypto.createHmac("sha256", segredo).update(`${ts}.${rawBody}`).digest("hex");
  return recebida.length === esperada.length &&
    crypto.timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada));
}

Python:

import hmac, hashlib, time

def assinatura_valida(raw_body: bytes, headers, segredo: str) -> bool:
    ts = headers.get("X-GI-Timestamp", "")
    recebida = headers.get("X-GI-Signature", "").removeprefix("sha256=")
    if not ts or abs(time.time() - int(ts)) > 300:
        return False
    esperada = hmac.new(segredo.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(recebida, esperada)

5.5 Entrega, novas tentativas e desligamento

• Sucesso: resposta HTTP 2xx em até 8 segundos. Responda rápido e processe depois.
• Falha: a ORQTA tenta de novo com espera crescente de 1, 2, 4, 8, 16 e 32 minutos, até 6 tentativas. Depois disso, a entrega fica como "Falhou".
• Desligamento automático: um webhook com 20 entregas sem sucesso em 7 dias é desligado, com o motivo exibido no console. Corrija o destino e clique em Ligar.
• Duplicidade: use o id do alerta para ignorar repetições. Uma nova tentativa reenvia o mesmo id, e o teste também usa o id de um alerta real, com "test": true.
• Destino: somente https://. Endereços locais e IPs privados são recusados.
• Histórico: as últimas entregas de cada webhook, com código HTTP e erro, aparecem no console.

6. Guias passo a passo

"Testado pela ORQTA" quer dizer que fizemos o caminho completo, com alerta real, em 25/09/2026.

Caminhos testados pela ORQTA: Zapier → Pipedrive, Zapier → Google Sheets, Pluga → RD Station CRM, n8n (recebimento do webhook) e, via Make, HubSpot, Salesforce, Zoho CRM, Trello, Notion, ClickUp e Airtable.

6.1 Zapier → PipedriveTestado pela ORQTA

1. Zapier → Create Zap → gatilho Webhooks by Zapier → Catch Hook → copie a URL.
2. ORQTA → Integrações → Novo webhook com a URL → Enviar teste.
3. Em até 5 minutos, no Zapier, clique em Test trigger e escolha a entrega recebida.
4. Adicione a ação Pipedrive → Create Deal e conecte a sua conta.
5. Mapeie os campos: Title — monte com o botão +: resumo.orgao + " (" + resumo.municipio + " - " + resumo.uf + ")"; Deal Value: resumo.valor; Currency: Brazilian Real; Expected Close Date: resumo.data_limite.
6. Clique em Test step. O negócio aparece na primeira etapa do funil.
7. Publish para ligar.

Dicas: no Zapier, digitar "/" num campo para inserir dado substitui o que já está escrito — para juntar vários campos num só, use o botão +. Opcional: acrescente Pipedrive → Create Note com resumo.titulo, resumo.categoria, resumo.fornecedor e resumo.link; use Find or Create Organization com resumo.orgao para ligar o negócio à organização.

6.2 Zapier → Google SheetsTestado pela ORQTA

1. Crie uma planilha com uma coluna para cada campo do resumo, mais evento_id e teste.
2. No mesmo Zap, ou num novo, adicione Google Sheets → Create Spreadsheet Row e conecte a sua conta Google.
3. Escolha a planilha e a aba e mapeie cada coluna para o campo resumo.* correspondente; evento_id = id; teste = test.
4. Test step → a linha aparece na planilha.

6.3 MakeTestado pela ORQTA

1. Cenário novo → módulo Webhooks → Custom webhook → Add → copie o endereço.
2. Cadastre o endereço na ORQTA e clique em Enviar teste. O Make aprende a estrutura com a primeira entrega.
3. Adicione o módulo do destino (Pipedrive, RD Station CRM, Google Sheets…) e mapeie os campos do resumo.

6.4 n8nTestado pela ORQTA

1. Nó Webhook, método POST → copie a Production URL.
2. Cadastre a URL na ORQTA.
3. Para conferir a assinatura, ative Raw Body no nó e aplique a função da seção 5.4 num nó Code.
4. Ligue o nó do destino (CRM, planilha, chat).

6.5 Pluga → RD Station CRMTestado pela ORQTA

Pré-requisito: a conta RD precisa ter o RD Station CRM ativado. É um produto separado do RD Station Marketing e tem plano gratuito.

1. Na Pluga, gatilho Webhooks → Notificação recebida; copie a URL.
2. Na ORQTA, Integrações → Novo webhook com essa URL → Enviar teste.
3. Ação RD Station CRM → Criar ou atualizar negociação; na janela do RD, escolha RD Station CRM e autorize.
4. Título = resumo.orgao - resumo.tipo; empresa = resumo.orgao (o RD passa a exigir o responsável pela empresa); anotação = resumo.titulo | Valor R$ resumo.valor | resumo.link.

Na Pluga, o valor da negociação só entra pelo bloco de produto, por isso o guia coloca o valor na anotação.

7. MCP: agentes de IA

Endereço:

https://api.orqta.com.br/functions/v1/mcp

Protocolo: Streamable HTTP, versão 2025-06-18. Autenticação: Authorization: Bearer <sua chave de API>, com os mesmos limites e escopos da API.

8. Dados, cobertura e LGPD

• Os dados vêm de fontes públicas oficiais: PNCP, Portal da Transparência, SICONFI/Tesouro, Transferegov, IBGE e Obrasgov.
• Uma contagem sem a cobertura ao lado não é universo. Consulte /v1/coverage.
• Não enviamos CPF, nem nome de pessoa física como fornecedor.
• O uso dos dados segue os Termos de Uso. Redistribuir ou revender a base não é permitido.