Conecte seu sistema ao CardZap

1. Seu primeiro pedido pela API

A integração permite ler pedidos e receber eventos. A API v1 não cria pedidos, altera status nem sincroniza o cardápio. Essas ações continuam no CardZap.

1. No painel da loja, abra Integrações → Chaves de API.
2. Crie uma chave com o nome do seu sistema e copie o valor completo. Ele aparece apenas uma vez.
3. No terminal do seu servidor, defina as variáveis abaixo e execute a consulta.

export CARDZAP_API_URL='https://cardzap.io/api/v1'
export CARDZAP_API_KEY='czk_SUBSTITUA_PELA_SUA_CHAVE'

curl --fail-with-body --get "$CARDZAP_API_URL/orders" \
  --header "Authorization: Bearer $CARDZAP_API_KEY" \
  --data-urlencode 'limit=1'

O resultado esperado é HTTP 200. Se a loja ainda não tem pedidos, data será uma lista vazia — isso também confirma que a autenticação funcionou. A listagem só inclui alterações com pelo menos 5 segundos.

2. Autenticação e acesso

URL base: https://cardzap.io/api/v1. Envie Authorization: Bearer czk_… em toda consulta. Cada chave acessa apenas os pedidos da loja onde foi criada; não é necessário enviar restaurant_id.

A chave de API (czk_…) autentica consultas. O segredo do webhook (whsec_…) valida eventos recebidos. São credenciais diferentes; use o valor completo, incluindo o prefixo.

Guarde ambos no servidor, em variáveis de ambiente. Eles não devem aparecer no código do navegador, em repositórios ou em logs. Para substituir uma chave, crie outra, atualize seu sistema e revogue a antiga no painel.

3. Consultar pedidos

GET /api/v1/orders

Retorna o estado atual dos pedidos, ordenados por updated_at crescente e, em caso de empate, por id. Todos os parâmetros são opcionais. Sem filtros, começa pelos pedidos mais antigos alterados.

curl --fail-with-body --get "$CARDZAP_API_URL/orders" \
  -H "Authorization: Bearer $CARDZAP_API_KEY" \
  --data-urlencode 'updated_since=2026-09-21T00:00:00Z' \
  --data-urlencode 'limit=50'

# Copie next_cursor da resposta anterior.
curl --fail-with-body --get "$CARDZAP_API_URL/orders" \
  -H "Authorization: Bearer $CARDZAP_API_KEY" \
  --data-urlencode 'cursor=COLE_NEXT_CURSOR_AQUI' \
  --data-urlencode 'limit=50'

{
  "api_version": "2026-09-18",
  "data": [
    {
      "id": "pedido_exemplo_42",
      "restaurant_id": "loja_exemplo",
      "number": 42,
      "code": "0042",
      "status": "NEW",
      "created_at": "2026-09-21T15:00:00.000Z",
      "updated_at": "2026-09-21T15:00:00.000Z",
      "completed_at": null,
      "cancelled_at": null,
      "expired_at": null,
      "fulfillment": "DELIVERY",
      "fulfillment_label": "Entrega",
      "table_label": null,
      "customer": {
        "name": "Ana (exemplo)",
        "phone": "5511999999999"
      },
      "address": "Rua Exemplo, 100",
      "notes": null,
      "payment": {
        "method": "PIX_ON_DELIVERY",
        "label": "Pix"
      },
      "items": [
        {
          "kind": "item",
          "item_id": "produto_exemplo",
          "combo_id": null,
          "name": "X-Burger",
          "external_code": "101",
          "quantity": 2,
          "unit_price_cents": 2500,
          "regular_unit_price_cents": null,
          "options": [
            {
              "name": "Bacon",
              "external_code": "B1",
              "price_cents": 200
            }
          ],
          "components": [],
          "total_cents": 5400
        }
      ],
      "promotions": [],
      "promo_discount_cents": 0,
      "subtotal_cents": 5400,
      "delivery_fee_cents": 500,
      "coupon": null,
      "total_cents": 5900
    }
  ],
  "has_more": false,
  "next_cursor": "MjAyNi0wOS0yMVQxNTowMDowMC4wMDBafHBlZGlkb19leGVtcGxvXzQy"
}

Enquanto has_more for true, continue com next_cursor. Quando for false, salve o cursor e consulte novamente depois; o cursor também vem em respostas vazias. Só avance o cursor depois de persistir todos os pedidos da página.

GET /api/v1/orders/{orderId}

curl --fail-with-body \
  -H "Authorization: Bearer $CARDZAP_API_KEY" \
  "$CARDZAP_API_URL/orders/ID_DO_PEDIDO"

Use o campo id, não o número de exibição code. A resposta é { "api_version": "2026-09-18", "data": { …pedido } }, sem paginação. Um pedido inexistente ou de outra loja retorna 404.

