Skip to content

Pagamentos e Fechamento no Contexto Interno

Visão Geral

O módulo de Pagamentos e Fechamento representa a etapa final e mais crítica do ciclo de vida de um carrinho administrativo.

É através dele que um rascunho operacional é convertido em um pedido oficial (Order), disparando os processos fiscais, logísticos e financeiros da plataforma Uappi.

Diferente do checkout público, o fechamento administrativo oferece flexibilidade para lidar com diferentes modalidades de liquidação:

1. Inspeção: O operador consulta as formas de pagamento permitidas para o Canal de Venda do carrinho. 2. Seleção: Uma forma de pagamento é "marcada" como a escolhida para a negociação. 3. Efetivação: O pedido é gerado através da captura imediata de valores ou pela comunicação de transações já processadas externamente.

---

Modalidades de Fechamento

A API disponibiliza três caminhos distintos para a geração do pedido, dependendo da origem da transação financeira:

  • Fechamento Nativo (POST /buy): Utilizado quando o gateway de pagamento da loja deve realizar a captura síncrona dos valores (ex: digitação de cartão de crédito no painel ou geração de PIX/Boleto nativo).
  • Fechamento Externo (POST /create-order): Utilizado para conciliar vendas onde o pagamento ocorreu por fora da plataforma (ex: links de pagamento de terceiros, máquinas físicas de cartão ou faturamento direto via ERP).
  • Link de Pagamento (POST /generate-payment-code): O pedido é criado imediatamente, sem cobrança, e um link público é gerado para que o próprio cliente final conclua o pagamento posteriormente através de um formulário/iframe (veja Consultar Pedido pelo Link de Pagamento).

    • Entidades Envolvidas

  • Payment Option: Uma configuração comercial que amarra o método (PIX, Crédito, etc.) às credenciais do gateway e às regras de parcelamento e desconto.
  • Internal Sale Settings: Objeto de contexto que armazena a pré-seleção do pagamento feita pelo operador antes do clique final de compra.
  • Transactions: Representam o rastro financeiro do pedido, contendo IDs de autorização, status de liquidação e dados técnicos do provedor.

    • Notas e Considerações

    Pré-requisitos de Integridade

    O fechamento é uma operação protegida por múltiplas travas de negócio. O sistema impedirá a geração do pedido se:

  • Não houver um cliente vinculado.
  • Os endereços de entrega e faturamento estiverem incompletos.
  • Nenhuma opção de frete tiver sido selecionada.
  • O estoque de algum item tiver se esgotado durante a montagem do carrinho.

---

Segurança PCI e Dados Sensíveis

Ao lidar com capturas nativas de cartão de crédito no ambiente administrativo, é mandatório que a interface utilize as melhores práticas de segurança.

Tokens de acesso com escopo CART_WRITE são exigidos para todas as ações deste módulo, garantindo que apenas operadores autorizados possam manipular dados financeiros e concluir vendas.

Opções de Pagamento do Carrinho (Admin)

GET /carts/{cartId}/payments

Lista as formas de pagamento disponíveis para o carrinho, simulando parcelamentos e descontos conforme a política comercial.

Descrição

Este endpoint atua como o simulador financeiro do carrinho administrativo.

Ao ser chamado, o sistema cruza o valor total do carrinho (Grand Total) com as regras do Canal de Venda vinculado para retornar todas as modalidades de pagamento elegíveis para aquela negociação.

A resposta fornece uma visão detalhada para cada opção, incluindo:

  • Tabelas de Parcelamento: Quantidade máxima de parcelas, valores de cada parcela e possíveis juros configurados.
  • Descontos à Vista: Aplicação de incentivos para métodos como PIX ou Boleto, calculados em tempo real sobre o saldo do carrinho.
  • Credenciais de Gateway: Informações técnicas sobre qual provedor processará a transação.

---

Personalização por Contexto

As opções retornadas podem variar dependendo do valor do carrinho (ex: valor mínimo para parcelamento) ou do perfil do cliente vinculado.

