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

# Documentação API

> Envie os dados de uma venda para a Utmify via requisição POST.

## Antes de começar

Para enviar uma requisição à nossa API, você precisará de uma **credencial de API**. Para obtê-la, acesse sua conta na Utmify e siga o caminho:

> Integrações → Webhooks → Credenciais de API → Adicionar Credencial → Criar Credencial

***

## 1. Formato da Requisição

### 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 0
  "approvedDate": "YYYY-MM-DD HH:MM:SS" | null, // UTC 0 
  "refundedAt": "YYYY-MM-DD HH:MM:SS" | null, // UTC 0
  "customer": Customer,
  "products": Product[],
  "trackingParameters": TrackingParameters,
  "commission": Commission,
  "isTest?": boolean
}
```

> **Objetos:** [Customer](#customer) · [Product](#product) · [TrackingParameters](#tracking-parameters) · [Commission](#commissions)

<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="commissions">
  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. Descrição dos Parâmetros

### 2.1 Headers

| Parâmetro   | Exemplo                                | Descrição                                                                                                                                    |
| ----------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| x-api-token | "KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC" | Credencial de API gerada no Dashboard da Utmify. É 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.                                                                                                                                                                                                                                    |
| platform           | "GlobalPay"           | Nome da plataforma que está integrando com a Utmify. Recomendado em PascalCase.                                                                                                                                                                                                     |
| paymentMethod      | "credit\_card"        | Meio de pagamento utilizado na transação.                                                                                                                                                                                                                                           |
| status             | "paid"                | Status do pagamento da transação.                                                                                                                                                                                                                                                   |
| createdAt          | "2024-07-25 15:34:14" | Data em que o pedido foi criado (UTC 0). Deve ser informada sempre a mesma data quando o status for atualizado. **Atenção:** serão aceitos somente pedidos de até 7 dias anteriores e no máximo 45 dias para reembolsos ou chargebacks. O descumprimento pode resultar em bloqueio. |
| approvedDate       | "2024-07-25 15:41:12" | Data em que o pagamento foi realizado (UTC 0). Caso o pedido ainda não tenha sido pago, deve ser informado **null**.                                                                                                                                                                |
| refundedAt         | null                  | Data em que o pedido foi reembolsado (UTC 0). Caso não tenha sido reembolsado, informar **null**.                                                                                                                                                                                   |
| customer           | Customer              | Informações do cliente que realizou a compra.                                                                                                                                                                                                                                       |
| products           | Array de Product      | Informações dos produtos presentes na transação.                                                                                                                                                                                                                                    |
| trackingParameters | TrackingParameters    | Parâmetros de URL extraídos da URL do checkout no momento da compra e enviados à Utmify via Webhook.                                                                                                                                                                                |
| commission         | Commission            | Valores da transação.                                                                                                                                                                                                                                                               |
| isTest             | false                 | Define se o envio é um teste. Caso **true**, a validação será realizada normalmente, mas a transação não será salva. Para salvar o pedido, não passe esse campo ou deixe como **false**.                                                                                            |

### 2.3 Customer

| Parâmetro | Exemplo                                                 | Descrição                                                                       |
| --------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
| name      | "Lucas Sampaio"                                         | Nome do comprador.                                                              |
| email     | "[lusampa2020@gmail.com](mailto:lusampa2020@gmail.com)" | E-mail do comprador.                                                            |
| phone     | "11991560063"                                           | Telefone do comprador.                                                          |
| document  | "43887057481"                                           | CPF ou CNPJ do comprador.                                                       |
| country   | "BR"                                                    | País do comprador no formato ISO 3166-1 alfa-2. Não é obrigatório.              |
| ip        | "204.97.192.73"                                         | IP do comprador. Não é obrigatório, porém recomendado para melhor rastreamento. |

### 2.4 Product

| Parâmetro    | Exemplo             | Descrição                                                                                                                |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| id           | "FGC1375Z5"         | Identificação do produto.                                                                                                |
| name         | "Calça"             | Nome do produto.                                                                                                         |
| planId       | "FTS7743C3"         | Id do plano (caso a plataforma disponibilize múltiplos planos para o mesmo produto). Caso não possua, informar **null**. |
| planName     | "Promoção de Natal" | Nome do plano. Caso não possua, informar **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                                                                             |
| ------------- | ---------------------------------------- | ------------------------------------------------------------------------------------- |
| src           | null                                     | Valor do src extraído da URL do checkout. Caso não possua, enviar **null**.           |
| sck           | null                                     | Valor do sck extraído da URL do checkout. Caso não possua, enviar **null**.           |
| utm\_source   | "FB"                                     | Valor do utm\_source extraído da URL do checkout. Caso não possua, enviar **null**.   |
| utm\_campaign | "Vendas 2024/07/10\|12635162351273652 3" | Valor do utm\_campaign extraído da URL do checkout. Caso não possua, enviar **null**. |
| utm\_medium   | "ABO\|1273612873681723"                  | Valor do utm\_medium extraído da URL do checkout. Caso não possua, enviar **null**.   |
| utm\_content  | "VIDEO 01\|2412937293769713"             | Valor do utm\_content extraído da URL do checkout. Caso não possua, enviar **null**.  |
| utm\_term     | "Instagram\_Reels"                       | Valor do utm\_term extraído da URL do checkout. Caso não possua, enviar **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.                                                                                                                                                                                                                                          |
| userCommissionInCents | 13490   | Valor recebido pelo vendedor, em centavos. Esse valor não pode ser 0, a não ser que o usuário 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**. |
| currency              | "USD"   | Moeda da compra. Caso em reais, não é necessário informar esse campo.                                                                                                                                                                                                                 |

***

## 3. Exemplos Práticos de Requisições

### 3.1 PIX Gerado e Pago

Um cliente realizou um pedido via PIX na loja GlobalPay através do checkout com a URL: `https://checkout.globalpay.com/11c4ca3b-4afa-487f-b92b-aeb2c9e86d3d?utm_source=FB&utm_campaign=CAMPANHA_2|413591587909524&utm_medium=CONJUNTO_2|498046723566488&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 e pago em 26/07/2024 às 11:43:37 (horário de Brasília).

#### 3.1.1 PIX Gerado

```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": "Ó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

```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": "Ó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 em 15/07/2024 10:30:14 e solicitou reembolso em 18/07/2024 22:44:39 (horário de Brasília). O pedido foi realizado na plataforma GlobalPay, em dólares, com uma camiseta de R\$ 35,00 e uma calça de R\$ 40,00. A plataforma cobra 5% de taxa por pedido.

#### 3.2.1 Cartão Pago

```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": "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

```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": "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

<AccordionGroup>
  <Accordion title="Como faço para acessar a Utmify e realizar a integração?">
    Basta criar uma conta gratuita através do link: [https://app.utmify.com.br/register](https://app.utmify.com.br/register)
  </Accordion>

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

  <Accordion title="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íodos específicos.
  </Accordion>

  <Accordion title="Recebi o erro API_CREDENTIAL_NOT_FOUND. O que significa?">
    Indica que a Credencial de API não foi informada ou foi passada incorretamente através dos headers da requisição. Consulte a seção **Formato da Requisição** para mais detalhes.
  </Accordion>
</AccordionGroup>