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

# Eventos de parceiros

> Endpoint restrito para parceiros de pagamento enviarem eventos de carrinho, pagamento, Pix e boleto que viram mensagem de WhatsApp.

Só para parceiros integrados. Se você é cliente da Arara, você não precisa desta página.

Um parceiro de pagamento habilitado envia um evento de negócio e a Arara manda um template fixo para o cliente final, a partir de um número da própria Arara. Hoje o único parceiro é a AbacatePay.

<Warning>
  A chave de parceiro é emitida pela equipe da Arara. Valide a integração com a Arara antes de ir para produção.
</Warning>

Se você é cliente e quer recuperar carrinho, Pix ou boleto no seu número e com os seus templates, use a [recuperação de receita](/recovery).

## Endpoint

```
POST https://api.ararahq.com/v1/partners/abacate/events
Authorization: Bearer <chave_do_parceiro>
Content-Type: application/json
```

A chave de parceiro não é uma chave de API `ara_live_...`.

## Corpo

```json theme={null}
{
  "event": "pix.created",
  "phone": "+5511999999999",
  "customer": "João Silva",
  "store": "Minha Loja",
  "value": 199.90,
  "code": "00020126580014br.gov.bcb.pix..."
}
```

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `event` | string | sim | Um dos eventos da tabela abaixo. |
| `phone` | string | sim | Telefone do cliente em E.164 (`+5511999999999` ou `5511999999999`). |
| `customer` | string | sim | Nome do cliente. |
| `store` | string | sim | Nome da loja. |
| `value` | number | sim | Valor em reais (`199.90`). |
| `url` | string | não | Link de checkout, nova tentativa ou pagamento. |
| `code` | string | não | Código Pix copia e cola. |

## Eventos e variáveis

Cada evento usa um template fixo com 4 variáveis:

| Variável | Conteúdo |
| - | - |
| `{{1}}` | `customer` |
| `{{2}}` | `store` |
| `{{3}}` | `value` formatado com vírgula e duas casas (`199,90`), sem `R$` |
| `{{4}}` | `url`; sem `url`, usa `code`; sem os dois, vazio |

<Note>
  `url` tem prioridade sobre `code`. Se você enviar os dois, o código Pix é descartado.
</Note>

| `event` | Quando enviar |
| - | - |
| `cart.abandoned` | Carrinho abandonado. |
| `payment.failed` | Pagamento não autorizado. |
| `pix.created` | Pix gerado, aguardando pagamento. |
| `boleto.due` | Boleto vence hoje. |

## Exemplo

```bash theme={null}
curl -X POST https://api.ararahq.com/v1/partners/abacate/events \
  -H "Authorization: Bearer <chave_do_parceiro>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "cart.abandoned",
    "phone": "+5511999999999",
    "customer": "João Silva",
    "store": "Nike Store",
    "value": 299.90,
    "url": "https://checkout.exemplo.com/123"
  }'
```

## Respostas

### Sucesso (`200 OK`)

```json theme={null}
{
  "status": "queued",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

`id` é o UUID interno da mensagem criada.

### Erros

| HTTP | Corpo | Quando |
| - | - | - |
| `400` | `{ "error": "Evento desconhecido" }` | `event` fora da lista. |
| `400` | `{ "error": { "code": "VALIDATION_ERROR", "message": "..." } }` | Campo obrigatório em branco. `message` traz a primeira violação. |
| `400` | `{ "error": { "code": "INVALID_JSON", ... } }` | JSON malformado ou `value` ausente. |
| `401` | sem corpo | Chave de parceiro incorreta. |
| `403` | padrão do Spring, sem `code` | Requisição recusada pelo filtro de autenticação da API. |
| `422` | `{ "error": { "code": "INVALID_RECIPIENT", ... } }` | Telefone fora do E.164. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.