Documentação das integrações de usuário

As integrações de usuários representam os vínculos que um usuário possui com serviços externos ou automações da plataforma.

É por meio dessas integrações que o usuário pode conectar a conta em:

• Sistemas terceiros;
• Habilitar sincronizações;
• Receber dados externos;
• Acionar funcionalidades automáticas.

Cada integração define como o usuário se comunica com esses serviços, seja por

• Filas de integração;
• Webhooks

Garantindo que as operações externas funcionem de forma segura e vinculada ao usuário correto dentro do painel.

Funcionamento do webhook

Quando a plataforma executa certas operações como: alteração de estoque de produto, status de pedido, documento de cliente, etc. Ela dispara uma requisição HTTP para a URL de webhook cadastrada em cada integração de usuário ativa e do tipo webhook.

Portanto, antes de utilizar o webhook de fato, é necessário cadastrar ao menos uma integração de usuário com esses parâmetros. Para mais detalhes consulte o endpoint de criação/atualização de integrações de usuário

Requisição enviada

A requisição é enviada como POST para a URL cadastrada com os seguintes cabeçalhos:

1Content-Type: application/json
2Accept: application/json

O corpo da requisição é um JSON com o payload do evento. Os dados sensíveis são mascarados antes de serem armazenados no histórico, mas são enviados íntegros ao endpoint do webhook.

Timeout

A plataforma aguarda no máximo 30 segundos para conexão e para a resposta do servidor. Requisições que ultrapassem esse limite são consideradas falhas.

Tentativas e reenvio (retry)

Em caso de falha, a plataforma realiza até 5 tentativas de entrega por evento. O intervalo entre as tentativas segue uma estratégia de backoff exponencial com jitter:

Tentativa	Delay base	Jitter máximo
1ª	imediato	—
2ª	4 segundos	+2 segundos
3ª	8 segundos	+4 segundos
4ª	16 segundos	+8 segundos
5ª	32 segundos	+16 segundos

O jitter é um valor aleatório somado ao delay base para evitar sobrecarga em caso de múltiplos webhooks disparados simultaneamente. O envio é interrompido assim que uma tentativa for bem-sucedida.

Critério de sucesso

Uma tentativa é considerada bem-sucedida quando o servidor responde com qualquer status HTTP de sucesso (2xx) dentro do tempo limite. Qualquer outro status ou erro de conexão é tratado como falha.

Controle de falhas e desativação automática

Cada integração de webhook tem o campo webhookFailures, com a quantidade de falhas de entrega acumuladas. Após cada ciclo de entregas, a plataforma atualiza esse contador:

• Sucesso: o contador é zerado.
• Falha: o contador é incrementado.
• 3 falhas acumuladas: a integração é desativada automaticamente (active: false) e o contador é zerado.
• Salvar a integração novamente: o contador é zerado.

> Uma integração desativada por excesso de falhas precisa ser reativada manualmente, salvando a integração novamente com active: true.

Dados do payload por entidade

O payload enviado varia conforme o tipo de entidade configurado na integração. Abaixo estão os campos incluídos em cada caso.

• Produto (product)

Os dados são obtidos via listagem de produtos da loja.

Campo	Descrição
flags	Flags e marcadores do produto
description	Descrição do produto
parentProduct	Produto pai (em caso de variação)
tax	Informações fiscais
filters	Filtros e categorias associados
stockByStorage	Estoque detalhado por depósito
stock	Estoque consolidado
dimension	Dimensões físicas (peso, altura, largura, etc.)
variation	Dados de variação do produto
price	Preços e tabelas de preço

• Remessa (order)

Os dados são obtidos via listagem de pedidos da loja.

Campo	Descrição
orderGroup	Dados gerais do agrupador de pedidos.
productStorage	Informações do estoque de origem.
status	Detalhes do status atual do pedido.
customer	Dados completos do comprador.
addresses	Endereços de entrega e faturamento.
values	Composição de valores (subtotal, frete, descontos, total).
shipping	Dados logísticos e de rastreio.
items	Lista detalhada de produtos no pedido.
invoice	Dados das notas fiscais emitidas.
discounts	Detalhamento de descontos.
additions	Detalhamento de acréscimos.

• Cliente (customer)

Os dados são obtidos via listagem de clientes da loja.

Exemplo de requisição

Abaixo está um exemplo do corpo enviado ao endpoint de webhook para a entidade customer:

