Documentação API - UTMify

Documentação da API para envio de vendas - Utmify

1- Formato da Requisição 2
1.1- Endpoint 2
1.2- Headers 2
1.3- Payload 2
1.3.1- Body 2
1.3.2- Customer 2
1.3.3- Product 3
1.3.4- TrackingParameters 3
1.3.5- Commission 3
2- Descrição dos Parâmetros 4
2.1- Headers 4
2.2- Body 4
2.3- Customer 5
2.4- Product 5
2.5- TrackingParameters 6
2.6- Commission 7
3- Exemplos Práticos de Requisições 7
3.1- Pix Gerado e Pago 7
3.1.1- Pix Gerado 7
3.1.2- Pix Pago 9
3.2- Cartão de Crédito Pago e Reembolsado 10
3.2.1- Cartão Pago 10
3.2.2- Cartão Reembolsado 11
4- Perguntas Frequentes 13

1- Formato da Requisição

Para enviar uma requisição à nossa API, será necessário criar uma credencial de API, que será
utilizada nos headers desta requisição. Para obter uma credencial, basta acessar (ou criar) a sua conta
gratuita na Utmify e seguir o caminho: Integrações > Webhooks > Credenciais de API > Adicionar
Credencial > Criar Credencial.

1.1- Endpoint

Para enviar as informações dos pedidos, devem ser enviadas requisições do tipo POST para o
seguinte endpoint: [Link]

1.2- Headers

Nos headers da requisição deve ser informada a credencial de api gerada no seguinte formato:

{
‘x-api-token’: string
}

1.3- Payload

O body da requisição deve seguir o formato abaixo:

1.3.1- Body

{
orderId: string,
platform: string,
paymentMethod: 'credit_card' | 'boleto' | 'pix' | 'paypal' | 'free_price',
status: 'waiting_payment' | 'paid' | 'refused' | 'refunded' | 'chargedback',
createdAt: 'YYYY-MM-DD HH:MM:SS', // UTC
approvedDate: 'YYYY-MM-DD HH:MM:SS' | null, // UTC
refundedAt: 'YYYY-MM-DD HH:MM:SS' | null, // UTC
customer: Customer,
products: Product[],
trackingParameters: TrackingParameters,
commission: Commission,
isTest?: boolean
}

1.3.2- Customer

{
name: string,
email: string,
phone: string | null,
document: string | null,
country?: string, // ISO 3166-1 alfa-2
ip?: string
}

1.3.3- Product

{
id: string,
name: string,
planId: string | null,
planName: string | null,
quantity: number,
priceInCents: number
}

1.3.4- TrackingParameters

{
src: string | null,
sck: string | null,
utm_source: string | null,
utm_campaign: string | null,
utm_medium: string | null,
utm_content: string | null,
utm_term: string | null
}

1.3.5- Commission
{
totalPriceInCents: number,
gatewayFeeInCents: number,
userCommissionInCents: number,
currency?: 'BRL' | 'USD' | 'EUR' | 'GBP' | 'ARS' | 'CAD'
}

2- Descrição dos Parâmetros

2.1- Headers

Parâmetro Exemplo Descrição

Credencial de API gerada no
Dashboard da Utmify.
x-api-token “KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC” É através desse token que será
identificado o cliente e o dashboard
que receberão o pedido.

2.2- Body

Parâmetro Exemplo Descrição

orderId “FC72D9AK9” Identificação do pedido na plataforma de vendas.

Nome da plataforma que está integrando com a

platform “GlobalPay” Utmify. Recomendado que seja informado no
formato PascalCase.
paymentMethod “credit_card” Meio de pagamento utilizado na transação.

status “paid” Status do pagamento da transação.

Data em que o pedido foi criado (UTC).
createdAt “2024-07-25 15:34:14” Deve ser informada sempre a mesma data
quando o status do pedido for atualizado.
Data em que o pagamento do pedido foi realizado
approvedDate “2024-07-25 15:41:12” (UTC).
Caso o pedido ainda não tenha sido pago, deve
ser informado o valor null.
Data em que o pedido foi reembolsado (UTC).
refundedAt null Caso o pedido não tenha sido reembolsado, deve
ser informado o valor null.

customer Customer Informações do cliente que realizou a compra na

plataforma de vendas.

products Array de Product Informações dos produtos presentes na

