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

# Testar e reenviar

> Envie um payload de exemplo, consulte os logs e reenvie quando necessário.

## Testar um webhook

`POST /v2/webhooks/{idEndpoint}/testar`

Cria e envia **um log de teste para cada evento que o webhook assina**, com o código real do evento e um payload de exemplo que tem exatamente os mesmos campos do payload real, preenchidos com **dados fictícios**. Use para validar, antes de ir para produção, se o seu sistema recebe, autentica e interpreta o evento.

* O envio é **síncrono**: acontece dentro da própria requisição, sem passar pela fila. A resposta já traz o resultado de cada envio.
* O envelope tem o campo `teste: true` (eventos reais não têm este campo).
* Headers e token são os mesmos de um envio real (`X-Gestio-Event` traz o código do evento).
* O teste funciona mesmo com o webhook **inativo**, para você validar antes de ativá-lo.
* O log de teste é tentado **uma única vez**, sem novas tentativas automáticas.
* O resultado **não** altera o contador de falhas nem a desativação automática do webhook — nem mesmo quando o teste tem sucesso.
* Cada envio respeita o tempo limite de 10 segundos. Com vários eventos assinados, os envios são feitos em sequência e a resposta traz os logs na ordem dos eventos.

```bash theme={null}
curl -X POST "https://api.gestio.com.br/v2/webhooks/8d1f6c2a-3b4e-4a5f-9e6d-7c8b9a0f1e2d/testar" \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"
```

