# Seu próprio Gateway

> Envie vendas de qualquer sistema para a sua plataforma com o postback Customizado.

O gateway **Customizado** serve para quem vende por um sistema próprio, por um checkout que não está na lista ou por uma automação (Zapier, Make, n8n e similares). Você manda um aviso para a sua plataforma a cada venda, cancelamento ou reembolso, e ela libera ou remove o acesso do aluno.

Ele também serve para quem não vende por gateway e só quer criar entregas para liberar manualmente, no perfil do aluno.

## 1. Crie a entrega na sua plataforma

1. No painel, abra **Vendas › Entregas** e clique em **Nova Entrega**.
2. Na tela **Selecione um Gateway**, escolha **Customizado**.
3. Dê um nome à entrega e escolha a **Modalidade de Venda** (**Venda única** ou **Assinatura**).
4. No campo **ID do Produto**, crie um código livre que identifique o que está sendo vendido, por exemplo `CURSOX3MESES`. É esse código que você vai mandar no campo `produto_id` de cada venda.
5. Em **Conteúdo entregue**, marque os cursos, o tempo de acesso e a liberação de cada um.
6. Clique em **Salvar**.

Depois de salvar, o bloco **Conexão com o gateway** mostra a **URL de Postback** desta entrega e o **Token de postback** da plataforma.

## 2. Para onde enviar

Faça um `POST` para um destes endereços:

| Endereço | Autorização |
|---|---|
| `https://<sua-plataforma>/api/postback/custom/<token>` (a URL de Postback da entrega) | O token já vai na URL. Não precisa do campo `token` no corpo |
| `https://<sua-plataforma>/api/postback/custom` | Mande o campo `token` no corpo, com o **Token de postback** da plataforma |

Use a URL da entrega quando cada produto tem sua própria integração. Use o endereço geral quando um único sistema manda vendas de vários produtos: a plataforma acha a entrega pelo `produto_id`.

O **Token de postback** aparece na própria tela da entrega e também em **Configurações › Integrações › Chaves de API**, aba **API legada**.

:::perigo O token é secreto
Quem tiver o token de postback consegue registrar vendas na sua plataforma. Não coloque o token em páginas públicas nem em formulários. O formulário de cadastro gratuito tem um token próprio, diferente deste.
:::

O corpo pode ir em JSON (`Content-Type: application/json`) ou como formulário (`application/x-www-form-urlencoded`).

## 3. Campos aceitos

| Campo | Descrição | Obrigatório |
|---|---|---|
| `token` | Token de postback da plataforma (dispensado se você usar a URL da entrega) | Sim, no endereço geral |
| `codigo` | ID único da venda | Sim |
| `status` | `aprovado`, `cancelado` ou `disputa` | Sim |
| `produto_id` | O ID cadastrado na entrega | Sim |
| `cliente_email` | E-mail do cliente | Sim |
| `produto_nome` | Nome do produto | |
| `valor` | Valor da venda, ex.: `123.50` | |
| `pagamento` | Forma de pagamento | |
| `cliente_nome` | Nome do cliente | |
| `cliente_doc` | CPF ou CNPJ, com ou sem pontuação | |
| `cliente_celular` | DDD + celular | |
| `cliente_endereco` | Endereço | |
| `cliente_endereco_n` | Número | |
| `cliente_endereco_comp` | Complemento | |
| `cliente_endereco_bairro` | Bairro | |
| `cliente_endereco_cidade` | Cidade | |
| `cliente_endereco_estado` | Estado | |
| `cliente_endereco_cep` | CEP | |
| `recorrencia_id` | ID da assinatura ou contrato | |
| `recorrencia_status` | `ativo`, `cancelado` ou `em-atraso` | |
| `tags` | Tags separadas por `;` (ponto e vírgula) | |
| `comecou_em` | Data de início do acesso, para liberar com data retroativa (ex.: `15/10/2026 08:00`) | |

### Como o status é interpretado