1curl -X POST https://seu-endpoint.com/webhook \
2  -H "Content-Type: application/json" \
3  -H "Accept: application/json" \
4  -d '[
5  {
6    "id": 1042,
7    "salesChannelId": 3,
8    "tradePolicyId": 1,
9    "email": "joao.silva@email.com.br",
10    "dealerGroupId": null,
11    "nameCorporateName": "João da Silva",
12    "tradeName": "",
13    "isCorporate": false,
14    "gender": "male",
15    "nationality": "BRA",
16    "birthdate": "1990-07-15",
17    "phone": "+5592996329384",
18    "walletAmount": 0,
19    "pointSystemAmount": 350,
20    "orderQuantity": null,
21    "cancelledOrderQuantity": null,
22    "orderValue": null,
23    "lastOrder": null,
24    "origin": "frontend",
25    "createdAt": "2023-04-10 09:22:41",
26    "active": true,
27    "deleted": false,
28    "masked": false,
29    "addresses": [
30      {
31        "id": 78,
32        "main": true,
33        "zipCode": "01310100",
34        "identification": "Casa",
35        "street": "Avenida Paulista",
36        "number": "1000",
37        "city": "São Paulo",
38        "complement": "Apto 42",
39        "district": "Bela Vista",
40        "state": "São Paulo",
41        "recipient": "João da Silva",
42        "stateCode": "BR-SP",
43        "countryCode": "BRA",
44        "createdAt": "2023-04-10 09:22:41",
45        "updatedAt": "2024-01-05 14:37:18"
46      }
47    ],
48    "documents": [
49      {
50        "type": "cpf",
51        "document": "12345678900"
52      }
53    ],
54    "flags": {
55      "sendPromotionalEmail": true,
56      "sendPromotionalSms": false,
57      "sendOrderEmail": true,
58      "sendOrderSms": false
59    },
60    "additionalFields": [
61      {
62				"name": "Tem intolerância a lactose?",
63				"code": "tem-intolerancia-a-lactose",
64				"type": "boolean",
65				"value": false
66			}
67    ]
68  }
69]'

Listagem de integrações de usuário

Descrição

Endpoint responsável por retornar uma lista de integrações associadas a um usuário

Parâmetros de Query

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/auth/users/{userId}/integration \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "userId": 123,
6      "type": "customer",
7      "integrationMethod": "webhook",
8      "active": true,
9      "webhookUrl": "https://minhaapi.com.br/webhook",
10      "webhookFailures": 0
11    }
12  ]
13}

O campo webhookFailures informa as falhas de entrega acumuladas da integração. Ao chegar a 3, a integração é desativada automaticamente e o contador é zerado; uma entrega com sucesso ou salvar a integração novamente também zera o contador.

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

Cadastro/Atualização de integrações de usuário

Descrição

Endpoint responsável por cadastrar ou atualizar uma integração vinculada a um usuário.

Um usuário de integração pode receber eventos de duas formas:

• webhook - quando nossa plataforma dispara os eventos para uma URL externa configurada;
• queue - quando nossa plataforma publica eventos em uma fila e o integrador consome e processa esses eventos.

Para saber mais sobre os disparos de webhook, consulte o tópico Funcionamento do webhook

Parâmetros de query

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/auth/users/{userId}/integration \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "type": "order",
6    "integrationMethod": "webhook",
7    "active": false,
8    "webhookUrl":"https://minhaapi.com.br/webhook"
9  }'

✅ Resposta de Sucesso

1[
2  {
3    "userId": 123,
4    "type": "customer",
5    "integrationMethod": "webhook",
6    "active": true,
7    "webhookUrl": "https://minhaapi.com.br/webhook",
8    "webhookFailures": 0
9  }
10]

O campo webhookFailures informa as falhas de entrega acumuladas da integração e é sempre 0 logo após salvar. Para a regra de desativação automática (3 falhas acumuladas), consulte Controle de falhas e desativação automática.

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

Excluir Perfil de Usuário

Descrição

Endpoint responsável por excluir integrações de usuários da loja.

Parâmetros de query

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/auth/users/{userId}/integration/{type} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "userId": 123,
5    "type": "customer",
6    "integrationMethod": "webhook",
7    "active": true,
8    "webhookUrl": "https://minhaapi.com.br/integration"
9  }
10}

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

Listagem da fila de integração de um usuário

Descrição

Endpoint responsável por retornar, para um usuário específico, os itens pendentes de sincronização na fila de integração (produto, cliente ou pedido).

Diferente do endpoint de fila do usuário autenticado (/queue/{products|customers|orders}), este permite que o painel administrativo consulte a fila de qualquer usuário da loja, informando o userId na URL — útil para diagnosticar e acompanhar o consumo da fila de integração de um usuário específico. 📋

Assim como a listagem da fila do usuário autenticado, este endpoint funciona como um proxy para a listagem principal da entidade (produto, cliente ou pedido).

Isso significa que você pode utilizar o parâmetro fields para escolher exatamente quais informações deseja receber. 🔍

Caso o usuário não tenha itens pendentes na fila para o tipo informado, é retornada uma lista vazia, sem gerar erro.

O acesso a este recurso requer o escopo de permissão USER_READ. 🔒

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/auth/users/{userId}/integration/queue/{type} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "price",
7      "stock"
8    ],
9    "limit": 50
10  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "id": 1234,
6      "type": "product",
7      "sku": "SMPH001",
8      "name": "Smartphone XYZ Pro 128GB",
9      "active": true
10    }
11  ]
12}

Quando o usuário não possui itens pendentes na fila para o tipo informado, o retorno é uma lista vazia:

1{
2  "status": true,
3  "data": []
4}

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