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

# Consultando Eventos e Reenviando Entregas

> Percorra todos os eventos que o SpherePay registrou, inspecione tentativas de entrega e respostas, e reenvie uma entrega com falha sob demanda.

Todo evento que o SpherePay cria — e toda tentativa de entregá-lo — é registrado e consultável. Use a API de Eventos para auditar o que aconteceu, diagnosticar entregas com falha e reenviar qualquer entrega ao seu endpoint. Visões do Dashboard para navegar e reenviar eventos chegarão em breve; hoje esses controles estão na API.

## Listar eventos

```bash theme={"dark"}
curl "https://api.spherepay.co/v2/events?type=transfer.*&status=failed&page=1&limit=10" \
  -H "Authorization: Bearer {{api_key}}"
```

| Parâmetro                     | Descrição                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `type`                        | Filtro de tipo de evento — um nome exato (`transfer.succeeded`), um wildcard de recurso (`transfer.*`) ou `*`. |
| `status`                      | Filtra pelo status de entrega: `queued`, `delivering`, `delivered` ou `failed`.                                |
| `webhookEndpointId`           | Apenas eventos com uma entrega para o endpoint informado.                                                      |
| `createdStart` / `createdEnd` | Limites ISO 8601 inclusivos sobre o horário de criação do evento.                                              |
| `page` / `limit`              | Paginação (padrões `1` / `10`, limite máximo `100`).                                                           |

Cada item da lista resume o evento e sua entrega mais recente:

```json theme={"dark"}
{
  "data": [
    {
      "id": "event_01HXPA3M9R7DEF456",
      "type": "transfer.succeeded",
      "createdAt": "2026-08-07T14:05:30.123Z",
      "sequence": 5,
      "delivery": {
        "id": "eventDelivery_2351653173",
        "webhookEndpointId": "whk_01HXP9TN3J2ABC",
        "status": "delivered",
        "attemptsUsed": 1,
        "deliveredAt": "2026-08-07T14:05:31.821Z",
        "latestAttempt": {
          "type": "original",
          "success": true,
          "responseCode": 200
        }
      }
    }
  ],
  "page": 1,
  "limit": 10,
  "total": 1,
  "totalPages": 1,
  "hasNext": false,
  "hasPrevious": false
}
```

<Tip>
  Para encontrar tudo o que precisa de atenção, filtre por `status=failed`. Um `responseCode` de `null` em uma tentativa significa que seu endpoint não respondeu de forma alguma — um timeout ou erro de rede, e não um erro HTTP.
</Tip>

### Status de entrega

| Status       | Significado                                                                                                           |
| ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `queued`     | A entrega está aguardando para ser enviada.                                                                           |
| `delivering` | Uma requisição HTTP ao seu endpoint está em andamento.                                                                |
| `delivered`  | Seu endpoint confirmou com uma resposta `2xx`.                                                                        |
| `failed`     | A tentativa mais recente falhou — resposta não-`2xx`, ou nenhuma resposta em até 15 segundos. Recuperável via replay. |

## Recuperar um evento

`GET /v2/events/{id}` retorna o evento completo mais cada entrega e cada tentativa — incluindo a resposta que seu endpoint retornou:

```bash theme={"dark"}
curl https://api.spherepay.co/v2/events/event_01HXPA3M9R7DEF456 \
  -H "Authorization: Bearer {{api_key}}"
```

Cada tentativa registra `type` (`original` ou `replay`), `attemptedAt`, `success`, `responseCode`, `responseBody` (truncado em 200 caracteres, capturado em falhas para ajudar na depuração) e `latencyMs`.

<Note>
  Se você tem em mãos um cabeçalho `Sphere-Delivery-Id` de uma entrega que recebeu, esse é o ID da entrega — você pode usá-lo para correlacionar uma requisição chegando aos seus servidores com os registros de entrega e tentativa exibidos aqui.
</Note>

## Reenviando uma entrega

O SpherePay faz exatamente uma tentativa automática de entrega por evento por endpoint — **não há retentativas automáticas**. Quando uma entrega falha (seu endpoint estava fora do ar, excedeu o tempo limite ou retornou um erro), você decide quando reenviá-la com `POST /v2/events/replay/{eventDeliveryId}`, usando o ID da entrega (não o ID do evento):

```bash theme={"dark"}
curl -X POST https://api.spherepay.co/v2/events/replay/eventDelivery_2351653173 \
  -H "Authorization: Bearer {{api_key}}"
```

Um replay reenvia o **payload idêntico byte a byte** para o mesmo endpoint, com um `Sphere-Timestamp` e uma `Sphere-Signature` novos e os cabeçalhos `Sphere-Delivery-Type: replay` e `Sphere-Replay-Reason: manual`. Seu caminho de código de verificação é idêntico para originais e replays.

Um replay bem-sucedido transiciona a entrega para `delivered`; um replay com falha a deixa em `failed` e registra mais uma tentativa. De qualquer forma, o histórico completo de tentativas é preservado.

<Warning>
  Replays são entregues pelo menos uma vez (at-least-once) em cima do que seu endpoint já recebeu, e você pode reenviar uma entrega que já teve sucesso. Garanta que seu handler deduplique pelo `id` do evento e aplique a [verificação de obsolescência via `sequence`](/pt-BR/concepts/webhooks/event-payloads) para que os replays sejam sempre seguros.
</Warning>

## Recuperando-se de indisponibilidade

Se o seu endpoint ficou fora do ar por um período:

1. Liste os eventos com `status=failed` e `createdStart`/`createdEnd` cobrindo a janela da indisponibilidade.
2. Reenvie cada entrega com falha via `POST /v2/events/replay/{eventDeliveryId}`.
3. Seu tratamento de `sequence` descartará automaticamente qualquer evento reenviado que já tenha sido superado.

Alternativamente, como os payloads são mínimos, você pode simplesmente buscar novamente o estado atual dos recursos afetados com seus endpoints `GET` e reconciliar diretamente.