Documentación API

Antes de comenzar

Para enviar una solicitud a nuestra API, necesitarás una credencial de API. Para obtenerla, accede a tu cuenta de Utmify y sigue el camino:

Integraciones → Webhooks → Credenciales de API → Agregar Credencial → Crear Credencial

1. Formato de la Solicitud

1.1 Endpoint

POST https://api.utmify.com.br/api-credentials/orders

1.2 Headers

{
  "x-api-token": "string"
}

1.3 Payload

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
}

Objetos: Customer · Product · TrackingParameters · Commission

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" | "COP" | "MXN" | "PYG" | "CLP" | "PEN" | "PLN"
}

2. Descripción de los Parámetros

2.1 Headers

Parámetro	Ejemplo	Descripción
x-api-token	”KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC”	Credencial de API generada en el Dashboard de Utmify. Este token se utiliza para identificar al cliente y el dashboard que recibirá el pedido.

2.2 Body

Parámetro	Ejemplo	Descripción
orderId	”FC72D9AK9”	Identificación del pedido en la plataforma de ventas.
platform	”GlobalPay”	Nombre de la plataforma que se integra con Utmify. Se recomienda en PascalCase.
paymentMethod	”credit_card”	Método de pago utilizado en la transacción.
status	”paid”	Estado del pago de la transacción.
createdAt	”2024-07-25 15:34:14”	Fecha en que se creó el pedido (UTC). Debe ser siempre la misma fecha cuando se actualice el estado del pedido. Atención: solo se aceptan pedidos de hasta 7 días anteriores y un máximo de 45 días para reembolsos o chargebacks. El incumplimiento puede resultar en bloqueo.
approvedDate	”2024-07-25 15:41:12”	Fecha en que se realizó el pago (UTC). Si el pedido aún no ha sido pagado, enviar null.
refundedAt	null	Fecha en que se reembolsó el pedido (UTC). Si no fue reembolsado, enviar null.
customer	Customer	Información del cliente que realizó la compra.
products	Array de Product	Información de los productos presentes en la transacción.
trackingParameters	TrackingParameters	Parámetros de URL extraídos de la URL del checkout al momento de la compra y enviados a Utmify vía Webhook.
commission	Commission	Valores de la transacción.
isTest	false	Define si el envío es una prueba. Si es true, la validación se realizará normalmente, pero la transacción no se guardará. Para guardar el pedido, no envíes este campo o déjalo como false.

2.3 Customer

Parámetro	Ejemplo	Descripción
name	”Lucas Sampaio”	Nombre del comprador.
email	”[email protected]”	Correo electrónico del comprador.
phone	”11991560063”	Teléfono del comprador.
document	”43887057481”	CPF o CNPJ del comprador.
country	”BR”	País del comprador en formato ISO 3166-1 alfa-2. No es obligatorio.
ip	”204.97.192.73”	IP del comprador. No es obligatorio, pero se recomienda para un mejor rastreo de ventas.

2.4 Product

Parámetro	Ejemplo	Descripción
id	”FGC1375Z5”	Identificación del producto.
name	”Pantalón”	Nombre del producto.
planId	”FTS7743C3”	ID del plan (si la plataforma ofrece múltiples planes para el mismo producto). Si no aplica, enviar null.
planName	”Promoción de Navidad”	Nombre del plan. Si no aplica, enviar null.
quantity	2	Cantidad comprada del producto.
priceInCents	11990	Precio del producto en la plataforma de ventas.

2.5 TrackingParameters

Parámetro	Ejemplo	Descripción
src	null	Valor de src extraído de la URL del checkout. Si no aplica, enviar null.
sck	null	Valor de sck extraído de la URL del checkout. Si no aplica, enviar null.
utm_source	”FB”	Valor de utm_source extraído de la URL del checkout. Si no aplica, enviar null.
utm_campaign	”Ventas 2024/07/10”	Valor de utm_campaign extraído de la URL del checkout. Si no aplica, enviar null.
utm_medium	”ABO”	Valor de utm_medium extraído de la URL del checkout. Si no aplica, enviar null.
utm_content	”VIDEO 01”	Valor de utm_content extraído de la URL del checkout. Si no aplica, enviar null.
utm_term	”Instagram_Reels”	Valor de utm_term extraído de la URL del checkout. Si no aplica, enviar null.

2.6 Commission

Parámetro	Ejemplo	Descripción
totalPriceInCents	14990	Valor total de la transacción en centavos.
gatewayFeeInCents	1500	Monto recibido por la plataforma en centavos.
userCommissionInCents	13490	Monto recibido por el vendedor en centavos. Este valor no puede ser 0, a menos que el usuario realmente no haya recibido nada por la venta. Si la plataforma no desea informar la comisión del usuario (no recomendado), debe dejar este valor igual al totalPriceInCents.
currency	”USD”	Moneda de la compra. Si es en BRL, no es necesario informar este campo.

