Integração PDV Avanço — Consulta de Descontos e Envio de Venda (Parceiros CRM) Objetivo Documentar o fluxo PDV → Parceiro de Fidelidade/Descontos (ex.: "crescevendas" como placeholder), com exemplos de requisição e retorno, e a explicação dos campos utilizados. O documento é genérico e pode ser aplicado a qualquer parceiro que exponha endpoints equivalentes. Visão geral do fluxo Consulta de descontos (pré-venda): o PDV envia os itens do carrinho + identificação do cliente → API do parceiro retorna descontos aplicáveis e dados do cliente. Envio da venda (pós-fechamento): o PDV registra a venda efetuada (itens, pagamento, total) → API do parceiro confirma pontos/saldo/benefícios concedidos e retorna os saldos finais. Observação: os nomes de host, caminhos e cabeçalhos abaixo são exemplos . Adapte-os ao parceiro real (ex.: https://{host-parceiro}/admin/api/v2/... ). Padrões comuns Formato : JSON (UTF-8). Métodos : POST para as operações descritas. Timeout recomendado no PDV : 30s. Autenticação : via cabeçalhos proprietários do parceiro (ex.: X-AdminUser-Email , X-AdminUser-Token ). Idioma : quando suportado, enviar Accept-Language: pt-BR . Cabeçalhos (exemplo) Accept: */* Content-Type: application/json Accept-Language: pt-BR,pt;q=0.8,en-US;q=0.6,en;q=0.4 charsets: utf-8 X-AdminUser-Email: X-AdminUser-Token: 1) Consulta de Descontos (pré-venda) Endpoint (exemplo): POST https://{host-parceiro}/admin/api/v2/shops Request — Exemplo de curl curl -k -m 30 -s -S \ -H "Accept: */*" \ -H "Content-Type: application/json" \ -H "Accept-Language: pt-BR,pt;q=0.8,en-US;q=0.6,en;q=0.4" \ -H "charsets: utf-8" \ -H "X-AdminUser-Email: " \ -H "X-AdminUser-Token: " \ -X POST \ --data-binary @inicia_parceiro.json \ "https://{host-parceiro}/admin/api/v2/shops" \ -o retorno_consulta.json --stderr erro_consulta.log -D header_consulta.txt Request — Corpo (exemplo) { "items": [ { "category": "046", "code": "00000000000017", "product_name": "CREME AMEND ALMOND B", "quantity": 1.0, "subcategory": "241", "unit_type": "um", "unit_value": 6.99 } ], "registration": "05940778690" } Significado dos campos (request) Campo Tipo Obrigatório Descrição items Array de objeto Sim Lista de itens no carrinho do PDV para avaliação de desconto. items[].category string Recomendado Código de categoria mercadológica do item no PDV. items[].subcategory string Opcional Código de subcategoria mercadológica. items[].code string Sim Identificador do produto (EAN/PLU/código interno). items[].product_name string Recomendado Descrição do produto. items[].quantity number Sim Quantidade do item. items[].unit_type string Recomendado Unidade de medida (ex.: um , kg , lt ). items[].unit_value number Sim Preço unitário vigente no PDV (antes de desconto). registration string Sim Identificação do cliente para o parceiro. Ex.: CPF (somente números). Boas práticas: Enviar unit_value já no valor de venda do PDV; o parceiro retornará descontos/propostas. Se houver mix de unidades (ex.: peso/quilagem), alinhar previamente com o parceiro como enviar e arredondar. Response — Exemplo { "response": { "code": 200, "discounts": { "products": [], "subtotal": 0.0 }, "shop_id": "0909092413", "user": { "address": { "adjunct": "", "city": "Belo Horizonte", "district": "Santa Efigênia", "number": 131, "phone": "(31) 33333-3333", "state": "Minas Gerais", "street": "Avenida Brasil", "zipcode": "30140-000" }, "name": "Heberth Minelli", "st_token": "11177821-d40a-40f8-9b58-9f50978682a9", "total_balance": 100.0, "total_points": 1969 } } } Significado dos campos (response) Campo Tipo Descrição response.code number Código de status interno do parceiro (200 = sucesso). Não substitui o HTTP status. response.discounts.products array Detalhes de descontos por produto (quando aplicável). response.discounts.subtotal number Desconto total a ser aplicado no subtotal do carrinho (se houver). response.shop_id string Identificador da loja/estabelecimento no parceiro. response.user objeto Dados do cliente no ecossistema do parceiro (endereços, saldos, pontos). response.user.st_token string Token de sessão/identificação do cliente no parceiro (usar conforme política do parceiro). response.user.total_balance number Saldo monetário de benefícios (se aplicável). response.user.total_points number Pontos acumulados (se aplicável). Aplicação no PDV: o PDV pode aplicar descontos retornados (por item e/ou subtotal) e exibir dados do cliente (nome, pontos, etc.), conforme regras da loja. 2) Envio da Venda (pós-fechamento) Endpoint (exemplo): POST https://{host-parceiro}/admin/api/v2/sales O caminho acima é exemplo . Alguns parceiros usam /shops/sales , /orders , etc. Alinhe o endpoint definitivo na homologação. Request — Corpo (exemplo) { "discounts": [], "items": [ { "category": "046", "code": "00000000000017", "product_name": "CREME AMEND ALMOND B", "quantity": 1.0, "subcategory": "241", "total_value": 6.99, "unit_type": "um", "unit_value": 6.99 }, { "category": "048", "code": "00000000000031", "product_name": "LEITE UHT PIRACANJUB", "quantity": 1.0, "subcategory": "269", "total_value": 1.0, "unit_type": "um", "unit_value": 1.0 } ], "payment": { "coupon": "02290621.99", "date": "2025-09-09T11:12:20", "paymethod": [ { "paymethod": 1, "value": 7.99 } ], "total": 7.99 }, "registration": "05940778690" } Significado dos campos (request) Campo Tipo Obrigatório Descrição discounts array Opcional Lista de descontos efetivamente aplicados na venda (quando o parceiro exige detalhar). items array Sim Itens efetivamente vendidos. Campos seguem a semântica da consulta, com adição de total_value . items[].total_value number Sim Valor total do item (já considerando quantidade e descontos). payment objeto Sim Dados do pagamento da venda. payment.coupon string Recomendado Identificador do cupom/ECF/NSU no PDV (para auditoria). payment.date string (ISO-8601) Sim Data/hora de fechamento da venda no PDV (ex.: YYYY-MM-DDThh:mm:ss ). payment.paymethod[] array Sim Parcelas/meios de pagamento utilizados. payment.paymethod[].paymethod number/string Sim Código do meio de pagamento (tabela acordada com o parceiro). payment.paymethod[].value number Sim Valor pago com o respectivo meio. payment.total number Sim Total da venda (soma dos pagamentos). registration string Sim Identificação do cliente no parceiro (ex.: CPF). Conciliação: payment.total deve bater com a soma de paymethod[].value . Para múltiplos meios, adicione entradas no array. Response — Exemplo { "response": { "balance": 0.0, "code": 200, "future_balance": 0.0, "points": 8, "user": { "address": { "adjunct": "", "city": "Belo Horizonte", "district": "Santa Efigênia", "number": 131, "phone": "(31) 33333-3333", "state": "Minas Gerais", "street": "Avenida Brasil", "zipcode": "30140-000" }, "name": "Heberth Minelli", "st_token": "11177821-d40a-40f8-9b58-9f50978682a9", "total_balance": 100.0, "total_points": 1977 } } } Significado dos campos (response) Campo Tipo Descrição response.code number Código de processamento no parceiro (200 = sucesso). response.points number Pontos concedidos na venda. response.balance number Saldo monetário utilizado/remanescente após a venda (quando aplicável). response.future_balance number Saldo futuro (benefícios liberados em D+N, quando houver). response.user.total_points number Pontos totais do cliente após a venda. response.user.total_balance number Saldo total do cliente após a venda (quando aplicável). Considerações de implementação (PDV) Idempotência: Recomenda-se enviar um identificador único por venda (ex.: payment.coupon + data) e, se o parceiro suportar, um cabeçalho Idempotency-Key para evitar lançamentos duplicados em reenvios. Tratamento de erros: Mapear HTTP status (ex.: 4xx/5xx ) e também response.code do corpo quando houver. Implementar retentativas somente para erros transitórios. Encoding: Garantir UTF-8 para nomes de produtos e logradouros; caso o parceiro retorne acentos com encoding incorreto, normalizar para exibição no PDV. Tabelas de referência: paymethod (meios de pagamento) e eventuais códigos de categoria/subcategoria devem ser alinhados e versionados entre PDV e parceiro. Segurança: Armazenar X-AdminUser-Token em cofre seguro. Nunca registrar token em logs de nível INFO/DEBUG. Observabilidade: Logar request-id, latência, tamanho de payload e resumo do resultado (sem PII sensível) para facilitar diagnósticos. Anexos — Arquivos de exemplo inicia_parceiro.json { "items": [ { "category": "046", "code": "00000000000017", "product_name": "CREME AMEND ALMOND B", "quantity": 1.0, "subcategory": "241", "unit_type": "um", "unit_value": 6.99 } ], "registration": "05940778690" } retorno_consulta.json (amostra) { "response": { "code": 200, "discounts": { "products": [], "subtotal": 0.0 }, "shop_id": "0909092413", "user": { "name": "Heberth Minelli", "st_token": "11177821-d40a-40f8-9b58-9f50978682a9", "total_balance": 100.0, "total_points": 1969 } } } venda_enviada.json { "discounts": [], "items": [ { "category": "046", "code": "00000000000017", "product_name": "CREME AMEND ALMOND B", "quantity": 1.0, "subcategory": "241", "total_value": 6.99, "unit_type": "um", "unit_value": 6.99 }, { "category": "048", "code": "00000000000031", "product_name": "LEITE UHT PIRACANJUB", "quantity": 1.0, "subcategory": "269", "total_value": 1.0, "unit_type": "um", "unit_value": 1.0 } ], "payment": { "coupon": "02290621.99", "date": "2025-09-09T11:12:20", "paymethod": [ { "paymethod": 1, "value": 7.99 } ], "total": 7.99 }, "registration": "05940778690" } retorno_venda.json (amostra) { "response": { "balance": 0.0, "code": 200, "future_balance": 0.0, "points": 8, "user": { "name": "Heberth Minelli", "st_token": "11177821-d40a-40f8-9b58-9f50978682a9", "total_balance": 100.0, "total_points": 1977 } } } Checklist de Homologação Confirmar endpoints definitivos (consulta e venda) e autenticação. Validar mapeamento de paymethod (códigos e formas aceitas). Verificar regras de arredondamento e casas decimais em itens/descontos. Ensaiar cenários com múltiplos meios de pagamento e cancelamento/estorno (se aplicável). Testar comportamento offline/timeout e diretrizes de reenvio (com idempotência). Observação: os exemplos de dados (CPF, nomes, tokens, códigos) são fictícios e servem apenas para demonstração. Substitua por valores reais na sua integração.