API de Integração Drezzo

Referência técnica para integradores. Versão 1.0 · https://api.drezzopay.com/v1

Visão geral

A API expõe os dados comerciais de um estabelecimento — vendas, itens, consumidores, estornos, catálogo e eventos — para consumo por sistemas externos.

Todos os endpoints são GET. A API é somente leitura.

Fluxo típico

1. GET /v1/sales?createdSince=…     lê as vendas novas
2. seu sistema processa
3. GET /v1/returns?createdSince=…   lê os estornos novos
4. seu sistema processa a devolução
5. guarda o timestamp e repete

Uma venda fica disponível assim que é registrada no PDV e seus valores não mudam depois disso — não é preciso esperar o evento acabar.

Autenticação

Authorization: Bearer dz_live_7f3a9c2e8b1d4a6f0e5c3b8a2d7f1e9c

Formato do token:

dz_<ambiente>_<32 hexadecimais>
     │
     ├── live    produção
     └── test    sandbox

O token é vinculado a uma ou mais lojas e determina o que pode ser lido. Pedir uma loja fora do escopo retorna 403.

Tokens são gerados pelo estabelecimento no Dashboard Drezzo, em Configurações → Chaves de API. A Drezzo guarda apenas o hash: um token perdido não pode ser recuperado, apenas revogado e substituído.

Convenções

Valores monetários

Todo valor monetário é inteiro, em centavos, e o nome do campo sempre termina em Cents. Não existe campo de dinheiro com casa decimal nesta API.

{ "unitPriceCents": 1500 }    // R$ 15,00
{ "totalAmountCents": 3300 }  // R$ 33,00

Datas e horários

Intervalos são inclusivos nas duas pontas. Janela máxima por consulta: 92 dias.

Paginação por cursor

{
  "data": [ … ],
  "pagination": { "nextCursor": "eyJ0IjoiMjAyNi0…", "hasMore": true }
}

Repita a chamada passando cursor=<nextCursor> até hasMore ser false. limit aceita até 500 (padrão 200).

Não usamos offset de propósito: numa varredura em que linhas novas chegam entre páginas, offset pula registros — e um registro pulado nunca chega ao seu sistema. O cursor ancora na última linha lida.

Parâmetros são validados

Parâmetro de query não reconhecido devolve 400, com o nome do que não foi entendido e a lista do que aquela rota aceita.

GET /v1/sales?customerId=8891