**Resposta (`200`)** — um log por evento assinado, já com o resultado do envio:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "idEntrega": "5c9e2d4a-1b3f-4e6a-8d7c-0f9e8d7c6b5a",
      "idEndpoint": "8d1f6c2a-3b4e-4a5f-9e6d-7c8b9a0f1e2d",
      "tipoDoEvento": "compras.pedido-de-compra.processado",
      "url": "https://integracao.suaempresa.com.br/webhooks/gestio",
      "situacao": "Entregue",
      "tentativas": 1,
      "ultimoStatusHttp": 200,
      "ultimoErro": null,
      "duracaoUltimaTentativaMs": 412,
      "ultimaTentativaEm": "2026-11-06T14:30:00",
      "proximaTentativaEm": null,
      "criadoEm": "2026-11-06T14:30:00",
      "entregueEm": "2026-11-06T14:30:00",
      "envelope": "{\"id\":\"5c9e2d4a-1b3f-4e6a-8d7c-0f9e8d7c6b5a\",\"tipo\":\"compras.pedido-de-compra.processado\",\"versao\":1,\"ocorridoEm\":\"2026-11-06T14:30:00Z\",\"teste\":true,\"dados\":{...}}"
    }
  ]
}
```

> [!NOTE]
>
> O campo `envelope` é o JSON exato enviado ao seu sistema, em formato texto. Use `JSON.parse` (ou equivalente) para ler o conteúdo.

> [!TIP]
>
> Se o seu sistema recusar o envio de teste (erro, tempo limite ou resposta diferente de `2xx`), a rota continua respondendo `200` com `success: true`: a falha do destino aparece no log, com `situacao: "Falha"`, `ultimoStatusHttp` e `ultimoErro`. A falha do destino não é falha do teste.

**Payload de exemplo de `compras.pedido-de-compra.processado`:**

```json theme={null}
{
  "id": "5c9e2d4a-1b3f-4e6a-8d7c-0f9e8d7c6b5a",
  "tipo": "compras.pedido-de-compra.processado",
  "versao": 1,
  "ocorridoEm": "2026-11-06T14:30:00Z",
  "teste": true,
  "dados": {
    "numeroDoPedido": 999999,
    "sequencia": 1,
    "codigoDaFilial": 1,
    "fornecedor": {
      "codigo": 999999,
      "nome": "Fornecedor de Teste"
    },
    "valorTotal": 1500.0,
    "dataDeEmissao": "2026-11-06T14:30:00Z",
    "situacao": "F",
    "codigoDoUsuario": "usuario.teste",
    "quantidadeDeItens": 2
  }
}
```

### Erros do teste

| Mensagem | Causa |
| - | - |
| Endpoint não encontrado. | `idEndpoint` inexistente ou de outra empresa |
| O webhook não tem eventos assinados. Assine ao menos um evento para testá-lo. | Webhook sem eventos |
| Não há exemplo de payload para o evento '…'. | Evento assinado ainda sem exemplo. Nenhum log é criado, nem para os demais eventos do webhook |

***

## Logs

`GET /v2/webhooks/{idEndpoint}/logs`

Lista os logs de um webhook de forma paginada.

**situacao** `string`

Filtra pela situação: `Pendente`, `Entregue` ou `Falha`.

**de** `string (date-time)`

Data inicial de criação do log.

**ate** `string (date-time)`

Data final de criação do log.

**skip** `integer` (default: 0)

Quantidade de registros a pular.

**take** `integer`

Quantidade de registros da página. Máximo de 500.

**orderBy** `string`

Campo de ordenação: `criadoEm`, `entregueEm`, `tipoDoEvento`, `situacao`, `tentativas`, `ultimoStatusHttp` ou `ultimaTentativaEm`.

**desc** `boolean`

Ordenação decrescente.

**Exemplo:**

```http theme={null}
GET /v2/webhooks/8d1f6c2a-3b4e-4a5f-9e6d-7c8b9a0f1e2d/logs?situacao=Falha&skip=0&take=50&orderBy=criadoEm&desc=true
```

**Resposta (`200`):**

```json theme={null}
{
  "success": true,
  "data": {
    "data": [
      {
        "idEntrega": "3f2b8c1e-6a4d-4f0b-9c2e-1d7a5b8e9f10",
        "idEndpoint": "8d1f6c2a-3b4e-4a5f-9e6d-7c8b9a0f1e2d",
        "tipoDoEvento": "compras.pedido-de-compra.processado",
        "url": "https://integracao.suaempresa.com.br/webhooks/gestio",
        "situacao": "Falha",
        "tentativas": 6,
        "ultimoStatusHttp": 503,
        "ultimoErro": "O destino respondeu HTTP 503.",
        "duracaoUltimaTentativaMs": 412,
        "ultimaTentativaEm": "2026-11-06T23:06:00",
        "proximaTentativaEm": null,
        "criadoEm": "2026-11-06T14:30:00",
        "entregueEm": null
      }
    ],
    "totalPage": 1,
    "totalCount": 1
  }
}
```

### Campos do log

**idEntrega** `string (uuid)`

Identificador da entrega (igual ao `id` do envelope).

**idEndpoint** `string (uuid)`

Webhook do log.

**tipoDoEvento** `string`

Código do evento.

**url** `string`

URL usada neste envio (a do webhook no momento em que o log foi criado).

**situacao** `string`

`Pendente`, `Entregue` ou `Falha`.

**tentativas** `integer`

Quantidade de tentativas já feitas.

**ultimoStatusHttp** `integer | null`

HTTP da última resposta do seu sistema; `null` se não houve resposta (ex.: tempo limite).

**ultimoErro** `string | null`

Erro da última tentativa (até 500 caracteres); `null` após sucesso.

**duracaoUltimaTentativaMs** `integer | null`

Duração da última tentativa, em milissegundos.

**ultimaTentativaEm** `string (date-time) | null`

Data da última tentativa, em UTC.

**proximaTentativaEm** `string (date-time) | null`

Próxima tentativa agendada; `null` quando o log terminou.

**criadoEm** `string (date-time)`

Data de criação do log.

**entregueEm** `string (date-time) | null`

Data em que o seu sistema confirmou o recebimento.

> [!NOTE]
>
> Apenas o resultado da **última** tentativa é guardado; cada nova tentativa sobrescreve o anterior. O corpo da resposta do seu sistema não é gravado.

### Consultar um log

`GET /v2/webhooks/logs/{idLog}` devolve o log com os mesmos campos acima e mais o campo `envelope`, com o JSON exato enviado. Um `idLog` inexistente ou de outra empresa responde `404`.

***

## Reenviar um log

`POST /v2/webhooks/logs/{idLog}/reenviar`

Reenvia um log em qualquer situação (`Pendente`, `Entregue` ou `Falha`), útil depois de corrigir um problema no seu sistema.

* A entrega mantém o **mesmo `idEntrega`** e o **mesmo envelope**, por isso o seu tratamento de duplicidade continua funcionando.
* É enviado para a **URL gravada no log**, mesmo que a URL do webhook tenha sido alterada depois.
* Usa o **token atual** do webhook (se o token foi rotacionado, vai o novo).
* Volta para `Pendente` com `tentativas = 0`, sem o resultado da tentativa anterior, e segue as mesmas [regras de novas tentativas](https://docs.gestio.com.br/pages/webhooks/receber-eventos.md#novas-tentativas).
* O reenvio é **assíncrono**: a resposta confirma o enfileiramento. Consulte `GET /v2/webhooks/logs/{idLog}` para acompanhar o resultado.
* Um log de teste reenviado continua sendo de teste (`teste: true`).

| Mensagem | Causa |
| - | - |
| Entrega de webhook não encontrada. (mensagem literal da API) | `idLog` inexistente ou de outra empresa |
| O webhook da entrega está desativado. (mensagem literal da API) | Webhook inativo: reative-o antes de reenviar |

> [!TIP]
>
> Para reprocessar várias falhas de uma vez, liste com `GET /v2/webhooks/{idEndpoint}/logs?situacao=Falha` e chame o reenvio para cada `idEntrega` — respeitando o limite de requisições por minuto da API.


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