> ## Documentation Index
> Fetch the complete documentation index at: https://docs.utmify.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentación API

> Envía los datos de una venta a Utmify mediante solicitud POST.

## 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

```text theme={null}
POST https://api.utmify.com.br/api-credentials/orders
```

### 1.2 Headers

```json theme={null}
{
  "x-api-token": "string"
}
```

### 1.3 Payload

#### 1.3.1 Body

```json theme={null}
{
  "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](#customer) · [Product](#product) · [TrackingParameters](#tracking-parameters) · [Commission](#commission)

<h4 id="customer">
  1.3.2 Customer
</h4>

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

<h4 id="product">
  1.3.3 Product
</h4>

```json theme={null}
{
  "id": "string",
  "name": "string",
  "planId": "string" | null,
  "planName": "string" | null,
  "quantity": number,
  "priceInCents": number
}
```

<h4 id="tracking-parameters">
  1.3.4 TrackingParameters
</h4>

```json theme={null}
{
  "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
}
```

<h4 id="commission">
  1.3.5 Commission
</h4>

```json theme={null}
{
  "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](#customer)                      | Información del cliente que realizó la compra.                                                                                                                                                                                                                                      |
| products           | Array de [Product](#product)               | Información de los productos presentes en la transacción.                                                                                                                                                                                                                           |
| trackingParameters | [TrackingParameters](#tracking-parameters) | 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](#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     | "[lusampa2020@gmail.com](mailto:lusampa2020@gmail.com)" | 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

```json theme={null}
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": "marcosgonrod@hotmail.com",
    "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

```json theme={null}
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": "marcosgonrod@hotmail.com",
    "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

```json theme={null}
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": "lucaspbarros@gmail.com",
    "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

```json theme={null}
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": "lucaspbarros@gmail.com",
    "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

<AccordionGroup>
  <Accordion title="¿Cómo accedo a Utmify y realizo la integración?">
    Solo crea una cuenta gratuita en: [https://app.utmify.com.br/register](https://app.utmify.com.br/register)
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="¿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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>