O limite atual é de 900 requisições por 15 minutos por chave (cerca de 1/s), compartilhado entre os dois endpoints e aplicado por instância do servidor. Distribua as chamadas e respeite Retry-After ao receber 429.

4. Receber pedidos automaticamente

1. Disponibilize um endpoint POST em uma URL HTTPS pública, por exemplo https://seu-sistema.com/webhooks/cardzap.
2. Em Integrações → Webhook, salve a URL e mantenha o webhook ativo.
3. Copie o segredo de assinatura para CARDZAP_WEBHOOK_SECRET no servidor receptor.
4. Use o botão de teste no painel. Seu endpoint receberá um ping; responda com HTTP 2xx.

Localhost, IPs privados e redirecionamentos não são aceitos. Para desenvolver localmente, exponha seu receptor por um túnel HTTPS público. O endpoint precisa responder em até 10 segundos.

{
  "id": "evt_exemplo_42",
  "type": "order.created",
  "api_version": "2026-09-18",
  "created_at": "2026-09-21T15:00:00.000Z",
  "data": {
    "order": {
      "id": "pedido_exemplo_42",
      "restaurant_id": "loja_exemplo",
      "number": 42,
      "code": "0042",
      "status": "NEW",
      "created_at": "2026-09-21T15:00:00.000Z",
      "updated_at": "2026-09-21T15:00:00.000Z",
      "completed_at": null,
      "cancelled_at": null,
      "expired_at": null,
      "fulfillment": "DELIVERY",
      "fulfillment_label": "Entrega",
      "table_label": null,
      "customer": {
        "name": "Ana (exemplo)",
        "phone": "5511999999999"
      },
      "address": "Rua Exemplo, 100",
      "notes": null,
      "payment": {
        "method": "PIX_ON_DELIVERY",
        "label": "Pix"
      },
      "items": [
        {
          "kind": "item",
          "item_id": "produto_exemplo",
          "combo_id": null,
          "name": "X-Burger",
          "external_code": "101",
          "quantity": 2,
          "unit_price_cents": 2500,
          "regular_unit_price_cents": null,
          "options": [
            {
              "name": "Bacon",
              "external_code": "B1",
              "price_cents": 200
            }
          ],
          "components": [],
          "total_cents": 5400
        }
      ],
      "promotions": [],
      "promo_discount_cents": 0,
      "subtotal_cents": 5400,
      "delivery_fee_cents": 500,
      "coupon": null,
      "total_cents": 5900
    }
  }
}

data.order tem exatamente o mesmo formato do pedido na API. O envelope representa o estado no momento do evento; created_at do envelope é a data do evento, e data.order.updated_at é a data da alteração do pedido.

// receptor.mjs — Node.js 20+, sem instalar dependências
import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

