Skip to content

Recuperações de Vendas Internas

Visão Geral

O módulo de Recuperação de Vendas é uma ponte entre a venda assistida (backoffice) e o checkout público (loja).

Ele permite que um operador administrativo, após montar um carrinho para o cliente, gere um link seguro de fechamento.

Isso possibilita que o cliente finalize o pagamento em seu próprio dispositivo, utilizando seus métodos salvos e garantindo total privacidade nos dados sensíveis do cartão.

Este ecossistema opera sob o prefixo /carts/recovery para consultas gerenciais e utiliza um endpoint de escrita diretamente no recurso de carrinho (/carts/{cartId}/recovery) para disparar novas ações de recuperação.

---

Ciclo de Vida da Recuperação

1. Geração: O operador solicita um recoveryCode para um carrinho administrativo ativo. 2. Notificação: O sistema gera um snapshot e disponibiliza o código para ser enviado via E-mail, SMS ou WhatsApp. 3. Conversão: O cliente acessa o link, o sistema restaura o estado do carrinho na loja pública e a venda é concluída. 4. Rastreabilidade: O administrador acompanha o status (pendente, enviado, recuperado) através dos relatórios de listagem.

Entidades Envolvidas

  • Recovery Code: Um token alfanumérico único e temporário que serve como chave de acesso para restaurar o carrinho no front-end público.
  • Status de Recuperação: Indica a fase atual da tentativa, como notification-send (notificação enviada) ou recovered (venda concluída com sucesso).
  • Generated Order Group: ID do grupo de pedidos gerado após o sucesso da recuperação, permitindo cruzar dados de campanhas de recuperação com faturamento real.

    • Notas e Considerações

    Segurança e Integridade

    Uma vez gerada a recuperação, o sistema cria um vínculo persistente. Tentativas duplicadas para o mesmo carrinho retornarão o código já existente, a menos que as configurações da loja permitam a invalidação e re-geração.

    ---

    Escopos de Acesso

  • Leitura (RECOVERY_READ): Permite listar o histórico e visualizar detalhes de recuperações passadas.
  • Escrita (CART_WRITE): Necessária para o endpoint de criação, pois a geração de uma recuperação altera o estado e as permissões de visibilidade do carrinho administrativo.

---

Inteligência de Dados

Através da listagem de recuperações, gestores podem identificar quais canais de venda ou operadores possuem a melhor taxa de conversão em vendas assistidas, utilizando filtros por data e canal de venda.

Listagem de Recuperações (Admin)

GET /carts/recovery

Recupera o histórico de tentativas de recuperação de vendas assistidas com suporte a filtros de status e performance.

Descrição

Este endpoint fornece uma visão consolidada de todas as tentativas de recuperação disparadas pelo backoffice.

Ele é essencial para times de CX (Customer Experience) e gestores comerciais que precisam monitorar o funil de conversão das vendas assistidas.

Através desta listagem, é possível identificar quais links foram apenas gerados e quais efetivamente resultaram em uma venda concluída (recovered).

O suporte a filtros avançados permite segmentar o relatório por operador, data de criação ou canal de venda original.

---

Análise de Conversão

A listagem pode ser expandida via fields[] para incluir o objeto completo do carrinho ou o grupo de pedidos resultante.

Isso permite que sistemas de BI externos cruzem o valor original do rascunho com o valor final convertido, medindo a eficácia das campanhas de recuperação.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo RECOVERY_READ.

Parâmetros de Query

A API segue o padrão Uappi v3 para listagens.

ParâmetroTipoObrigatórioDescrição
limitintegerNãoRegistros por página (padrão: 10).
offsetintegerNãoDeslocamento da paginação (padrão: 0).
fields[]arrayNãoEntidades extras (ex: cart, orderGroup).
conditionobjectNãoFiltros (ver campos abaixo).
order[]arrayNãoOrdenação (ex: field=createdAt&order=desc).

Campos de Condição Disponíveis