transação.
Parâmetros de url.
trackingParameters TrackingParameters Devem ser extraídos da url do checkout no
momento da compra pela plataforma de vendas e
enviados à Utmify através do Webhook.
commission Commission Valores da transação

Define se o envio trata-se de um teste.

Caso true, será realizada a validação das
 informações enviadas normalmente, mas a
isTest false transação não será salva na Utmify.
Para salvar normalmente o pedido, basta não
passar esse campo na requisição ou deixar o seu
valor false.

2.3- Customer

Parâmetro Exemplo Descrição

name “Lucas Sampaio” Nome do comprador.

email “lusampa2020@[Link]” E-mail do comprador.

phone “11991560063” Telefone do comprador.

document “43887057481” CPF ou CNPJ do comprador.

País do comprador no formato ISO 3166-1

country “BR” alfa-2.
Não é um campo obrigatório.
Ip do comprador.
ip “[Link]” Não é um campo obrigatório, porém, é
recomendado o envio para um melhor
rastreamento das vendas.

2.4- Product

Parâmetro Exemplo Descrição

id “FGC1375Z5” Identificação do produto.

name “Calça” Nome do produto.

Id do plano (caso a plataforma

disponibilize opção de múltiplos planos para o
planId “FTS7743C3” mesmo produto).
Caso não possua essa opção, informe como
null.
Nome do plano (caso a plataforma
disponibilize opção de múltiplos planos para o
planName “Promoção de Natal” mesmo produto).
Caso não possua essa opção, informe como
null.

quantity 2 Quantidade comprada do produto.

priceInCents 11990 Preço do produto na plataforma de vendas.

2.5- TrackingParameters

Parâmetro Exemplo Descrição

Valor do src extraído da url do checkout.
 src null Caso o checkout não possua essa variável
no momento do pedido, enviar como null.

Valor do sck extraído da url do checkout.

sck null Caso o checkout não possua essa variável
no momento do pedido, enviar como null.
Valor do utm_source extraído da url do
utm_source “FB” checkout.
Caso o checkout não possua essa variável
no momento do pedido, enviar como null.
Valor do utm_campaign extraído da url do
utm_campaign “Vendas checkout.
2024/07/10|126351623512736523” Caso o checkout não possua essa variável
no momento do pedido, enviar como null.
Valor do utm_medium extraído da url do
utm_medium “ABO|1273612873681723” checkout.
Caso o checkout não possua essa variável
no momento do pedido, enviar como null.
Valor do utm_content extraído da url do
utm_content “VIDEO 01|2412937293769713” checkout.
Caso o checkout não possua essa variável
no momento do pedido, enviar como null.
Valor do utm_term extraído da url do
utm_term “Instagram_Reels” checkout.
Caso o checkout não possua essa variável
no momento do pedido, enviar como null.

2.6- Commission

Parâmetro Exemplo Descrição

totalPriceInCents 14990 Valor total da transação, em centavos.

gatewayFeeInCents 1500 Valor recebido pela plataforma, em centavos.

Valor recebido pelo vendedor, em centavos.
Esse valor não pode ser 0, a não ser que o usuário
userCommissionInCents 13490 realmente não tenha recebido nada pela venda.
Caso a plataforma não queira informar a comissão do
usuário (não recomendado), deve deixar esse valor
igual ao totalPriceInCents.
Moeda da compra.
currency “USD” Caso em reais, não é necessário informar esse
campo.

3- Exemplos Práticos de Requisições

Neste tópico, serão apresentados alguns exemplos práticos realistas de como devem ser enviadas as
informações e atualizações do pedido.

3.1- Pix Gerado e Pago

Um cliente realizou um pedido via pix na loja GlobalPay através do checkout com a url:
[Link]
utm_source=FB&utm_campaign=CAMPANHA_2|413591587909524&utm_medium=CONJUNTO_2|498
046723566488&utm_content=ANUNCIO_2|504346051220592&utm_term=Instagram_Feed.

O produto comprado foi um óleo de motor de R$ 80,00 com R$ 20,00 de frete. A plataforma cobra R$
1,00 por pix pago + 3% do valor do pedido. O pix foi gerado em 26/07/2024 às 11:35:13 (horário de
Brasília) e pago 26/07/2024 às 11:43:37 (horário de Brasília).

A credencial de API do usuário da Utmify que realizou a venda, é:

KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC.

3.1.1- Pix Gerado