É uma etapa indispensável para que o operador informe ao cliente exatamente quais as condições financeiras disponíveis antes de prosseguir para a seleção definitiva.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimIdentificador único do carrinho administrativo.

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "paymentOption": {
6        "id": 2,
7        "tradePolicyId": 1,
8        "paymentId": 2,
9        "paymentCode": "pix",
10        "paymentStoreCredentialId": 15,
11        "paymentAntiFraudCredentialId": null,
12        "paymentType": {
13          "id": 1,
14          "code": "pix"
15        },
16        "active": true,
17        "label": "PIX Instantâneo",
18        "description": "Pagamento via PIX com desconto",
19        "instruction": "O QR Code será gerado após a finalização.",
20        "order": 1,
21        "options": null,
22        "configurations": {},
23        "publicCredentials": {
24          "publicKey": "pk_test_..."
25        },
26        "createdAt": "2026-03-01 10:00:00",
27        "updatedAt": "2026-03-20 15:30:00"
28      },
29      "cashDiscount": {
30        "discountPercentage": 5.00,
31        "discountValue": 5.50,
32        "valueWithDiscount": 104.50
33      },
34      "installments": [
35        {
36          "installment": 1,
37          "installmentValue": 104.50,
38          "totalValue": 104.50,
39          "fee": 0,
40          "feeTotalValue": 0
41        }
42      ],
43      "error": null
44    }
45  ]
46}

⚠️ 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 informado não foi encontrado ou o token é inválido.
UAPPI_STORE_CART_CUSTOMER_IS_DISABLED401O titular do carrinho possui restrições cadastrais e não pode visualizar opções de pagamento.
UAPPI_STORE_CART_EMPTY400Carrinhos sem itens não possuem opções de pagamento simuladas.
UAPPI_STORE_CART_ORDER_EXISTS403O carrinho já foi convertido em pedido; as opções de pagamento não podem mais ser consultadas.

Definir Pagamento do Carrinho (Admin)

PUT /carts/{cartId}/payment

Registra a forma de pagamento escolhida para a negociação assistida no contexto do carrinho administrativo.

Descrição

Este endpoint permite que o operador "marque" formalmente qual será a modalidade de pagamento utilizada para fechar a venda.

Ele funciona como uma gravação de intenção: ao enviar o paymentOptionId, o sistema atualiza as configurações internas de venda do carrinho, preparando o terreno para a geração do pedido final.

A definição do pagamento é um passo obrigatório para fluxos que utilizam o endpoint de fechamento nativo (POST /buy).

Sem esta escolha prévia, o domínio de Store não terá a referência de qual gateway ou regra de parcelamento deve aplicar no momento da captura.

---

Persistência da Escolha

Uma vez definida, a opção de pagamento fica salva no objeto cartInternalSaleSettings (visível no detalhe do carrinho).

Esta escolha pode ser substituída a qualquer momento por uma nova chamada a este endpoint ou removida via DELETE, permitindo que o operador ajuste a forma de pagamento conforme a evolução da conversa com o cliente.

---

Validações Comerciais

O backend valida se o paymentOptionId enviado é de fato uma das opções retornadas pelo endpoint de listagem de pagamentos.

Tentar definir um método de pagamento que não pertença à política comercial do Canal de Venda do carrinho resultará em erro de validação.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.
Content-Typeapplication/jsonTipo de conteúdo da requisição.

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
cartIdstringSimIdentificador único do carrinho administrativo.

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
paymentOptionIdintegerSimID da opção de pagamento selecionada (ex: ID do PIX, Cartão, etc.).

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/carts/CART123/payment' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "paymentOptionId": 2
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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_INVALID_PAYMENT_OPTION403A opção de pagamento enviada não é permitida para este carrinho ou canal de venda.
UAPPI_STORE_CART_USER_MISMATCH403O operador não tem permissão para alterar as configurações deste carrinho.
UAPPI_STORE_CART_ORDER_EXISTS403O carrinho já possui um pedido e seu método de pagamento não pode mais ser alterado.

Remover Pagamento do Carrinho (Admin)

