Zurcad · API

Integre cotação e rastreio ao seu sistema

Seu ERP, e-commerce ou painel interno consulta frete e status de carga sem digitar de novo. Dois endpoints, autenticação por chave.

Cotação instantânea Envie origem, destino e carga → receba preço e prazo quando a rota for elegível.
Rastreio de frete Consulte status e timeline da carga pelo código da proposta (ou pelo seu external_id).

Quero integrar

Fale com o comercial Zurcad no WhatsApp. Enviamos o acesso à API por e-mail.

Documentação mínima

Base: https://zurcad.com.br/api/v1 · Header: Authorization: Bearer zk_…

1) Cotar — POST /api/v1/quotes

curl -s -X POST https://zurcad.com.br/api/v1/quotes \
  -H "Authorization: Bearer zk_test_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "service_type": "carga",
  "origin": { "city": "São Paulo", "state": "SP" },
  "destination": { "city": "Campinas", "state": "SP" },
  "cargo": {
    "weight_kg": 50,
    "volume_m3": 0.2,
    "invoice_value_brl": 1500
  },
  "options": { "persist": false }
}'

2) Rastrear — GET /api/v1/shipments/{codigo}

curl -s "https://zurcad.com.br/api/v1/shipments/ZU123456R0" \
  -H "Authorization: Bearer zk_test_SUA_CHAVE" \
  -H "Accept: application/json"

Formato do cargo

{
  "weight_kg": 120,
  "volume_m3": 0.8,
  "invoice_value_brl": 4500,
  "description": "2 volumes eletrônicos",
  "items": [
    {
      "description": "Caixa",
      "qty": 2,
      "weight_kg": 60,
      "length_cm": 80,
      "width_cm": 40,
      "height_cm": 40
    }
  ]
}

Notas rápidas

Peso, volume e NF vão dentro de cargo (não na raiz do JSON).
Origem/destino: city+state ou cep.
Sem options.persist: true, a cotação não abre proposta no comercial.
Ping sem key: GET https://zurcad.com.br/api/v1/health

O que a API devolve (exemplos)

Cotação com preço (quote_status: priced). Com persist: true vêm codigo, persisted e link de rastreio. valid_until = validade comercial de 7 dias.

Resposta — POST /quotes

{
  "ok": true,
  "quote_id": "QK7M2A1B3C4D5E6F",
  "codigo": "ZU288535R0",
  "external_id": "PED-99881",
  "quote_status": "priced",
  "currency": "BRL",
  "price": 189.9,
  "price_formatted": "R$ 189,90",
  "valid_until": "2026-11-17",
  "eta": {
    "pickup": "1 dia útil",
    "delivery": "2 dias úteis"
  },
  "origin": "São Paulo - SP",
  "destination": "Campinas - SP",
  "persisted": { "orcamento_id": 12345, "proposta_id": 288535 },
  "links": { "track": "https://zurcad.com.br/rastreio-frete/ZU288535R0" }
}

Rastreio: status comercial + etapa atual + timeline (mais recente primeiro).

Resposta — GET /shipments/{codigo}

{
  "ok": true,
  "codigo": "ZU288535R0",
  "proposta_id": 288535,
  "commercial_status": "approved",
  "commercial_label": "Aprovada",
  "price": 189.9,
  "shipment": {
    "current_stage_code": "REMEDEST",
    "current_stage_label": "Em Trânsito para o Destino",
    "current_stage_status": "EM_ANDAMENTO",
    "timeline": [
      {
        "stage_code": "REMEDEST",
        "label": "Em Trânsito para o Destino",
        "status": "EM_ANDAMENTO",
        "at": "2026-11-12 14:30:00"
      },
      {
        "stage_code": "NOSSACOLETA",
        "label": "Coleta realizada",
        "status": "CONCLUIDO",
        "at": "2026-11-11 09:10:00"
      }
    ]
  }
}

Também dá para buscar por pedido do cliente: GET /api/v1/shipments?external_id=PED-99881.

Status da cotação e etapas do rastreio

Cotação (quote_status)

Valor	Significado
`priced`	Preço e prazo automáticos.
`manual_review`	Sem preço na hora: rota fora do automático, carga acima de ~30 t ou ~90 m³, ou regra de elegibilidade. A equipe analisa; com `persist: true` a proposta cai no comercial.
`rejected`	Fora da política (`policy_blocked`) — não segue.

Frete (commercial_status): pending, quoted, negotiating, approved, cancelled.

Timeline operacional (exemplos de stage_code): coleta (NOSSACOLETA), em trânsito (REMEDEST, BASEDEST), entregue (ENTREGUE). Use current_stage_label para exibir ao usuário.

Erros e limites

HTTP	`error_code`	Quando
401	`unauthorized`	Key ausente ou inválida.
404	`not_found`	Frete/código inexistente ou de outro cliente (mesmo retorno).
422	`validation_error` / `policy_blocked`	JSON inválido, campos faltando ou política de carga.
429	`rate_limited`	Estourou quota da key.

60 requisições / minuto por key (ajustável no perfil).
Teto diário em POST /quotes (fase de teste costuma ser 50/dia; sobe com cliente real).

Do teste à proposta (persist e external_id)

Sandbox (zk_test_…): integração e testes. Live (zk_live_…): produção.
options.persist: false (padrão): só calcula; não abre proposta no comercial.
options.persist: true: grava orçamento/proposta, devolve codigo (ex. ZU…) e a equipe vê no painel.
external_id: ID do pedido no seu sistema. Guarde e consulte depois com ?external_id= no rastreio.

Webhook de status

Existe aviso automático quando o frete muda de etapa (approved → collected → in_transit → delivered, com assinatura HMAC. É liberado sob pedido (URL + secret no perfil). Enquanto isso, o GET /shipments cobre o acompanhamento por polling.