---
title: "POST /v1/events"
description: "Enviar lote de telemetria client_reported"
sidebar:
  hidden: true
---

Operação pública/SDK existente, separada da Platform API administrativa. [Guia funcional](/sdk/contratos-publicos/) · [Índice dos 13 endpoints](/sdk/endpoints-publicos/) · [Schemas navegáveis](/contratos-publicos/) · [JSON Schema](/contracts/public-openapi.json). Não envie Authorization administrativo. Tokens/capacidades transitórias dos exemplos são fictícios.


## POST /v1/events

Enviar lote de telemetria client_reported. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://edge.agilink.invalid/functions/v1/api`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `version` | constante | sim |
| `appId` | string | sim |
| `events` | array | sim |

```json
{
  "version": 1,
  "appId": "app_loja",
  "events": [
    {
      "eventId": "80000000-0000-4000-8000-000000000001",
      "openId": "80000000-0000-4000-8000-000000000002",
      "type": "app_open",
      "linkId": "go.example.com~-a~-produto",
      "occurredAt": "2026-10-19T12:00:00Z",
      "platform": "ios",
      "entryMethod": "https"
    }
  ]
}
```

```sh
curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/events' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","events":[{"eventId":"80000000-0000-4000-8000-000000000001","openId":"80000000-0000-4000-8000-000000000002","type":"app_open","linkId":"go.example.com~-a~-produto","occurredAt":"2026-10-19T12:00:00Z","platform":"ios","entryMethod":"https"}]}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "results": [
    {
      "eventId": "80000000-0000-4000-8000-000000000001",
      "status": "accepted"
    }
  ]
}
```

Erros documentados: `400`, `403`, `413`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

## JavaScript / TypeScript

```js
const response = await fetch("https://edge.agilink.invalid/functions/v1/api/v1/events", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"version":1,"appId":"app_loja","events":[{"eventId":"80000000-0000-4000-8000-000000000001","openId":"80000000-0000-4000-8000-000000000002","type":"app_open","linkId":"go.example.com~-a~-produto","occurredAt":"2026-10-19T12:00:00Z","platform":"ios","entryMethod":"https"}]}) });
if (!response.ok) throw new Error('HTTP ' + response.status);
const result = await response.json();
// Confira accepted e o ACK de cada evento. Não registre tokens transitórios.
```

## Python

```python
import json
import requests
payload = json.loads("{\"version\":1,\"appId\":\"app_loja\",\"events\":[{\"eventId\":\"80000000-0000-4000-8000-000000000001\",\"openId\":\"80000000-0000-4000-8000-000000000002\",\"type\":\"app_open\",\"linkId\":\"go.example.com~-a~-produto\",\"occurredAt\":\"2026-10-19T12:00:00Z\",\"platform\":\"ios\",\"entryMethod\":\"https\"}]}")
response = requests.request("POST", "https://edge.agilink.invalid/functions/v1/api/v1/events", json=payload, timeout=30)
response.raise_for_status()
result = response.json()
# Confira accepted/ACK, sem registrar tokens transitórios.
```

## Campos, limites e semântica

Os schemas abaixo descrevem obrigatoriedade, tipos, defaults, enums e limites; referências apontam para components.schemas do contrato baixável. Omitir opcionais usa o comportamento do contrato; null só é aceito onde declarado. A API pública não usa os envelopes, If-Match ou Idempotency-Key administrativos. Eventos e etapas de recuperação usam seus próprios IDs, deduplicação e capacidade transitória. Não repita um resgate como se fosse leitura: consulte o estado e os limites do [ciclo de recuperação](/sdk/contratos-publicos/). A resolução não gera clique administrativo; telemetria é client_reported. Associação nativa publicada exige verificação em aparelho. Sem paginação administrativa; requests não concedem acesso de gerenciamento.

### Request schema

```json
{
  "type": "object",
  "properties": {
    "version": {
      "const": 1
    },
    "appId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
    },
    "events": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "$ref": "#/components/schemas/NativeEvent"
      }
    }
  },
  "required": [
    "version",
    "appId",
    "events"
  ],
  "additionalProperties": false
}
```

### Response schema

```json
{
  "type": "object",
  "properties": {
    "version": {
      "const": 1
    },
    "results": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "object",
        "properties": {
          "eventId": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "enum": [
              "accepted",
              "duplicate",
              "retry",
              "rejected"
            ]
          },
          "reason": {
            "enum": [
              "invalid_event",
              "conflict",
              "unavailable_link",
              "parent_missing",
              "rate_limited"
            ]
          }
        },
        "required": [
          "eventId",
          "status"
        ],
        "additionalProperties": false
      }
    },
    "retryAfterSeconds": {
      "type": "integer",
      "minimum": 1
    }
  },
  "required": [
    "version",
    "results"
  ],
  "additionalProperties": false
}
```

Headers: Content-Type application/json nas respostas JSON. Erros aplicáveis são os listados acima e podem ter corpo vazio; 429 exige respeitar Retry-After quando fornecido, sem tentativas ilimitadas. Não trate HTTP 200/ACK como confirmação de conteúdo exibido, instalação ou detecção certa.