| Envio | Resultado |
|---|---|
| `status: aprovado` | Libera os cursos da entrega |
| `status: aprovado` + `recorrencia_status: em-atraso` | Encerra o acesso (assinatura em atraso) |
| `status: aprovado` + `recorrencia_status: cancelado` | Encerra o acesso (assinatura cancelada) |
| `status: cancelado` | Encerra os acessos da venda. Com `recorrencia_id`, encerra os de todas as cobranças daquela assinatura |
| `status: disputa` | Funciona como pedido de reembolso: encerra os acessos da venda |

A plataforma também reconhece `reembolsado` e `chargeback` no campo `status`. Os dois encerram os acessos da venda.

As tags enviadas em `tags` são criadas se ainda não existirem e dadas ao aluno. Num reembolso ou cancelamento, elas são retiradas, a não ser que o aluno já as tivesse antes.

:::aviso O código da venda precisa ser único
Cada venda precisa de um `codigo` diferente. Um envio com um código que já existe **atualiza** aquela venda em vez de criar outra. É assim que o cancelamento encontra a venda aprovada: mande o cancelamento com o mesmo `codigo` da aprovação.
:::

## 4. Exemplos

Venda aprovada, enviada para o endereço geral:

```json
{
  "token": "SEU_TOKEN_DE_POSTBACK",
  "codigo": "PED-1001",
  "status": "aprovado",
  "produto_id": "CURSOX3MESES",
  "produto_nome": "Curso X - 3 meses",
  "valor": "297.00",
  "cliente_email": "maria@exemplo.com.br",
  "cliente_nome": "Maria Souza",
  "cliente_doc": "123.456.789-09",
  "cliente_celular": "5521999990000",
  "tags": "Turma Outubro;Clientes"
}
```

Cancelamento da mesma venda:

```json
{
  "token": "SEU_TOKEN_DE_POSTBACK",
  "codigo": "PED-1001",
  "status": "cancelado",
  "produto_id": "CURSOX3MESES",
  "cliente_email": "maria@exemplo.com.br"
}
```

Assinatura em atraso:

```json
{
  "token": "SEU_TOKEN_DE_POSTBACK",
  "codigo": "ASS-77-2026-10",
  "status": "aprovado",
  "produto_id": "CLUBE-MENSAL",
  "cliente_email": "joao@exemplo.com.br",
  "recorrencia_id": "ASS-77",
  "recorrencia_status": "em-atraso"
}
```

Envio pela linha de comando, usando a URL da entrega (sem `token` no corpo):

```bash
curl -X POST "https://escola.asalahub.com/api/postback/custom/pb_SEU_TOKEN_DA_ENTREGA" \
  -H "Content-Type: application/json" \
  -d '{"codigo":"PED-1002","status":"aprovado","produto_id":"CURSOX3MESES","cliente_email":"ana@exemplo.com.br","cliente_nome":"Ana Lima"}'
```

## 5. A resposta

Quando o envio é recebido, a plataforma responde com o código **200** e os dados da venda registrada:

```json
{
  "success": true,
  "code": 200,
  "data": { "carga": { "id": 123, "status": "aprovado", "processado": 0, "erro": null } }
}
```

A resposta acima está resumida: a `carga` traz também os dados do cliente e do produto.

O processamento acontece logo em seguida, em segundo plano. Por isso a resposta 200 quer dizer "recebido", não "acesso liberado". Se algo der errado (entrega não encontrada, token inválido, e-mail ausente), a venda aparece em **Vendas › Vendas** com o status **Com erro** e o motivo. Depois de corrigir, clique em **Reprocessar**.

A resposta **409** só aparece quando o corpo não pode ser lido.

:::info Aluno que já existe
A plataforma procura o aluno primeiro pelo CPF/CNPJ (`cliente_doc`) e depois pelo e-mail. A segunda compra de um mesmo CPF entra no perfil já existente, sem mudar nome nem e-mail. Uma venda com o e-mail de um administrador da plataforma não é processada.
:::