Integração personalizada

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.

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 e influencia os números do dashboard e da tela de Campanhas.

Como funciona

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.

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.

Pronto

O Metrito valida o payload, faz a atribuição via UTMs e o pedido passa a aparecer nas Vendas e nos relatórios.

Formato do payload

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

{
  "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.

Valores são sempre em centavos (inteiros). 9990 significa R$ 99,90 — não envie 99.90.

Status aceitos

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

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.

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.

Primeiros Passos

Conceitos Fundamentais

Dashboard

Análise de Dados

Integrações

Rastreamento

Integração personalizada

O que é a integração personalizada?

Como funciona

Formato do payload

Campos obrigatórios

Status aceitos

Próximos passos

Referência da API — Pedidos

Tela de Vendas

​O que é a integração personalizada?

​Como funciona

​Formato do payload

​Campos obrigatórios

​Status aceitos

​Próximos passos

Referência da API — Pedidos

Tela de Vendas

O que é a integração personalizada?

Como funciona

Formato do payload

Campos obrigatórios

Status aceitos

Próximos passos