DELETE /carts/{cartId}/payment

Limpa a opção de pagamento previamente selecionada no carrinho administrativo.

Descrição

Este endpoint desfaz a seleção de pagamento realizada anteriormente via PUT.

Ele limpa o campo paymentOptionId nas configurações internas do carrinho, permitindo que o operador reinicie o processo de negociação financeira ou remova a intenção de fechamento por um método específico.

A remoção é uma operação segura e idempotente: se não houver pagamento selecionado, a chamada retornará sucesso sem alterações.

É o método recomendado para garantir que o carrinho não possua uma "forma de pagamento fantasma" antes de o operador realizar uma nova cotação ou mudar o titular da venda.

---

Autenticação e Permissões

Assim como a definição, a remoção exige o escopo CART_WRITE. O sistema garante que apenas o operador responsável (ou um administrador autorizado) possa realizar a limpeza, mantendo a consistência do atendimento assistido.

---

Impacto no Fluxo de Fechamento

Após a execução bem-sucedida deste endpoint, qualquer tentativa de chamar o fechamento nativo (POST /buy) resultará em erro, uma vez que a referência de pagamento obrigatória terá sido removida do contexto do carrinho.

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.

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true

⚠️ 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_USER_MISMATCH403O operador não tem permissão para manipular as configurações deste carrinho.
UAPPI_STORE_CART_ORDER_EXISTS403O carrinho já possui um pedido finalizado; o pagamento histórico não pode ser removido por este caminho.

Fechamento de Carrinho (Admin)

POST /carts/{cartId}/buy

Converte o carrinho administrativo em um pedido real, processando opcionalmente a captura de pagamentos via cartão ou métodos nativos.

Descrição

Este endpoint é o responsável pela finalização síncrona da venda assistida.

Ele consolida todos os dados de itens, cliente, endereços e frete do carrinho e tenta gerar o pedido.

Se o operador enviar dados de pagamento (como número de cartão ou tokens), o sistema realizará a tentativa de captura junto ao gateway de pagamento configurado.

É o método preferencial para fechamentos onde o operador administrativo está em contato direto com o cliente e possui os dados necessários para processar a liquidação na mesma chamada.

Caso o pagamento já tenha ocorrido de forma externa, deve-se utilizar o endpoint create-order.

---

Captura de Pagamento (PCI)

O sistema permite a recepção de dados sensíveis de cartão através do array payments[].

É imperativo que a aplicação front-end que consome este endpoint utilize conexões seguras (HTTPS) e siga os protocolos de segurança vigentes.

O backend da Uappi encapsula a comunicação com os provedores, garantindo que o pedido só nasça com status paid se a autorização financeira for concedida em tempo real.

---

Pré-requisitos Mandatórios

Antes de chamar este endpoint, o carrinho deve obrigatoriamente ter: 1. Um cliente vinculado. 2. Endereço de entrega e faturamento definidos. 3. Ao menos uma opção de frete selecionada. 4. Uma forma de pagamento pré-selecionada via PUT /payment (caso o corpo da requisição buy não envie liquidações explícitas).

Conclusão do pedido por URL externa

É possível que um cliente escolha concluir seu pedido com uma forma de pagamento externa ou um pagamento personalizado que possui URL externa configurada.

No primeiro caso, o pedido ainda será gerado aguardando pagamento.

Já no segundo caso o processo de fechamento do pedido será abortado na etapa de pagamento, qualquer reserva gerada nesse processo será cancelada e um novo grupo de dados será retornado do endpoint.

Isso permitirá que o frontend redirecione o cliente para o ambiente externo desejado, onde ele poderá pagar pelo seu pedido.

No caso de um pagamento personalizado com URL externa, será necessário que o ambiente externo (onde as transações foram efetuadas) efetue uma chamada para o endpoint de Fechamento de Carrinho com Transações já Criadas.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.
Content-Typeapplication/jsonTipo de conteúdo da requisição.