400 {"error":{"code":"invalid_parameter",
     "message":"Parâmetro não reconhecido: customerId. Aceitos nesta rota:
                storeId, eventId, customerDocument, from, to,
                createdSince, cursor, limit.", …}}

Busca por consumidor

O consumidor é identificado pelo documento — não expomos id interno de consumidor em lugar nenhum da API.

GET /v1/customers?document=12345678900              o consumidor
GET /v1/sales?customerDocument=12345678900          as compras dele
GET /v1/sales?customerDocument=…&eventId=1001       as compras dele num evento
GET /v1/events?customerDocument=12345678900         os eventos em que esteve

Aceita com ou sem máscara — 123.456.789-00 e 12345678900 chegam ao mesmo lugar. Documento desconhecido devolve lista vazia, nunca 404.

Limites

Ao exceder, retornamos 429 com Retry-After. Use backoff exponencial.

Compatibilidade

Mudanças aditivas — novos campos, novos endpoints, novos valores de enum — acontecem sem aviso na v1. Ignore campos desconhecidos e tenha um caso default para valores de enum não previstos. Mudanças incompatíveis ganham nova versão, com no mínimo 6 meses em paralelo.

Sincronização

Duas coleções são append-only: uma linha, uma vez criada, nunca muda.

Guarde o timestamp da última varredura, passe em createdSince e pagine por cursor. Nada precisa ser relido para detectar alteração, porque não existe alteração — só registros novos.

Estorno é registro novo, não alteração da venda

Quando parte de uma venda é devolvida, a venda original não muda. Um registro novo aparece em /v1/returns.

22:00  venda 12345 criada (2 chopes, R$ 30,00)
       você lê /v1/sales e processa. tudo certo.

23:30  operador estorna 1 chope dessa venda

23:35  você lê /v1/sales?createdSince=22:00
       -> a venda 12345 NÃO aparece.
          ela não foi alterada — continua idêntica.
          o estorno é um registro separado.

       você lê /v1/returns?createdSince=22:00
       -> aqui está: 1 unidade, R$ 15,00 devolvidos

Estorno é parcial por item: quantity pode ser menor que a quantidade vendida — no exemplo acima, 1 chope de 2. Use refundAmountCents como o valor da devolução, nunca o total da venda.

Evento aberto não é problema

Você pode processar vendas de um evento em andamento. A venda é final no instante em que é registrada

O que continua se movendo enquanto o evento está open são apenas os agregados do evento em /v1/events — totalAmountCents, customerCount, productsSold. Se o seu sistema faz conferência ou fechamento contra esses números, aí sim espere status: "closed". Para as vendas em si, não há espera.

Lojas

Lojas que a chave enxerga. Sem parâmetros. Loja é o estabelecimento com CNPJ próprio. Os pontos de venda (bares) compartilham o CNPJ da loja e não são entidades separadas.

{
  "data": [{
    "id": "6",
    "name": "Drezzo Bar",
    "document": "12345678000190",
    "timezone": "America/Sao_Paulo",
    "posLocations": [
      { "id": "12", "name": "Bar Central" }
    ]
  }]
}

Eventos

Vendas

endpoint principal Uma venda vem completa: itens, consumidor, taxa de serviço e totais. Não é preciso juntar endpoints para montar o registro.

{
  "data": [{
    "id": "12345",
    "storeId": "6",
    "orderNumber": 42,
    "event": { "id": "1001", "name": "Réveillon 2026", "date": "2026-07-20" },
    "occurredAt": "2026-07-20T23:15:42-03:00",
    "posLocation": { "id": "12", "name": "Bar Central" },
    "operator": { "id": "44", "name": "Maria Souza" },
    "customer": {
      "name": "João Silva",
      "document": "12345678900",
      "documentType": "CPF",
      "email": "joao@email.com",
      "phone": "11987654321"
    },
    "paymentMethod": "prepaid",
    "items": [{
      "id": "77001",
      "productId": "98765",
      "sku": "CHOPP300",
      "name": "Chopp 300ml",
      "categoryId": "5",
      "categoryName": "Chopes",
      "quantity": 2,
      "unit": "UN",
      "unitPriceCents": 1500,
      "grossAmountCents": 3000,
      "discountAmountCents": 0,
      "netAmountCents": 3000,
      "returnedQuantity": 0,
      "returnedAmountCents": 0
    }],
    "serviceFee": { "rateBps": 1000, "amountCents": 300, "waived": false },
    "totals": {
      "grossAmountCents": 3000,
      "discountAmountCents": 0,
      "netAmountCents": 3000,
      "serviceFeeAmountCents": 300,
      "returnedAmountCents": 0,
      "totalAmountCents": 3300
    },
    "createdAt": "2026-07-20T23:15:42-03:00"
  }],
  "pagination": { "nextCursor": "eyJ0IjoiMjAyNi0…", "hasMore": true }
}

Identidades garantidas

netAmountCents   = grossAmountCents − discountAmountCents
totalAmountCents = netAmountCents + serviceFeeAmountCents − returnedAmountCents

E, dentro de uma venda, sum(items[].discountAmountCents) fecha exatamente com totals.discountAmountCents. O desconto é registrado por venda e rateado por item proporcionalmente ao valor, com o resto do arredondamento no item de maior valor.

venda    1 × X-Tudo .......... R$ 28,50
         desconto ........... −R$ 10,00
         cliente pagou ...... R$ 18,50

estorno  registrado como ..... R$ 28,50   (preço cheio, sem o desconto)

totals   18,50 − 28,50 = −R$ 10,00

Observações de campo

• customer pode ser null — venda a consumidor não identificado.
• O consumidor é identificado pelo document.
• customer.email é frequentemente null: só é capturado no cadastro pelo aplicativo; quem entra pelo check-in no PDV costuma não fornecer. Trate a ausência sem falhar.
• serviceFee é null quando não há taxa. rateBps em basis points (1000 = 10%).
• A taxa de serviço nunca está embutida em unitPriceCents nem nos totais de mercadoria.

Estornos

Stream append-only de devoluções. É o canal para detectar estorno.

{
  "data": [{
    "id": "551",
    "saleId": "12345",
    "storeId": "6",
    "eventId": "1001",
    "productId": "98765",
    "sku": "CHOPP300",
    "productName": "Chopp 300ml",
    "quantity": 1,
    "refundAmountCents": 1500,
    "reason": "desistencia_com_estoque",
    "occurredAt": "2026-07-21T01:02:00-03:00"
  }],
  "pagination": { "nextCursor": null, "hasMore": false }
}

Case saleId com o registro que você já processou e trate a devolução por refundAmountCents. Um mesmo produto pode ter mais de um estorno na mesma venda.

Produtos

Catálogo dos produtos da loja. Se o seu sistema precisa de atributos próprios por produto (classificação, tributação, códigos internos), mantenha-os do seu lado chaveados por id ou sku.

Consumidores

Cadastro de consumidores da loja. O consumidor já vem embutido em cada venda de /v1/sales — este endpoint serve para buscar por documento e para sincronizar dado mestre.

Tabelas de referência

Meios de pagamento paymentMethod

Tipos de produto type

Status de evento status

Erros

{
  "error": {
    "code": "invalid_parameter",
    "message": "`from` deve estar no formato YYYY-MM-DD.",
    "field": "from",
    "requestId": "req_01HQ8XZ4K9M2N7P3"
  }
}

Cite sempre o requestId ao reportar um problema — ele localiza a requisição exata nos logs da Drezzo.

Checklist de homologação

1. Autenticar e listar lojas.
2. Percorrer um evento completo com paginação por cursor até hasMore: false.
3. Conferir as identidades de valores em todas as vendas do evento.
4. Sincronizar incrementalmente com createdSince e confirmar que nada é relido nem perdido.
5. Registrar um estorno parcial e confirmar que ele aparece em /v1/returns — é o teste que mais importa.
6. Tratar 429 com backoff exponencial.
7. Confirmar que uma venda offline traz occurredAt anterior a createdAt.

Primeira chamada

curl -H "Authorization: Bearer dz_live_…" \
  https://api.drezzopay.com/v1/stores