CampoTipoDescrição
idintegerID único do registro de recuperação.
cartIdstringToken do carrinho administrativo vinculado.
statusstringStatus atual (ex: notification-send, recovered).
createdAtdateData de geração da recuperação.
recoveredAtdateData em que o cliente finalizou a compra.
salesChannelIdintegerID do canal de venda de origem.

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/carts/recovery?limit=10&offset=0&condition[status]=recovered' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "cartId": "CART123",
8        "orderGroupId": 10,
9        "generatedOrderGroupId": null,
10        "recoveryCode": "RECOVERY-TOKEN-123",
11        "status": "notification-send",
12        "createdAt": "2026-02-12 11:00:00",
13        "updatedAt": "2026-02-12 11:30:00",
14        "recoveredAt": null,
15        "cart": null,
16        "orderGroup": null
17      }
18    ],
19    "pagination": {
20      "limit": 10,
21      "offset": 0,
22      "pages": 1,
23      "registers": 1
24    }
25  }
26}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Código InternoCódigo HttpDescrição
UAPPI_AUTH_INVALID401Token ausente ou inválido.
UAPPI_SCOPE_FORBIDDEN403Falta a permissão RECOVERY_READ no token de acesso.
UAPPI_LISTING_INVALID_OPERATOR400Um operador de filtro inválido foi utilizado no objeto condition.

Detalhe de Recuperação (Admin)

GET /carts/recovery/{recoveryId}

Consulta informações detalhadas sobre uma tentativa específica de recuperação de venda.

Descrição

Este endpoint permite o detalhamento de um registro individual de recuperação.

Ele é utilizado para auditoria pontual ou para alimentar telas de acompanhamento de tickets de venda assistida. Através dele, é possível visualizar o código de recuperação exato (recoveryCode), o status de conversão e os timestamps de interação.

Diferente da listagem, o detalhe provê um objeto único, sendo ideal para integrações que precisam validar o sucesso de um link de recuperação em tempo real ou sincronizar o estado da venda com sistemas externos de mensageria.

---

Entidades Relacionadas

O uso do parâmetro fields[] permite expandir o detalhe para trazer o snapshot do carrinho (cart) ou o grupo de pedidos resultante (orderGroup).

