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

# Integração personalizada

> Conecte qualquer sistema ao Metrito enviando pedidos no formato de payload esperado.

## O que é a integração personalizada?

A **integração personalizada** é uma conexão de checkout genérica: em vez de um checkout pronto da lista, você envia os pedidos por conta própria, no **formato de payload que o Metrito espera**.

Com ela, **qualquer fonte** pode gerar pedidos dentro do Metrito — um sistema próprio, um CRM, uma área de membros, um ERP, o que for.

<Note>
  **O que é um pedido no Metrito?** É uma venda aprovada em um checkout. Ao chegar, o pedido pode disparar um evento de rastreamento (e ser enviado ao Meta), entra na tela de [Vendas](/analise/vendas) e influencia os números do [dashboard](/dashboard/overview) e da tela de [Campanhas](/analise/campanhas).
</Note>

## Como funciona

<Steps>
  <Step title="Crie a conexão personalizada">
    Em **Adicionar integração**, escolha a opção de integração **personalizada** (categoria Pagamentos). O Metrito gera uma **URL de webhook única** com a chave da sua conexão.
  </Step>

  <Step title="Envie os pedidos no formato esperado">
    O seu sistema dispara um `POST` em JSON para essa URL a cada mudança de status de pedido, seguindo o schema abaixo.
  </Step>

  <Step title="Pronto">
    O Metrito valida o payload, faz a atribuição via UTMs e o pedido passa a aparecer nas Vendas e nos relatórios.
  </Step>
</Steps>

## Formato do payload

O Metrito **valida o payload e rejeita** o que estiver fora do schema. Estrutura mínima de um pedido aprovado:

```json theme={null}
{
  "transaction": {
    "id": "12345",
    "status": "approved",
    "commission_currency": "BRL",
    "commission_value": 9990,
    "currency": "BRL",
    "value": 9990,
    "created_at": "2026-04-14T15:30:00-03:00",
    "updated_at": "2026-04-14T15:30:00-03:00",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "+5511999999999"
    },
    "products": [
      { "id": "prod_001", "product_name": "Curso de Marketing", "quantity": 1, "value": 9990 }
    ],
    "payment": { "method": "credit_card", "installments": 3 }
  },
  "utm": {
    "source": "facebook",
    "medium": "cpc",
    "campaign": "black-friday-2026"
  }
}
```

### Campos obrigatórios

| Campo                             | Tipo    | Descrição                                                    |
| --------------------------------- | ------- | ------------------------------------------------------------ |
| `transaction.id`                  | string  | ID único do pedido.                                          |
| `transaction.status`              | enum    | Status padronizado (ver abaixo).                             |
| `transaction.commission_currency` | string  | Moeda ISO de 3 letras (ex.: `BRL`).                          |
| `transaction.commission_value`    | integer | Valor da comissão **em centavos** (ex.: `9990` = R\$ 99,90). |
| `transaction.created_at`          | string  | ISO 8601 com fuso.                                           |
| `transaction.updated_at`          | string  | ISO 8601 com fuso.                                           |

<Warning>
  Valores são sempre **em centavos** (inteiros). `9990` significa R\$ 99,90 — não envie `99.90`.
</Warning>

### Status aceitos

`pending`, `approved`, `authorized`, `failed`, `refunded`, `chargeback`, `under_analysis`, `cancelled`.

<Tip>
  **Envie um webhook a cada mudança de status** — não só no `approved`. O Metrito precisa de `refunded`, `chargeback`, etc. para manter a atribuição e os relatórios precisos. A deduplicação é automática: o evento de **Purchase** não é enviado ao Meta mais de uma vez para o mesmo pedido.
</Tip>

<Warning>
  **UTMs são essenciais para a atribuição.** Inclua os parâmetros UTM da sessão original do comprador no payload. Sem eles, o pedido é registrado, mas não consegue ser atribuído a uma campanha na tela de [Campanhas](/analise/campanhas).
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência da API — Pedidos" icon="terminal" href="/tracking/events-api">
    Detalhes do endpoint e dos campos opcionais.
  </Card>

  <Card title="Tela de Vendas" icon="cart-shopping" href="/analise/vendas">
    Acompanhe os pedidos enviados pela sua integração.
  </Card>
</CardGroup>