Conecte seu e-commerce ao ERP com segurança.

1 · Começar

Crie uma chave no painel administrativo

1. Acesse Administração → Central de API.
2. Selecione a empresa Bering Imports e a unidade que expedirá os pedidos.
3. Marque apenas os dados e operações que o site realmente precisa.
4. Copie o token exibido uma única vez e salve-o no servidor do e-commerce.
5. Teste a rota de validação antes de iniciar a importação.

2 · Segurança

O token deve ficar somente no servidor

Nunca coloque a chave em JavaScript entregue ao navegador, aplicativo público, repositório Git ou variável iniciada por NEXT_PUBLIC_. O backend do site chama o CYNQUO e entrega ao frontend somente os dados necessários.

• Envie Authorization: Bearer SEU_TOKEN em todas as requisições.
• A empresa e a unidade são obtidas da chave; parâmetros externos não alteram esse contexto.
• Rotacione a chave imediatamente se houver suspeita de exposição.
• Opcionalmente restrinja os IPs autorizados ao servidor do e-commerce.
• Não registre tokens em logs, ferramentas de analytics ou mensagens de erro.

3 · Rotas

Endpoints disponíveis

4 · Sincronização

Use cursor e data de atualização

As listagens aceitam limit de 1 a 500. Quando hasMore for verdadeiro, envie o valor de nextCursor na próxima chamada. Para rotinas incrementais, salve synchronizedAt e use-o depois em updatedSince.

GET /catalog/products?limit=500
GET /catalog/products?limit=500&cursor=CURSOR_RECEBIDO
GET /catalog/products?updatedSince=2026-08-08T15:00:00.000Z
GET /catalog/prices?updatedSince=2026-08-08T15:00:00.000Z
GET /inventory/availability?updatedSince=2026-08-08T15:00:00.000Z

Produtos, preços e estoque têm relógios de alteração independentes. Sincronize as três rotas separadamente para não perder mudanças de preço ou saldo sem alteração cadastral.

5 · Pedidos

Do checkout ao CYNQUO sem duplicidade

Cada escrita exige o cabeçalho Idempotency-Key, com um UUID ou outro identificador estável do evento. Se o site repetir a mesma requisição após timeout, o CYNQUO devolve o pedido já processado. A mesma chave com conteúdo diferente retorna conflito.

POST /orders
Authorization: Bearer SEU_TOKEN
Idempotency-Key: 0195d8aa-5bb3-7bf2-932e-6fe7b14efc21
Content-Type: application/json

{
  "externalOrderId": "BASE44-10045",
  "status": "PAID",
  "createdAt": "2026-08-23T14:30:00.000Z",
  "currency": "BRL",
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@example.com",
    "document": "12345678909",
    "phone": "5562999999999"
  },
  "shippingAddress": {
    "street": "Rua Exemplo",
    "number": "100",
    "city": "Goiânia",
    "state": "GO",
    "postalCode": "74000000"
  },
  "items": [
    {
      "productId": "UUID_DO_PRODUTO",
      "sku": "20950",
      "name": "Produto",
      "quantity": 2,
      "unitPrice": 25.49,
      "discountTotal": 0,
      "total": 50.98
    }
  ],
  "payments": [
    {
      "externalPaymentId": "PAY-10045",
      "method": "PIX",
      "status": "CONFIRMED",
      "amount": 50.98
    }
  ],
  "subtotal": 50.98,
  "discountTotal": 0,
  "freightTotal": 0,
  "taxTotal": 0,
  "total": 50.98
}

• Use o SKU exatamente como recebido em /catalog/products.
• A empresa e a unidade vêm da chave; o corpo não pode trocar esse contexto.
• Pedido pago e reservado gera solicitações para emissão fiscal e picking.
• Saldo insuficiente mantém o pedido rastreável com divergência de estoque.
• Consulte a rota do pedido para refletir o status no e-commerce.

6 · Exemplos

Teste pelo backend do site

cURL

curl --request GET \
  --url 'https://erp.cynquo.com/api/external/v1/catalog/products?limit=100' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'

Node.js / TypeScript

const response = await fetch(
  'https://erp.cynquo.com/api/external/v1/catalog/products?limit=100',
  {
    headers: {
      Authorization: `Bearer ${process.env.CYNQUO_API_TOKEN}`,
      Accept: 'application/json',
    },
  },
);

if (!response.ok) throw new Error(`CYNQUO: ${response.status}`);
const page = await response.json();

Backend Base44

const response = await fetch(
  'https://erp.cynquo.com/api/external/v1/orders',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${Deno.env.get('CYNQUO_API_TOKEN')}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': order.eventId,
    },
    body: JSON.stringify(order),
  },
);

if (!response.ok) {
  throw new Error(`CYNQUO ${response.status}: ${await response.text()}`);
}
return await response.json();

No Base44, salve CYNQUO_API_TOKEN como segredo da função backend. Nunca exponha esse valor no frontend ou em uma entidade consultável pelo navegador.

7 · Operação

Erros e limites

400

Parâmetro, cursor ou formato inválido.

401

Chave ausente, inválida, expirada ou revogada.

403

Escopo ou IP não autorizado.

404

Registro inexistente ou fora da empresa da chave.

409

Idempotência reutilizada com outro conteúdo ou estado incompatível.

429

Limite por minuto excedido; aguarde e tente novamente.

5xx

Falha temporária; repita com backoff progressivo.

Use timeout, retentativas com backoff e idempotência no importador do site. Consulte a atividade da chave na Central de API para investigar falhas.