3. Ejemplos Prácticos de Solicitudes

3.1 PIX Generado y Pagado

Un cliente realizó un pedido vía PIX en la tienda GlobalPay. El producto comprado fue un aceite de motor por $80.00 con $20.00 de envío. La plataforma cobra $1.00 por PIX pagado + 3% del valor del pedido. El PIX fue generado el 26/07/2024 a las 11:35:13 y pagado el 26/07/2024 a las 11:43:37 (horario de Brasilia).

3.1.1 PIX Generado

POST https://api.utmify.com.br/api-credentials/orders
Headers: { "x-api-token": "KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC" }

{
  "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": "[email protected]",
    "phone": "19936387209",
    "document": "29672656599",
    "country": "BR",
    "ip": "61.145.134.105"
  },
  "products": [
    {
      "id": "53d5ce96-a548-4c7b-a0bc-da8bfa0f9294",
      "name": "Aceite 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 Pagado

POST https://api.utmify.com.br/api-credentials/orders
Headers: { "x-api-token": "KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC" }

{
  "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": "[email protected]",
    "phone": "19936387209",
    "document": "29672656599",
    "country": "BR",
    "ip": "61.145.134.105"
  },
  "products": [
    {
      "id": "53d5ce96-a548-4c7b-a0bc-da8bfa0f9294",
      "name": "Aceite 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 Tarjeta de Crédito Pagada y Reembolsada

Un cliente realizó un pedido con tarjeta de crédito el 15/07/2024 a las 10:30:14 y solicitó un reembolso el 18/07/2024 a las 22:44:39 (horario de Brasilia). El pedido fue realizado en la plataforma GlobalPay en dólares, con una camiseta de $35.00 y un pantalón de $40.00. La plataforma cobra un 5% de tarifa por pedido.

3.2.1 Tarjeta Pagada

POST https://api.utmify.com.br/api-credentials/orders
Headers: { "x-api-token": "JHTbglkQnUhz7Tk2oQ4ZyuVYxBsOpC1XNdYD" }

{
  "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": "[email protected]",
    "phone": "21996972147",
    "document": "24883871428",
    "country": "US",
    "ip": "242.53.157.167"
  },
  "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": "Pantalón",
      "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 Tarjeta Reembolsada

POST https://api.utmify.com.br/api-credentials/orders
Headers: { "x-api-token": "JHTbglkQnUhz7Tk2oQ4ZyuVYxBsOpC1XNdYD" }

{
  "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": "[email protected]",
    "phone": "21996972147",
    "document": "24883871428",
    "country": "US",
    "ip": "242.53.157.167"
  },
  "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": "Pantalón",
      "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. Preguntas Frecuentes

¿Cómo accedo a Utmify y realizo la integración?

Solo crea una cuenta gratuita en: https://app.utmify.com.br/register

¿Cómo sé si la información que envié es correcta?

Nuestra API valida todos los datos enviados en el payload. Los campos inválidos y los formatos aceptados serán retornados en la respuesta de la solicitud.

¿Cómo sé si los pedidos que envié fueron guardados correctamente?

Accede a la cuenta utilizada para obtener la credencial y navega hasta la pestaña “Resumen”. Allí encontrarás la información de los pedidos guardados en la plataforma, con opciones de filtro por períodos específicos.

Recibí el error API_CREDENTIAL_NOT_FOUND. ¿Qué significa?

Este error indica que la Credencial de API no fue informada o fue enviada incorrectamente a través de los headers de la solicitud. Consulta la sección Formato de la Solicitud para más detalles.

Documentation Index

​Antes de comenzar

​1. Formato de la Solicitud

​1.1 Endpoint

​1.2 Headers

​1.3 Payload

​1.3.1 Body

​1.3.2 Customer

​1.3.3 Product

​1.3.4 TrackingParameters

​1.3.5 Commission

​2. Descripción de los Parámetros

​2.1 Headers

​2.2 Body

​2.3 Customer

​2.4 Product

​2.5 TrackingParameters

​2.6 Commission

​3. Ejemplos Prácticos de Solicitudes

​3.1 PIX Generado y Pagado

​3.1.1 PIX Generado

​3.1.2 PIX Pagado

​3.2 Tarjeta de Crédito Pagada y Reembolsada

​3.2.1 Tarjeta Pagada

​3.2.2 Tarjeta Reembolsada

​4. Preguntas Frecuentes