POST [Link]
Headers: { “x-api-token”: “KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC” }
Body: {
“orderId”: ”8e40b27e-0118-4699-8587-e892beedb403”,
“platform”: “GlobalPay”,
“paymentMethod”: “pix”,
“status”: “waiting_payment”,
“createdAt”: “2024-07-26 14:35:13”,
“approvedDate”: null,
“refundedAt”: null,
“customer”: {
“name”: “Marcos Goncalves Rodrigues”,
“email”: “marcosgonrod@[Link]”,
“phone”: “19936387209”,
“document”: “29672656599”,
“country”: “BR”
“ip”: “[Link]”
},
“products”: [
{
“id”: “53d5ce96-a548-4c7b-a0bc-da8bfa0f9294”,
“name”: “Óleo de Motor”,
“planId”: null,
“planName”: null,
“quantity”: 1,
“priceInCents”: 8000
}
],
“trackingParameters”: {
“src”: null,
“sck”: null,
“utm_source”: “FB”,
“utm_campaign”: “CAMPANHA_2|413591587909524”,
“utm_medium”: “CONJUNTO_2|498046723566488”,
“utm_content”: “ANUNCIO_2|504346051220592”,
“utm_term”: “Instagram_Feed”
},
“commission”: {
“totalPriceInCents”: 10000,
“gatewayFeeInCents”: 400,
“userCommissionInCents”: 9600
},
“isTest”: false
}

3.1.2- Pix Pago

POST [Link]
Headers: { “x-api-token”: “KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC” }
Body: {
“orderId”: ”8e40b27e-0118-4699-8587-e892beedb403”,
“platform”: “GlobalPay”,
“paymentMethod”: “pix”,
“status”: “paid”,
“createdAt”: “2024-07-26 14:35:13”,
“approvedDate”: “2024-07-26 14:43:37”,
“refundedAt”: null,
“customer”: {
“name”: “Marcos Goncalves Rodrigues”,
“email”: “marcosgonrod@[Link]”,
“phone”: “19936387209”,
“document”: “29672656599”,
“country”: “BR”,
“ip”: “[Link]”
},
“products”: [
{
“id”: “53d5ce96-a548-4c7b-a0bc-da8bfa0f9294”,
“name”: “Óleo de Motor”,
“planId”: null,
“planName”: null,
“quantity”: 1,
“priceInCents”: 8000
}
],
“trackingParameters”: {
“src”: null,
“sck”: null,
“utm_source”: “FB”,
“utm_campaign”: “CAMPANHA_2|413591587909524”,
“utm_medium”: “CONJUNTO_2|498046723566488”,
“utm_content”: “ANUNCIO_2|504346051220592”,
“utm_term”: “Instagram_Feed”
},
“commission”: {
“totalPriceInCents”: 10000,
“gatewayFeeInCents”: 400,
“userCommissionInCents”: 9600
},
“isTest”: false
}

3.2- Cartão de Crédito Pago e Reembolsado

Um cliente realizou um pedido via cartão de crédito na data 15/07/2024 10:30:14 (horário de Brasília) e
insatisfeito, solicitou reembolso no dia 18/07/2024 22:44:39 (horário de Brasília).

O pedido foi realizado na plataforma GlobalPay, em dólares, e continha uma camiseta de $35.00 e uma
calça de $40.00. A plataforma cobra 5% de taxa por pedido.

O pedido foi realizado no checkout cuja url era: [Link]

a92b-6daa68188a?
utm_source=FB&utm_campaign=CAMPANHA_5|761832537749495&utm_medium=CONJUNTO_5|636
393136432792&utm_content=ANUNCIO_5|525916699209785&utm_term=Facebook_Mobile_Feed.
A credencial de API do vendedor era: JHTbglkQnUhz7Tk2oQ4ZyuVYxBsOpC1XNdYD.

3.2.1- Cartão Pago