Parâmetros da URL

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
paymentsarray✅Lista das formas de pagamento desejadas
payments.*.paymentOptionIdinteger✅Identificador da opção de pagamento a ser utilizada
payments.*.card.numberstring, numericObrigatório na presença de qualquer outro campo referente a cartãonúmero do cartão de crédito para identificação geral. (max: 16, min: 13)
payments.*.card.cvvstring, numericObrigatório na presença de qualquer outro campo referente a cartãoCVV do cartão para veracidade do cartão (max: 4)
payments.*.card.monthintegerObrigatório na presença de qualquer outro campo referente a cartãoMês de vencimento do cartão (max: 2)
payments.*.card.yearintegerObrigatório na presença de qualquer outro campo referente a cartãoAno de vencimento do cartão (max: 4)
payments.*.card.namestringObrigatório na presença de qualquer outro campo referente a cartãoNome do titular do cartão (max: 100)
payments.*.card.documentstring, numeric❌Documento válido do titular do cartão (max: 14)
payments.*.card.tokenstring❌Token do cartão (max: 400)
payments.*.card.idstring❌Identificador do cartão (max 100)
payments.*.phoneNumberstring❌Número de telefone do pagador
payments.*.documentstring, numeric❌Documento do pagador (max 14)
payments.*.accountstring, numeric❌Conta do pagador
payments.*.selectedInstallmentintegerObrigatório na presença de qualquer outro campo referente a cartãoQuantidade de parcelas selecionadas (min: 1)
payments.*.valuenumericObrigatório se o campo payments possuir qualquer valorValor do pagamento

Exemplo de Requisição (com Cartão)

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART123/buy' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "payments": [
7      {
8        "paymentOptionId": 1,
9        "selectedInstallment": 1,
10        "card": {
11          "number": "4000000000000010",
12          "cvv": "123",
13          "month": 12,
14          "year": 2030,
15          "name": "TITULAR DO CARTAO"
16        }
17      }
18    ]
19  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"id": 345,
5		"cartId": "ac66ca1d61577b216979169",
6		"tradePolicyId": 1,
7		"userId": null,
8		"userEmail": null,
9		"userName": null,
10		"code": "345",
11		"salesChannelDomain": "sua-loja.com.br",
12		"marketplaceId": null,
13		"marketplaceName": null,
14		"marketplaceStoreCredentialId": null,
15		"marketplaceOrderGroupId": null,
16		"currency": "BRL",
17		"createdAt": "2026-03-31 14:30:06",
18		"issuedAt": "2026-03-31 11:30:06"
19	}
20}

✅ Resposta de Sucesso com Pagamento Externo

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"cartId": "43410917165046c31c57021",
5		"paymentOptionId": 14,
6		"paymentUrl": "https://url-external.com?cartId=43410917165046c31c57021&paymentOptionId=14"
7	}
8}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

⚠️ Erros de Pedido:

Código InternoCódigo HttpDescrição
UAPPI_STORE_ORDER_DUPLICATED_CART_ID400O id do carrinho solicitado já está em uso.
UAPPI_STORE_ORDER_INVALID_QUANTITY400O número de pedidos enviado precisam ser maior ou igual a 1.
UAPPI_STORE_ORDER_MISSING_SHIPPING_OPTION400Nenhuma opção de frete está disponível para o pedido.
UAPPI_STORE_ORDER_REQUIRED_SHIPPING_OPTION400Pelo menos uma opção de frete é obrigatória para concluir o pedido.
UAPPI_STORE_ORDER_INVALID_PICKUP_POINT400O ponto de retirada solicitado é inválido.
UAPPI_STORE_ORDER_CUSTOMER_REQUIRED400O cliente é obrigatório para criar o pedido.
UAPPI_STORE_ORDER_INVALID_CUSTOMER400O cliente solicitado não é válido.
UAPPI_STORE_ORDER_INVALID_ADDRESS400É necessário prover um endereço do tipo "Ambos" ou 2 endereços sendo um de cobrança e o outro de entrega.
UAPPI_STORE_ORDER_INVALID_ITEM400O item requisitado é invalido.
UAPPI_STORE_ORDER_PRODUCT_CANNOT_BE_SOLD400O produto solicitado não pode ser vendido.
UAPPI_STORE_ORDER_PRICE_RULE_NOT_FOUND404A regra de preço solicitada não foi encontrada.
UAPPI_STORE_ORDER_INVALID_PRICE_RULE400A regra de preço solicitada é inválida.
UAPPI_STORE_ORDER_GROUP_NOT_FOUND404O grupo de pedido solicitado não foi encontrado.
UAPPI_STORE_ORDER_NOT_FOUND404O pedido solicitado não foi encontrado.
UAPPI_STORE_ORDER_STATUS_NOT_FOUND404O status de pedido solicitado não foi encontrado.
UAPPI_STORE_ORDER_PAYMENT_FAIL400Erros ocorreram durante o pagamento do pedido.
UAPPI_STORE_ORDER_INSERT_FAIL500Não foi possível inserir os registros de pedido no banco de dados.
UAPPI_STORE_CREATE_ORDER_PAYMENT_MISSING400Para criar o pedido, é necessário que não haja pagamentos pendentes.
UAPPI_STORE_ORDER_PAYMENT_REQUIRED400É necessário efetuar pelo menos um pagamento para que o pedido seja concluído.
UAPPI_STORE_DUPLICATED_ORDER_ALTERATION400A alteração de pedido solicitada já existe.
UAPPI_STORE_INVALID_ORDER_ALTERATION_VALUE400O valor para a alteração do pedido é inválida.
UAPPI_STORE_ORDER_INVALID_STORAGE400Os armazéns solicitados são inválidos. (orders[...])
UAPPI_STORE_CART_ORDER_EXISTS403Tentativa de fechamento duplicado: este carrinho já gerou um pedido anteriormente.

⚠️ Erros de Promocionais:

Código InternoCódigo HttpDescrição
UAPPI_STORE_APPLY_PROMOTIONAL_UNAVAILABLE400Os promocionais solicitados não estão disponíveis (1, 2, 3).
UAPPI_STORE_APPLY_PROMOTIONAL_DISABLED400A promoção solicitada não pode ser aplicada, pois não está ativa.
UAPPI_STORE_APPLY_PROMOTIONAL_OUT_OF_SCHEDULE400A promoção solicitada não pode ser aplicada pois está fora do período de vigência.
UAPPI_STORE_APPLY_PROMOTIONAL_MAX_USE400A promoção solicitada não pode ser aplicada, pois atingiu o limite máximo de utilização.
UAPPI_STORE_APPLY_PROMOTIONAL_ORDER_QUANTITY400A promoção solicitada não pode ser aplicada, pois o cliente não atende aos requisitos de quantidade do pedido.
UAPPI_STORE_APPLY_PROMOTIONAL_DISCOUNT_UNAVAILABLE400A promoção não pode ser aplicada, pois não há desconto disponível.
UAPPI_STORE_APPLY_PROMOTIONAL_MISSING_TRADE_POLICY400A promoção solicitada não inclui o link para a política comercial.
UAPPI_STORE_APPLY_PROMOTIONAL_INSUFFICIENT_BALANCE400A promoção solicitada não pode ser aplicada porque seu saldo é insuficiente.
UAPPI_STORE_POINT_SYSTEM_INVALID_EXPIRATION_DATE400A data de validade solicitada deve ser posterior à data atual.
UAPPI_STORE_POINT_SYSTEM_INVALID_VALUE400O valor da transação solicitada deve ser maior que zero.

⚠️ Erros de Armazém e Estoque:

Código InternoCódigo HttpDescrição
UAPPI_STORE_SALE_WITHOUT_STOCK_ACTIVE400A operação solicitada não pode continuar porque o produto estava à venda sem estoque disponível.
UAPPI_STORE_STOCK_UPDATE_PRODUCT_WITH_VARIATION_STOCK400O produto tem variações e não pode receber mudança de estoque.
UAPPI_STORE_STOCK_INSUFFICIENT_AVAILABLE_STOCK400A quantidade solicitada para a operação de reserva de estoque não está disponível.
UAPPI_STORE_STOCK_BELLOW_MINIMUM400O estoque do produto solicitado está abaixo do mínimo.
UAPPI_STORE_STOCK_INSUFFICIENT_RESERVED_STOCK400O produto solicitado possuí variações e não pode receber atualização de estoque
UAPPI_STORE_RESERVE_INVALID_UPDATE_STATUS400O status solicitado não pode ser aplicado à reserva.
UAPPI_STORE_RESERVE_MUST_BE_TYPE_ORDER400Para realizar esta ação, a reserva solicitada deve ser do tipo pedido.
UAPPI_STORE_STORAGE_NOT_FOUND404Os armazéns solicitados (1, 2, 3) não foram encontrados.
UAPPI_STORE_RESERVE_ALREADY_FINISHED409Impossível continuar a ação, a reserva já foi finalizada.
UAPPI_STORE_RESERVE_NOT_FOUND404A reserva solicitada não foi encontrada.
UAPPI_STORE_STORAGE_NOT_FOUND404O armazém solicitado não foi encontrado.

⚠️ Outros tipos de Erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND404A regra de preço solicitada não foi encontrada.
UAPPI_STORE_INVALID_ADDRESS404Os endereços solicitados 1, 2, 3 são inválidos.
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_NOT_FOUND404O produto solicitado não foi encontrado.
UAPPI_STORE_SEGMENTATION_NOT_FOUND404A segmentação não foi encontrada.
UAPPI_STORE_PAYMENT_OPTION_NOT_SET400Nenhuma opção de pagamento foi definida no carrinho ou enviada no payload.

Fechamento com Transações Externas

POST /carts/{cartId}/create-order

Finaliza o carrinho e gera o pedido comunicando liquidações financeiras que já ocorreram em gateways ou sistemas externos.

Descrição

Este endpoint é utilizado para a conciliação de pedidos originados de fluxos de pagamento externos à captura direta da Uappi.

Ele permite que o operador informe ao sistema que o pagamento já foi processado (em um link de pagamento externo, em uma maquininha física ou em um ERP), anexando os IDs de transação e os status de liquidação ao novo pedido.

Diferente do POST /buy, este método não tenta realizar nenhuma captura financeira; ele apenas registra o histórico recebido.

É a ferramenta ideal para integrar a Uappi com ecossistemas de pagamentos legados ou processos B2B de faturamento direto, onde a "confirmação do que aconteceu" é o que importa para a geração do pedido.

Detalhamento de Transações

O payload permite o envio de um array de payments[], suportando pedidos com múltiplas formas de pagamento (ex: parte em PIX e parte em Cartão).

Para cada item, é possível detalhar o método (credit-card, pix, billet, etc.) e o status atual da cobrança (waiting_payment ou paid).

Vínculo com a Política Comercial

Mesmo sendo um fechamento com dados externos, cada pagamento informado deve estar associado a uma paymentOptionId válida na política comercial do carrinho.

Isso garante que os relatórios financeiros e a categorização contábil do pedido sigam as regras de negócio da loja.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.
Content-Typeapplication/jsonTipo de conteúdo da requisição.

Parâmetros da URL

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

Parâmetros do Corpo (Obrigatórios)

ParâmetroTipoDescrição
paymentsarrayLista de transações externas a serem vinculadas ao pedido. Máximo de 100 itens.
payments.*.methodstringMétodo de pagamento utilizado. Valores aceitos: credit-card, pix, billet, debit-card, custom.
payments.*.paymentOptionIdintegerID da opção de pagamento correspondente na política comercial do carrinho.
payments.*.paymentOptionLabelstringRótulo/Nome da opção de pagamento (ex: "PIX Externo").
payments.*.valuedecimalValor bruto da transação (aceita até 6 casas decimais).
payments.*.statusstringStatus da liquidação. Valores aceitos: waiting_payment, paid.
payments.*.dataarrayObjeto contendo os dados de identificação da transação externa.
payments.*.data.idstringID ou código de autorização único da transação no provedor externo.