Isso é fundamental para entender o que exatamente o cliente comprou após utilizar o link de recuperação enviado pelo operador.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo RECOVERY_READ.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
recoveryIdintegerSimIdentificador numérico único do registro de recuperação.

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/carts/recovery/1?fields[]=cart' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "cartId": "CART123",
6    "orderGroupId": 10,
7    "generatedOrderGroupId": null,
8    "recoveryCode": "ABC-RECOVERY-123",
9    "status": "notification-send",
10    "createdAt": "2026-02-12 11:00:00",
11    "updatedAt": "2026-02-12 11:30:00",
12    "recoveredAt": null,
13    "cart": {
14      "id": "CART-8f42dce0-20f0-4c4c-bb4f-9f8a16f6f471",
15      "currencyId": "BRL",
16      "countryCode": "BRA",
17      "quoteZipcode": "12123-123",
18      "subtotalValue": 259.9,
19      "shippingValue": 18.4,
20      "discountValue": 15,
21      "additionValue": 0,
22      "totalValue": 263.3,
23      "discountPreview": {
24        "cashDiscount": {
25          "discountPercentage": 5,
26          "discountValue": 13.17,
27          "valueWithDiscount": 250.13
28        },
29        "pointSystem": {
30          "name": "Programa Fidelidade Uappi",
31          "pointValue": 0.01,
32          "originalAmount": 2633,
33          "finalAmount": 2501,
34          "finalValue": 25.01
35        }
36      },
37      "installments": [
38        {
39          "installment": 1,
40          "installmentValue": 263.3,
41          "totalValue": 263.3,
42          "fee": 0,
43          "feeTotalValue": 0
44        },
45        {
46          "installment": 3,
47          "installmentValue": 89.05,
48          "totalValue": 267.15,
49          "fee": 1.5,
50          "feeTotalValue": 3.85
51        }
52      ],
53      "requestedProductMap": [
54        {
55          "productId": 1,
56          "quantity": 2,
57          "code": "PROMO-ADMIN",
58          "upsellId": null,
59          "productPairOfferId": null
60        },
61        {
62          "productId": 25,
63          "quantity": 1,
64          "code": null,
65          "upsellId": 7,
66          "productPairOfferId": 18
67        }
68      ],
69      "discountMap": {
70        "promotion": [
71          {
72            "discountId": 9001,
73            "discountType": "promotion",
74            "discountValue": 10,
75            "discountMainCode": "PROMO-10",
76            "discountTitle": "Promoção 10% categoria"
77          }
78        ],
79        "coupon": {
80          "discountId": 9002,
81          "discountType": "coupon",
82          "discountValue": 5,
83          "discountMainCode": "BEMVINDO5",
84          "discountTitle": "Cupom de boas-vindas"
85        },
86        "customer-wallet": null,
87        "point-system": null
88      },
89      "customer": {
90        "customerId": 345,
91        "nameCorporateName": "Mariana Souza",
92        "tradeName": "",
93        "email": "mariana.souza@cliente.com",
94        "document": "12345678909",
95        "gender": "female",
96        "isCorporate": false,
97        "nationality": "BRA",
98        "birthdate": "1992-08-14",
99        "phone": "+5511998765432"
100      },
101      "addresses": [
102        {
103          "addressId": 31,
104          "type": "delivery",
105          "zipCode": "12123-123",
106          "identification": "Casa",
107          "street": "Rua das Flores",
108          "number": "120",
109          "city": "São José dos Campos",
110          "complement": "Apto 22",
111          "district": "Jardim Primavera",
112          "state": "São Paulo",
113          "stateCode": "SP",
114          "countryCode": "BRA",
115          "recipient": "Mariana Souza",
116          "createdAt": "2026-05-05 10:10:00",
117          "updatedAt": "2026-05-05 10:12:00"
118        }
119      ],
120      "orders": [
121        {
122          "orderId": 1,
123          "quoteId": "quote-01",
124          "distance": 12,
125          "subtotalValue": 259.9,
126          "shippingValue": 18.4,
127          "discountValue": 15,
128          "additionValue": 0,
129          "totalValue": 263.3,
130          "service": false,
131          "storage": {
132            "id": 11,
133            "code": "CD-SP-01",
134            "corporateName": "Centro de Distribuição SP LTDA",
135            "email": "logistica.sp@uappi.com.br",
136            "phone": "+551133334444",
137            "tradeName": "CD São Paulo",
138            "stateCode": "SP",
139            "countryCode": "BRA",
140            "document": "12345678000199",
141            "zipCode": "01000-000",
142            "city": "São Paulo",
143            "address": "Avenida Logística",
144            "district": "Centro",
145            "number": "1000",
146            "complement": "Galpão B",
147            "latitude": "-23.55052",
148            "longitude": "-46.63331",
149            "active": true,
150            "observation": "Janela de coleta até 16h",
151            "tradePolicyExceptions": [
152              5,
153              7
154            ]
155          },
156          "items": [
157            {
158              "itemId": 1,
159              "productCategoryIds": [
160                15,
161                18
162              ],
163              "upsellId": null,
164              "productPairOfferId": null,
165              "productPriceRuleId": 3,
166              "productPriceRuleName": "Preço Atacado",
167              "quantity": 2,
168              "code": "PROMO-ADMIN",
169              "unitValue": 129.95,
170              "unitAdditionValue": 0,
171              "unitDiscountValue": 7.5,
172              "subtotalValue": 259.9,
173              "subtotalAdditionValue": 0,
174              "subtotalDiscountValue": 15,
175              "totalValue": 244.9,
176              "product": {
177                "productId": 1,
178                "brandId": 9,
179                "brandName": "Marca Exemplo",
180                "mainCategoryId": 15,
181                "mainCategoryName": "Tênis",
182                "type": "simple",
183                "sku": "SKU-001",
184                "name": "Tênis Running Pro",
185                "active": true,
186                "url": "tenis-running-pro",
187                "comparisonPrice": 149.9,
188                "stock": 25,
189                "medias": [
190                  {
191                    "id": 88,
192                    "type": "image",
193                    "title": "Foto frontal",
194                    "alternativeText": "Tênis Running Pro azul",
195                    "file": "products/tenis-running-pro-frontal.webp",
196                    "originalFile": "products/original/tenis-running-pro-frontal.jpg",
197                    "size": 148230,
198                    "originalSize": 423991,
199                    "width": 1200,
200                    "height": 1200,
201                    "url": "https://cdn.uappi.com.br/products/tenis-running-pro-frontal.webp"
202                  }
203                ],
204                "combination": [
205                  301,
206                  455
207                ],
208                "currentAttributes": [
209                  {
210                    "id": 12,
211                    "name": "Cor",
212                    "value": {
213                      "id": 455,
214                      "label": "Azul",
215                      "image": "attributes/color-blue.webp",
216                      "originalImage": "attributes/original/color-blue.png",
217                      "color": "#0033CC",
218                      "order": 2
219                    }
220                  },
221                  {
222                    "id": 13,
223                    "name": "Tamanho",
224                    "value": {
225                      "id": 301,
226                      "label": "42",
227                      "image": null,
228                      "originalImage": null,
229                      "color": null,
230                      "order": 4
231                    }
232                  }
233                ],
234                "restriction": {
235                  "tradePolicyId": 1,
236                  "requiredAge": 0
237                }
238              },
239              "discounts": [
240                {
241                  "cartOrderDiscountId": 9001,
242                  "cartOrderAdditionId": 0,
243                  "value": 10,
244                  "detail": {
245                    "rule": "PROMO-10-CATEGORIA",
246                    "scope": "item"
247                  }
248                }
249              ],
250              "additions": [
251                {
252                  "cartOrderDiscountId": 0,
253                  "cartOrderAdditionId": 7001,
254                  "value": 0,
255                  "detail": {
256                    "reason": "sem acrescimo aplicado"
257                  }
258                }
259              ]
260            }
261          ],
262          "additions": [
263            {
264              "additionType": "custom-value-rule",
265              "additionValue": 0,
266              "additionTitle": "Ajuste manual interno"
267            }
268          ],
269          "discounts": [
270            {
271              "discountId": 9001,
272              "discountType": "promotion",
273              "discountValue": 10,
274              "discountMainCode": "PROMO-10",
275              "discountTitle": "Promoção 10% categoria"
276            },
277            {
278              "discountId": 9002,
279              "discountType": "coupon",
280              "discountValue": 5,
281              "discountMainCode": "BEMVINDO5",
282              "discountTitle": "Cupom de boas-vindas"
283            }
284          ],
285          "shippingOptions": [
286            {
287              "shippingTableId": 55,
288              "shippingPickupPointId": 0,
289              "label": "Entrega padrão",
290              "shippingValue": 18.4,
291              "beginShippingTime": 2,
292              "endShippingTime": 5,
293              "shippingTimeType": "days",
294              "selected": true,
295              "details": {
296                "shippingTableId": 55,
297                "integrationCode": "uappi",
298                "externalShippingCode": "STD-55",
299                "carrierId": 17,
300                "carrierName": "Transportadora XPTO",
301                "label": "Entrega padrão",
302                "value": 18.4,
303                "beginShippingTime": 2,
304                "endShippingTime": 5,
305                "trackingUrl": "https://tracking.transportadora.com/{code}",
306                "row": {
307                  "id": 901,
308                  "initialZipcode": "12000-000",
309                  "finalZipcode": "12999-999",
310                  "initialWeight": 0,
311                  "finalWeight": 30,
312                  "initialPrice": 0,
313                  "finalPrice": 99999,
314                  "beginShippingTime": 2,
315                  "endShippingTime": 5,
316                  "shippingValue": 18.4,
317                  "variables": {
318                    "kg_factor": 1.2,
319                    "distance_factor": 0.8
320                  }
321                },
322                "pickups": [
323                  {
324                    "id": 100,
325                    "type": "internal",
326                    "selected": false,
327                    "name": "Loja Centro",
328                    "address": "Rua Quinze de Novembro",
329                    "number": "45",
330                    "district": "Centro",
331                    "city": "São José dos Campos",
332                    "countryCode": "BRA",
333                    "stateCode": "SP",
334                    "zipCode": "12210-000",
335                    "complement": "Retirar no balcão 2",
336                    "latitude": "-23.1895",
337                    "longitude": "-45.8841",
338                    "openingHours": "Seg-Sex 09:00-18:00"
339                  }
340                ],
341                "error": null
342              }
343            }
344          ]
345        }
346      ],
347      "errors": [
348        {
349          "identifier": 1,
350          "entity": "Payment",
351          "type": "warning",
352          "description": "Condição de pagamento indisponível para uma das parcelas.",
353          "error": "UAPPI_STORE_PAYMENT_CONDITION_UNAVAILABLE"
354        }
355      ],
356      "isMerged": false,
357      "createdAt": "2026-05-05 10:00:00",
358      "updatedAt": "2026-05-05 10:43:21"
359    },
360    "orderGroup": null
361  }
362}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_RECOVERY_NOT_FOUND404O registro de recuperação com o ID informado não foi encontrado.
UAPPI_SCOPE_FORBIDDEN403O usuário não possui o escopo necessário para visualizar recuperações.

