API pública · v1

No painel /admin/api-clients, crie um ApiClient com os scopes necessários. O client_secret é mostrado UMA vez · salve em local seguro.

# Resposta do POST /api-clients
{
  "id": "...",
  "clientId": "cq_a1b2c3d4e5f6g7h8i9j0k1l2",
  "clientSecret": "sk_xxxxxx...",  // SALVE AGORA · não será mostrado de novo
  "scopes": ["products:read", "rfqs:write"]
}

Tokens duram 1 hora. Re-solicite a cada chamada ou implemente refresh interno.

curl -X POST https://api.centralquimica.tec.br/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cq_xxx",
    "client_secret": "sk_xxx",
    "scope": "products:read rfqs:write"
  }'

# Resposta:
{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "products:read rfqs:write"
}

curl https://api.centralquimica.tec.br/api/v1/products \
  -H "Authorization: Bearer eyJhbGc..."

• products:read · listar/buscar catálogo
• products:write · criar/editar produtos (supplier)
• rfqs:read · listar RFQs/propostas
• rfqs:write · criar RFQ ou proposta
• orders:read · status de pedidos
• orders:write · atualizar status
• nfe:read · NF-e emitidas
• analytics:read · KPIs agregados

Crie um endpoint HTTPS no seu lado. Configure subscription em /admin/webhooks escolhendo quais eventos receber.

Eventos disponíveis:

• rfq.created
• rfq.proposal.received
• order.confirmed
• order.delivered
• order.cancelled
• nfe.emitted
• nfe.cancelled
• compliance.change_detected

Cada POST do webhook traz header:

X-CentralQuimica-Signature: t=1717024800,v1=abcd1234ef56...
X-CentralQuimica-Event: order.confirmed
X-CentralQuimica-Delivery-Id: cmp...

Validação (Node.js):

import crypto from 'crypto'

function verificar(rawBody, signature, secret) {
  const [tPart, v1Part] = signature.split(',')
  const t = tPart.split('=')[1]
  const v1 = v1Part.split('=')[1]
  const expected = crypto.createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex')
  // Tolerância de 5 min para clock skew
  const tooOld = Date.now()/1000 - Number(t) > 300
  return !tooOld && crypto.timingSafeEqual(
    Buffer.from(v1, 'hex'),
    Buffer.from(expected, 'hex')
  )
}

Se seu endpoint responder 2xx, marcamos como entregue. Se falhar (timeout, 5xx, conexão), tentamos novamente em:

• · 30 segundos
• · 5 minutos
• · 1 hora
• · 6 horas

Após 5 falhas consecutivas a subscription vai para FAILING e pausa entregas. Receber 404 ou 410 marca como DEAD_LETTER imediato.

Esqueletos de integração disponíveis · implementação sob demanda do primeiro cliente piloto. Atualmente endpoints retornam stub.

• · SAP S/4HANA Cloud · estrutura para OData v4 (Product, Customer) · não-funcional ainda
• · TOTVS Protheus · estrutura para REST API com token · não-funcional ainda
• · Bling v3 · estrutura para OAuth2 com refresh_token · não-funcional ainda

Por enquanto, recomendamos seu time de TI integrar diretamente via OAuth2 + endpoints REST documentados acima. Conectores nativos serão implementados conforme demanda.

• · Rate limit: 60 req/min por IP (global)
• · Token TTL: 3600s (1h)
• · Webhook timeout: 10s
• · Webhook retry total: 5 tentativas em 7h
• · Body máximo: 10MB