Skip to content

Documentação de Opções de Pagamento e ERP

No contexto de ERP, o mapeamento de pagamento é responsável por relacionar as formas de pagamento cadastradas na loja com as equivalentes existentes no sistema de gestão 💳

Esse vínculo garante que, ao exportar um pedido, o ERP reconheça corretamente a condição de pagamento utilizada, evitando inconsistências financeiras.

O mapeamento atua como uma camada de correspondência entre identificadores, assegurando que códigos internos da plataforma sejam traduzidos para os códigos esperados pelo ERP.

Sem esse alinhamento, pedidos podem ser rejeitados ou registrados com informações incorretas, impactando conciliação e faturamento 🔄

Listagem de opções de pagamento disponíveis

GET /erps/maps/{erpStoreCredentialId}/payment-options/options

Permite ver as opções de pagamento disponíveis no ERP

Descrição

Endpoint responsável por listar as opções de pagamento disponíveis 💳

A busca é condicionada às credenciais informadas, garantindo que apenas as opções válidas para aquele contexto sejam retornadas.

A consulta é realizada diretamente no ERP, assegurando que os dados estejam sempre atualizados e alinhados com o sistema de gestão.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
erpStoreCredentialIdintegerSimIdentificador das credenciais necessárias para acessar o ERP

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/erps/maps/{erpStoreCredentialId}/payment-options/options \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": {
4		"externalId": {
5			"code": "externalId",
6			"title": "Forma de pagamento",
7			"type": "enum",
8			"default": "",
9			"enum": {
10        "987654321": "Dinheiro",
11        "987654322": "Cartão de crédito",
12        "987654323": "Cartão de débito",
13        "987654324": "Boleto bancário",
14        "987654325": "Cheque",
15        "987654326": "Depósito em conta",
16        "987654327": "Crediário da loja",
17        "987654328": "Vale-troca",
18        "987654329": "Pix",
19        "987654330": "Transferência bancária (TED/DOC)",
20        "987654331": "Pagamento padrão",
21        "987654332": "Cartão de crédito - 1x sem juros",
22        "987654333": "Cartão de crédito - 2x sem juros",
23        "987654334": "Cartão de crédito - 3x sem juros",
24        "987654335": "Múltiplos pagamentos",
25        "987654336": "Carteira digital"
26			},
27			"mapKey": "",
28			"mapValue": ""
29		}
30	}
31}

⚠️ 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.

Código InternoCódigo HttpDescrição
UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND404A credencial de ERP solicitada não foi encontrada.
UAPPI_EXTERNAL_ERROR_NOT_MAPPED403A aplicação encontrou um erro de "não mapeado" no microsserviço external.uappi.

Listagem de mapeamento de opções de pagamneto

GET /erps/maps/payment-options

Retorna lista mapeada de opções de pagamento com ERP

Descrição

Endpoint responsável por retornar a lista mapeada de opções de pagamento com o ERP 💳

A resposta contempla opções previamente mapeadas, garantindo alinhamento entre a aplicação e o sistema de gestão.

Ideal para cenários onde é necessário consumir dados já integrados e padronizados, evitando inconsistências na exibição ou no processamento dos pagamentos.

Este é um endpoint amplo e lista mapeamento de opções com qualquer ERP associado.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Campos de Condição Disponíveis

CampoTipoDescrição
erpStoreCredentialIdintegerIdentificador da credencial do ERP
paymentOptionIdintegerIdentificador da opção de pagamento mapeada
createdAtstringData de cadastro do mapeamento

Campos de Ordenação Disponíveis

CampoDescrição
createdAtData de cadastro do mapeamento

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/erps/maps/payment-options \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "erpStoreCredentialId": 1,
5      "externalId": "987654321",
6      "createdAt": "2025-11-19 14:15:10",
7      "paymentOptionId": 1,
8      "installment": 1
9    },
10    {
11      "erpStoreCredentialId": 1,
12      "externalId": "987654321",
13      "createdAt": "2025-11-19 14:15:10",
14      "paymentOptionId": 1,
15      "installment": 2
16    },
17    {
18      "erpStoreCredentialId": 1,
19      "externalId": "987654321",
20      "createdAt": "2025-11-19 14:15:10",
21      "paymentOptionId": 1,
22      "installment": 3
23    }
24  ],
25  "pagination": {
26    "limit": 10,
27    "offset": 0,
28    "pages": 1,
29    "registers": 3
30  }
31}

Atualização do mapeamento de opções de pagamento com ERP

PUT /erps/maps/{erpStoreCredentialId}/payment-options

Possibilita atualizar mapeamentos das opções de pagamento com ERP

Descrição

Endpoint responsável por atualizar o mapeamento das opções de pagamento com o ERP 🔄

Permite corrigir falhas em mapeamentos existentes ou gerar novos mapeamentos, garantindo que as formas de pagamento estejam corretamente vinculadas entre a aplicação e o sistema de gestão.

Para cada item do mapeamento também é possível específicar o número da parcela, isso aumenta a flexibilidade do mapeamento em cenários onde a loja e o ERP usam pagamentos com parcelamento.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {userToken}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
erpStoreCredentialIdintegerSimIdentificador da credencial do ERP

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
mapsarray✅Lista de itens que devem ser mapeados
maps.*.paymentOptionIdinteger✅Identificador da opção de pagamento a ser mapeada
maps.*.installmentinteger❌Número de parcelas da opção
maps.*.externalIdstring✅Identificador da opção de pagamento no ERP
maps.*.actionstring✅Ação que deve ser feita no mapeamento (add/remove)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/erps/maps/{erpStoreCredentialId}/payment-options \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "maps": [
6      {
7        "paymentOptionId": 1,
8        "installment": 1,
9        "externalId": "987654321",
10        "action": "add"
11      },
12    ]
13  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3	"data": [
4		{
5			"externalId": "987654321",
6			"erpStoreCredentialId": 1,
7			"action": "add",
8			"paymentOptionId": 1,
9			"installment": 1
10		}
11	]
12}

⚠️ 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.

Código InternoCódigo HttpDescrição
UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND404A credencial de ERP solicitada não foi encontrada.
UAPPI_INTEGRATION_PAYMENT_OPTION_NOT_FOUND404As opções de pagamento solicitadas (1, 2, 3) não foram encontradas.

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

Institucional

;