# 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 1. **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. 2. **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` ```bash 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) ```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" } ``` ### Significado dos campos (request)
CampoTipoObrigatórioDescrição
`items`Array de objetoSimLista de itens no carrinho do PDV para avaliação de desconto.
`items[].category`stringRecomendadoCódigo de **categoria mercadológica** do item no PDV.
`items[].subcategory`stringOpcionalCódigo de **subcategoria** mercadológica.
`items[].code`stringSimIdentificador do produto (EAN/PLU/código interno).
`items[].product_name`stringRecomendadoDescrição do produto.
`items[].quantity`numberSimQuantidade do item.
`items[].unit_type`stringRecomendadoUnidade de medida (ex.: `um`, `kg`, `lt`).
`items[].unit_value`numberSimPreço unitário vigente no PDV (antes de desconto).
`registration`stringSimIdentificaçã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 ```json { "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)
CampoTipoDescrição
`response.code`numberCódigo de status interno do parceiro (200 = sucesso). Não substitui o HTTP status.
`response.discounts.products`arrayDetalhes de descontos por produto (quando aplicável).
`response.discounts.subtotal`numberDesconto total a ser aplicado no **subtotal** do carrinho (se houver).
`response.shop_id`stringIdentificador da loja/estabelecimento no parceiro.
`response.user`objetoDados do cliente no ecossistema do parceiro (endereços, saldos, pontos).
`response.user.st_token`stringToken de sessão/identificação do cliente no parceiro (usar conforme política do parceiro).
`response.user.total_balance`numberSaldo monetário de benefícios (se aplicável).
`response.user.total_points`numberPontos 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) ```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" } ``` ### Significado dos campos (request)
CampoTipoObrigatórioDescrição
`discounts`arrayOpcionalLista de descontos efetivamente aplicados na venda (quando o parceiro exige detalhar).
`items`arraySimItens efetivamente vendidos. Campos seguem a semântica da consulta, com **adição** de `total_value`.
`items[].total_value`numberSimValor total do item (já considerando quantidade e descontos).
`payment`objetoSimDados do pagamento da venda.
`payment.coupon`stringRecomendadoIdentificador do cupom/ECF/NSU no PDV (para auditoria).
`payment.date`string (ISO-8601)SimData/hora de fechamento da venda no PDV (ex.: `YYYY-MM-DDThh:mm:ss`).
`payment.paymethod[]`arraySimParcelas/meios de pagamento utilizados.
`payment.paymethod[].paymethod`number/stringSimCódigo do meio de pagamento (tabela acordada com o parceiro).
`payment.paymethod[].value`numberSimValor pago com o respectivo meio.
`payment.total`numberSimTotal da venda (soma dos pagamentos).
`registration`stringSimIdentificaçã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 ```json { "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)
CampoTipoDescrição
`response.code`numberCódigo de processamento no parceiro (200 = sucesso).
`response.points`numberPontos concedidos na venda.
`response.balance`numberSaldo monetário utilizado/remanescente após a venda (quando aplicável).
`response.future_balance`numberSaldo futuro (benefícios liberados em D+N, quando houver).
`response.user.total_points`numberPontos totais do cliente **após** a venda.
`response.user.total_balance`numberSaldo 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` ```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) ```json { "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` ```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) ```json { "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.