Parâmetros do Corpo (Opcionais e Condicionais)

Detalhes Gerais

ParâmetroTipoDescrição
payments.*.paymentOptionDetailstringDetalhamento adicional sobre a opção de pagamento.
payments.*.integrationNamestringNome da integração ou gateway de origem da transação.
payments.*.datestringData e hora da transação no formato Y-m-d H:i:s.

Cartão (card)

Obrigatório apenas se for necessário registrar detalhes do cartão utilizado fisicamente ou em gateway externo.

ParâmetroTipoDescrição
payments.*.card.binstringOs primeiros 6 dígitos do cartão.
payments.*.card.last4stringOs últimos 4 dígitos do cartão.
payments.*.card.brandstringBandeira do cartão (ex: visa, mastercard, elo, amex, hipercard, etc).
payments.*.card.expirationstringData de expiração do cartão.

Pix (pix)

ParâmetroTipoDescrição
payments.*.pix.dueDatestringData de vencimento do Pix (Y-m-d H:i:s).
payments.*.pix.emvstringCódigo copia e cola (EMV) do Pix.
payments.*.pix.qrCodestringLink ou Base64 da imagem do QR Code.

Boleto (billet)

ParâmetroTipoDescrição
payments.*.billet.barCodestringCódigo de barras do boleto.
payments.*.billet.linkstringURL para visualização do boleto.
payments.*.billet.digitableLinestringLinha digitável do boleto.
payments.*.billet.dueDatestringData de vencimento do boleto (Y-m-d H:i:s).

Parcelamento (installmentData)

Se informado, todos os campos internos tornam-se obrigatórios.

ParâmetroTipoDescrição
payments.*.installmentData.installmentintegerNúmero da parcela.
payments.*.installmentData.installmentValuedecimalValor individual da parcela.
payments.*.installmentData.totalValuedecimalValor total parcelado (incluindo juros, se houver).
payments.*.installmentData.feedecimalValor da taxa de juros aplicada.
payments.*.installmentData.feeTotalValuedecimalValor total apenas das taxas.

Desconto à Vista (cashDiscount)

ParâmetroTipoDescrição
payments.*.cashDiscount.discountPercentagedecimalPercentual de desconto aplicado.
payments.*.cashDiscount.discountValuedecimalValor nominal do desconto concedido.
payments.*.cashDiscount.valueWithDiscountdecimalValor final da transação após a aplicação do desconto.

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/carts/CART123/create-order \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"payments": [
7		{
8			"method": "pix",
9			"paymentOptionId": 12,
10			"paymentOptionLabel": "Pagamento com PIX",
11			"paymentOptionDetail": "Pagamento em ambiente externo",
12			"integrationName": "Pagar.me V3",
13			"value": 300,
14			"status": "waiting-payment",
15			"data": {
16				"id": "weLa9yoUfKViV63"
17			},
18			"pix": {
19				"dueDate": "2026-03-31 09:00:00",
20				"emv": "asdfadsfasdfasdf",
21				"qrCode": "asdfasdcasdfasdfa"
22			},
23			"cashDiscount": {
24				"discountPercentage": 10,
25				"discountValue": 30,
26				"valueWithDiscount": 270
27			}
28		},
29		{
30			"method": "credit-card",
31			"paymentOptionId": 12,
32			"paymentOptionLabel": "Cartão do cliente",
33			"value": 236.34,
34			"status": "paid",
35			"data": {
36				"id": "Gvu8DeDezhehDMG"
37			},
38			"card": {
39				"bin": "400000",
40				"last4": "1000",
41				"brand": "visa",
42				"expiration": "03/2027"
43			},
44			"installmentData": {
45				"installment": 2,
46				"installmentValue": 124.0785,
47				"totalValue": 248.157,
48				"fee": 5,
49				"feeTotalValue": 11.817
50			}
51		}
52	]
53}'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"id": 345,
5		"cartId": "ac66ca1d61577b216979169",
6		"tradePolicyId": 1,
7		"userId": null,
8		"userEmail": null,
9		"userName": null,
10		"code": "345",
11		"salesChannelDomain": "sua-loja.com.br",
12		"marketplaceId": null,
13		"marketplaceName": null,
14		"marketplaceStoreCredentialId": null,
15		"marketplaceOrderGroupId": null,
16		"currency": "BRL",
17		"createdAt": "2026-03-31 14:30:06",
18		"issuedAt": "2026-03-31 11:30:06"
19	}
20}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_INTEGRATION_TRANSACTION_ID_REQUIRED400O ID da transação é obrigatório.
Os demais erros possíveis desse endpoint podem ser encontrados aqui.