Criar Recuperação de Carrinho (Admin)

POST /carts/{cartId}/recovery

Gera um link de recuperação seguro para que o cliente finalize a compra na loja pública a partir de um carrinho administrativo.

Descrição

Este endpoint é o motor da conversão no backoffice. Ele transforma um rascunho de venda assistida em uma oportunidade de fechamento na loja pública.

Ao ser acionado, o sistema gera um recoveryCode exclusivo que, quando anexado à URL da loja, restaura todo o estado do carrinho (itens, quantidades e vínculos) para o cliente.

Esta ação é ideal para concluir vendas onde o cliente prefere não compartilhar dados de pagamento por telefone ou chat, ou quando a negociação exige um tempo de maturação.

O operador gera o link e o envia através dos canais de comunicação da loja (Omnichannel).

---

Persistência e Conflitos

  • Código Único: Por padrão, o sistema retorna o mesmo código ativo se houver uma tentativa de duplicação para o mesmo carrinho, garantindo que o cliente não receba links conflitantes.
  • Validação de Estado: A criação falhará se o carrinho já tiver sido convertido em pedido, uma vez que a recuperação serve exclusivamente para fechar vendas pendentes.

---

Impacto no Fluxo Omnichannel

A geração da recuperação muda o status do carrinho no banco de dados, sinalizando que uma tentativa de conversão externa está em curso.

Se o cliente concluir a compra através deste link, o sistema marcará automaticamente a recuperação como recovered no histórico gerencial.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimToken identificador único do carrinho administrativo de origem.

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART123/recovery' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "cartId": "CART123",
6    "orderGroupId": null,
7    "generatedOrderGroupId": null,
8    "recoveryCode": "ABC-RECOVERY-123",
9    "status": "notification-send",
10    "createdAt": "2026-02-12 11:00:00",
11    "updatedAt": "2026-02-12 11:00:00",
12    "recoveredAt": null,
13    "cart": null,
14    "orderGroup": null
15  }
16}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho administrativo informado não foi encontrado.
UAPPI_STORE_CART_ORDER_EXISTS403Operação negada: o carrinho já possui um pedido finalizado.
UAPPI_STORE_CART_RECOVERY_ALREADY_EXISTS409Já existe um link de recuperação ativo para este carrinho.
UAPPI_STORE_CART_USER_MISMATCH403O operador não tem permissão para gerar recuperações para este carrinho.

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;