POST [Link]
Headers: { “x-api-token”: “JHTbglkQnUhz7Tk2oQ4ZyuVYxBsOpC1XNdYD” }
Body: {
“orderId”: ”b101ea20-72c7-473d-bcc4-416fe4d8f3be”,
“platform”: “GlobalPay”,
“paymentMethod”: “credit_card”,
“status”: “paid”,
“createdAt”: “2024-07-15 13:30:14”,
“approvedDate”: “2024-07-15 13:30:14”,
“refundedAt”: null,
“customer”: {
“name”: “Lucas Pereira Barros”,
“email”: “lucaspbarros@[Link]”,
“phone”: “21996972147”,
“document”: “24883871428”,
“country”: “US”
“ip”: “[Link]”
},
“products”: [
{
“id”: “ab341a39-52e1-4dda-92c8-ef336f2bb43c”,
“name”: “T-shirt”,
“planId”: “e7c5e019-3ac8-4ba1-9a11-2fcb4a4a598d”,
“planName”: “Winter T-shirts”,
“quantity”: 1,
“priceInCents”: 3500
},
{
“id”: “8d7eb04c-ee5c-4c51-b0dc-1bf104d3a37e”,
“name”: “Pants”,
“planId”: “49436d63-d345-4303-b4fd-f7da003e1a65”,
“planName”: “Winter Pants”,
“quantity”: 1,
“priceInCents”: 4000
}
],
“trackingParameters”: {
“src”: null,
“sck”: null,
“utm_source”: “FB”,
“utm_campaign”: “CAMPANHA_5|761832537749495”,
“utm_medium”: “CONJUNTO_5|636393136432792”,
“utm_content”: “ANUNCIO_5|525916699209785”,
“utm_term”: “Facebook_Mobile_Feed”
},
“commission”: {
“totalPriceInCents”: 7500,
“gatewayFeeInCents”: 375,
“userCommissionInCents”: 7125,
“currency”: “USD”
},
“isTest”: false
}

3.2.2- Cartão Reembolsado

POST [Link]
Headers: { “x-api-token”: “JHTbglkQnUhz7Tk2oQ4ZyuVYxBsOpC1XNdYD” }
Body: {
“orderId”: ”b101ea20-72c7-473d-bcc4-416fe4d8f3be”,
“platform”: “GlobalPay”,
“paymentMethod”: “credit_card”,
“status”: “refunded”,
“createdAt”: “2024-07-15 13:30:14”,
“approvedDate”: “2024-07-15 13:30:14”,
“refundedAt”: “2024-07-19 01:44:39”,
“customer”: {
“name”: “Lucas Pereira Barros”,
“email”: “lucaspbarros@[Link]”,
“phone”: “21996972147”,
“document”: “24883871428”,
“country”: “US”
“ip”: “[Link]”
},
“products”: [
{
“id”: “ab341a39-52e1-4dda-92c8-ef336f2bb43c”,
“name”: “T-shirt”,
“planId”: “e7c5e019-3ac8-4ba1-9a11-2fcb4a4a598d”,
“planName”: “Winter T-shirts”,
“quantity”: 1,
“priceInCents”: 3500
},
{
“id”: “8d7eb04c-ee5c-4c51-b0dc-1bf104d3a37e”,
“name”: “Pants”,
“planId”: “49436d63-d345-4303-b4fd-f7da003e1a65”,
“planName”: “Winter Pants”,
“quantity”: 1,
“priceInCents”: 4000
}
],
“trackingParameters”: {
“src”: null,
“sck”: null,
“utm_source”: “FB”,
“utm_campaign”: “CAMPANHA_5|761832537749495”,
“utm_medium”: “CONJUNTO_5|636393136432792”,
“utm_content”: “ANUNCIO_5|525916699209785”,
“utm_term”: “Facebook_Mobile_Feed”
},
“commission”: {
“totalPriceInCents”: 7500,
“gatewayFeeInCents”: 375,
“userCommissionInCents”: 7125,
“currency”: “USD”
},
“isTest”: false
}

4- Perguntas Frequentes

Como faço para acessar a Utmify e realizar a integração?

Basta criar uma conta gratuita através do link: [Link]
Como sei se as informações que enviei estão corretas?
A nossa API realiza a validação de todos os dados enviados no payload. Serão retornados na resposta
da requisição os campos inválidos e os formatos aceitos.

Como sei se os pedidos que enviei foram salvos corretamente?

Basta acessar a conta que foi utilizada para se obter a credencial e navegar até a aba “Resumo”. Nela
estarão as informações dos pedidos salvos na plataforma, com opções de filtros por período
específicos etc.

Recebi o seguinte erro: API_CREDENTIAL_NOT_FOUND. O que significa?

O erro em questão, indica que a Credencial de API não foi informada ou foi passada incorretamente
através dos headers da requisição. Consulte o tópico Formato da Requisição para melhor
esclarecimento.