Gerar Link de Pagamento (Admin)

POST /carts/{cartId}/generate-payment-code

Gera um código de link de pagamento a partir do carrinho administrativo, criando o pedido sem pagamento.

Este endpoint gera um link de pagamento a partir do carrinho administrativo: o pedido é criado imediatamente (sem cobrança) e um código público e aleatório é retornado, pronto para ser enviado ao cliente final.

Diferente do POST /buy (captura imediata) e do POST /create-order (conciliação de pagamento já processado externamente), este é um terceiro modelo de fechamento: o pedido existe desde já, mas a cobrança só acontece quando o cliente final acessa o link e conclui o pagamento pelo formulário/iframe público.

---

Formas de pagamento permitidas

O operador escolhe, no momento da geração, quais opções de pagamento (paymentOptionId) o cliente poderá utilizar ao acessar o link. Apenas as opções informadas em paymentOptions ficam disponíveis — qualquer outra é rejeitada no momento da finalização.

---

Expiração

O link expira automaticamente após expirationHours horas (padrão: 72h). Após a expiração, tanto a consulta pública quanto a finalização do pagamento passam a ser recusadas.

---

Após a geração

HeaderValorDescrição
AuthorizationBearer {token}Token do usuário autenticado na API privada com escopo CART_WRITE.
Content-Typeapplication/jsonTipo de conteúdo da requisição.

ParâmetroTipoObrigatórioDescrição
cartIdstringSimIdentificador único do carrinho administrativo.

ParâmetroTipoObrigatórioDescrição
paymentOptionsarraySimLista de opções de pagamento permitidas no link. Mínimo de 1 item.
paymentOptions.*.paymentOptionIdintegerSimID da opção de pagamento permitida.
paymentOptions.*.settingsobjectNãoConfigurações adicionais específicas da opção de pagamento nesse link.
expirationHoursintegerNãoQuantidade de horas até a expiração do link (mínimo: 1). Padrão: 72.

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART123/generate-payment-code' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "paymentOptions": [
7      { "paymentOptionId": 1 },
8      { "paymentOptionId": 2 }
9    ],
10    "expirationHours": 48
11  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "orderGroupId": 345,
5    "code": "a1b2c3d4e5f6...",
6    "paymentOptions": [
7      { "paymentOptionId": 1, "settings": [] },
8      { "paymentOptionId": 2, "settings": [] }
9    ],
10    "expiresAt": "2026-08-29 14:30:06",
11    "createdAt": "2026-08-27 14:30:06",
12    "updatedAt": "2026-08-27 14:30:06"
13  }
14}

CampoTipoDescrição
orderGroupIdintegerID do grupo de pedido criado a partir do carrinho.
codestringCódigo público do link de pagamento.
paymentOptionsarrayFormas de pagamento permitidas no link.
expiresAtdateData/hora de expiração do link.
createdAtdateData de criação do registro.
updatedAtdateData da última atualização do registro.

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_CART_NOT_FOUND404O carrinho administrativo informado não foi encontrado.
UAPPI_STORE_CART_USER_MISMATCH403O operador não tem permissão para gerar o link deste carrinho (pertence a outro vendedor).
UAPPI_STORE_CART_ORDER_EXISTS403O carrinho já possui um pedido gerado e não pode ser reutilizado.
UAPPI_STORE_ORDER_INVALID_PAYMENT_OPTION400Uma das opções de pagamento informadas não é válida para a política comercial do carrinho.

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

Institucional

;