function assinaturaValida(rawBody, header, segredo) {
  if (typeof header !== "string") return false;
  const partes = Object.fromEntries(header.split(",").map((parte) => {
    const i = parte.indexOf("=");
    return [parte.slice(0, i).trim(), parte.slice(i + 1).trim()];
  }));
  const t = Number(partes.t);
  if (!Number.isInteger(t) || !/^[a-f0-9]{64}$/i.test(partes.v1 ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const esperado = createHmac("sha256", segredo)
    .update(`${t}.`).update(rawBody).digest();
  const recebido = Buffer.from(partes.v1, "hex");
  return recebido.length === esperado.length && timingSafeEqual(recebido, esperado);
}

const segredo = process.env.CARDZAP_WEBHOOK_SECRET;
if (!segredo) throw new Error("Defina CARDZAP_WEBHOOK_SECRET");

createServer(async (req, res) => {
  if (req.method !== "POST" || req.url !== "/webhooks/cardzap") {
    res.writeHead(404).end();
    return;
  }
  try {
    const partes = [];
    let tamanho = 0;
    for await (const parte of req) {
      tamanho += parte.length;
      if (tamanho > 1024 * 1024) { res.writeHead(413).end(); return; }
      partes.push(parte);
    }
    const rawBody = Buffer.concat(partes);
    if (!assinaturaValida(rawBody, req.headers["cardzap-signature"], segredo)) {
      res.writeHead(401).end();
      return;
    }
    const evento = JSON.parse(rawBody.toString("utf8"));
    // Demonstração de recebimento: não grava nem importa pedidos.
    // Em produção, persista o evento em uma fila/banco antes do 2xx.
    // Use evento.id como chave única e processe fora desta requisição.
    // O ping tem data.restaurant_id, sem data.order.
    console.log({ id: evento.id, tipo: evento.type });
    res.writeHead(204).end();
  } catch {
    res.writeHead(500).end();
  }
}).listen(3001, () => console.log("Receptor na porta 3001"));

export CARDZAP_WEBHOOK_SECRET='whsec_SUBSTITUA_PELO_SEGREDO'
node receptor.mjs

Valide a assinatura antes de interpretar o JSON, usando os bytes originais. Fazer JSON.parse e depois JSON.stringify pode alterar a assinatura. O exemplo recusa timestamps com mais de 5 minutos de diferença; mantenha o relógio do servidor sincronizado.

Sem resposta 2xx, são até 7 tentativas, com intervalos de 1 min, 5 min, 30 min, 2 h, 6 h e 12 h (aproximadamente 21 h no total). A fila é verificada a cada 5 minutos, portanto os intervalos não são horários exatos.

Ao pausar, eventos novos e pendentes ficam na fila sem consumir tentativas. Ao reativar, o envio é retomado pela rotina de 5 minutos. No histórico do painel, filtre falhas e reenvie eventos individualmente ou até 20 por vez, preservando o id do evento. Entregas finalizadas são removidas após 30 dias desde a criação; pendentes são preservadas até o processamento ou a remoção do webhook.

Gerar um novo segredo muda a assinatura das próximas tentativas, inclusive as pendentes. Atualize o receptor junto com essa troca.

5. Entenda os dados do pedido

Datas são strings ISO 8601 em UTC. Valores monetários são inteiros em centavos: 5900 significa R$ 59,00. Campos sem valor podem ser null; aceite também campos novos para manter compatibilidade.

total_cents = subtotal_cents
            - promo_discount_cents
            + delivery_fee_cents
            - (coupon?.discount_cents ?? 0)

# Exemplo: 2 lanches de R$ 25 + R$ 2 de adicional por lanche
# (2500 + 200) × 2 = 5400; entrega 500; total 5900.
# Se houver desconto por quantidade de 400 e cupom de 500:
# 5400 - 400 + 500 - 500 = 5000 (R$ 50,00).

Para conferir faturamento, considere apenas pedidos COMPLETED. NEW é um pedido pendente; CANCELLED e EXPIRED não representam venda concluída.

6. Evite duplicações e pedidos perdidos

1. Ative o recebimento antes da carga inicial. Armazene os eventos enquanto consulta os pedidos existentes pela API; depois processe ambos com a mesma regra de atualização.
2. Grave antes de confirmar. Receba o webhook, valide a assinatura e persista o evento em uma fila durável com id único. Só então responda 2xx. Uma repetição já persistida também deve receber 2xx.
3. Atualize pelo id do pedido. Webhooks podem chegar repetidos e fora de ordem. Compare updated_at atomicamente no banco; não substitua um pedido por uma versão mais antiga. Em um empate com conteúdo diferente, consulte GET /orders/{orderId} para reconciliar o estado atual.
4. Salve o cursor após processar a página. Se a importação falhar, repita a mesma página. Evite o filtro de status numa sincronização geral: filtrar NEW, por exemplo, não informa que um pedido passou para COMPLETED.
5. Reconcilie periodicamente. Recomece uma consulta separada com updated_since anterior ao último horário sincronizado e percorra todas as páginas. Uma janela de sobreposição (por exemplo, 1 hora) ajuda a recuperar transações demoradas; ajuste ao seu cenário e faça verificações mais amplas. Não envie o cursor anterior ao iniciar essa reconciliação.

A API retorna estado atual, não um histórico de eventos. A espera de 5 segundos reduz, mas não elimina, o risco de transações que confirmam tarde. Não dependa apenas de avançar o cursor para sempre.

7. Resolver problemas

{
  "error": "Chave de API inválida.",
  "code": "UNAUTHORIZED",
  "reqId": "identificador-da-requisicao"
}

8. Valide antes de colocar em uso

• Consulte a API com uma chave válida e confira a resposta 401 com uma chave inválida.
• Receba o ping e depois um pedido real de teste; confirme o mesmo id na API e no webhook.
• Confira adicionais, combos, promoções, cupom e taxa de entrega, incluindo o total em centavos.
• Teste retirada e mesa, quando habilitadas, com os campos opcionais ausentes.
• Conclua ou cancele um pedido no painel e confirme a atualização no seu sistema.
• Faça o receptor responder 500 em um teste controlado e confira o reenvio sem duplicar o pedido. Teste também eventos fora de ordem.
• Percorra mais de uma página com limit=1 e retome uma consulta após uma resposta vazia.
• Interrompa e retome seu integrador, verificando a fila persistente, o cursor salvo e a reconciliação.

Os exemplos usam dados fictícios. Faça os testes em uma loja destinada à validação ou combine os pedidos de teste com o lojista: os endpoints usam os dados reais da loja vinculada à chave.