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                    (na 1ª vez, sem cursor)
2. percorra TODAS as páginas usando nextCursor
3. ao terminar, guarde o syncCursor da última resposta
4. na próxima execução, envie ?cursor=<syncCursor>
5. repita o mesmo processo em /v1/returns

Uma venda fica disponível assim que é registrada no PDV. Não é preciso esperar o evento acabar. Ver Sincronização para a semântica completa.

Autenticação

Authorization: Bearer dz_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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.

Contrato do cursor

O cursor é opaco e vinculado à rota e aos filtros da consulta que o gerou. Durante a paginação, mantenha os mesmos filtros e altere apenas cursor e, se quiser, limit.

O cursor não expira. Pode ser guardado por dias e retomado. Não é assinado criptograficamente, e não precisa ser: ele só escolhe posição dentro de um escopo que o token já autorizou, então adulterá-lo não dá acesso a nada.

400 {"error":{"code":"invalid_cursor",
     "message":"O cursor não pertence a esta rota ou não corresponde aos
                filtros informados.",
     "field":"cursor","requestId":"req_…"}}

Escopo da loja

Nas rotas que aceitam storeId, ele é opcional quando o token cobre exatamente uma loja e obrigatório quando cobre duas ou mais. Sua ausência no segundo caso retorna 400 store_required; pedir uma loja fora do escopo do token retorna 403.

GET /v1/sales/{id} não aceita storeId: o identificador da venda já é único, e o escopo sai das lojas do token.

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

O que é definitivo e o que é projeção

Os dados originais da venda são definitivos assim que ela é registrada: itens, quantidades, preços, descontos, forma de pagamento e valores cobrados não são alterados.

Alguns campos são projeções calculadas no momento da leitura e podem mudar quando novos estornos forem registrados:

/v1/sales é append-only para fins de descoberta: uma venda aparece uma única vez no stream incremental. Reconsultar a mesma venda pode devolver projeções de estorno atualizadas.

Retomada: use o syncCursor

Toda resposta de lista traz um syncCursor. A posição exata da última linha entregue. Guarde-o ao terminar a varredura e envie em cursor na próxima execução. A comparação é estrita, então retomar por ele é exatamente-uma-vez: sem lacuna e sem repetição.

GET /v1/sales?storeId=6
→ { "data": [...],
    "pagination": { "nextCursor": "eyJ0Ijo…", "hasMore": true },
    "syncCursor": "eyJ0Ijo…" }

  … percorra até hasMore: false …

→ { "data": [...],
    "pagination": { "nextCursor": null, "hasMore": false },
    "syncCursor": "eyJ0IjoiMjAyNi0…" }   ← guarde ESTE

próxima execução:
GET /v1/sales?storeId=6&cursor=eyJ0IjoiMjAyNi0…

Mesmo com o cursor, trate o processamento como idempotente por id. Uma queda entre "processei" e "salvei o cursor" faz a página anterior ser lida de novo.

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 + taxa R$ 3,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. o estorno é registro separado.

       você lê /v1/returns?createdSince=22:00
       -> aqui está: 1 unidade
          mercadoria R$ 15,00 + taxa R$ 1,50 = R$ 16,50

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,
      "reversedAmountCents": 0,
      "waived": false
    },
    "totals": {
      "grossAmountCents": 3000,
      "discountAmountCents": 0,
      "netAmountCents": 3000,
      "serviceFeeAmountCents": 300,
      "returnedAmountCents": 0,
      "returnedServiceFeeAmountCents": 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 − returnedServiceFeeAmountCents

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.

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,
    "serviceFeeRefundAmountCents": 150,
    "totalRefundAmountCents": 1650,
    "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.

totalRefundAmountCents = refundAmountCents + serviceFeeRefundAmountCents

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. Guardar o syncCursor, rodar de novo sem nada novo e confirmar que a resposta vem vazia.
5. Interromper uma varredura entre páginas e retomá-la pelo cursor, confirmando que nenhum registro se perde.
6. Reprocessar a última página e confirmar que o seu lado é idempotente por id.
7. Usar um cursor de /v1/sales em /v1/returns e confirmar 400 invalid_cursor.
8. Registrar um estorno parcial e confirmar que ele aparece em /v1/returns. É o teste que mais importa.
9. Tratar 429 com backoff exponencial.
10. Confirmar que uma venda offline traz occurredAt anterior a createdAt.

Primeira chamada

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