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

# Webhooks do Tiny ERP

> Configuração e gerenciamento de webhooks nativos do Tiny ERP.

## Endpoint

```
POST https://api.tiny.com.br/api2/webhooks.php
```

## Descrição

Este serviço permite configurar e gerenciar webhooks diretamente pelo Tiny ERP, possibilitando que você receba notificações automáticas de eventos que ocorrem no sistema.

## Parâmetros

| Parâmetro | Tipo   | Ocorrência  | Descrição                                                |
| --------- | ------ | ----------- | -------------------------------------------------------- |
| token     | string | obrigatório | Chave gerada para identificar sua empresa                |
| formato   | string | obrigatório | Formato do retorno (json)                                |
| acao      | string | obrigatório | Ação a ser executada (listar, incluir, alterar, excluir) |
| evento    | string | condicional | Tipo de evento do webhook (1)                            |
| url       | string | condicional | URL que receberá as notificações (1)                     |
| ativo     | string | opcional    | Se o webhook está ativo (S/N)                            |
| id        | int    | condicional | ID do webhook (necessário para alterar/excluir)          |

> (1) Obrigatório para incluir novo webhook

## Eventos Disponíveis

* `atualizacao_estoque` - Quando o estoque de produtos é alterado
* `envio_produtos` - Quando produtos são cadastrados ou alterados
* `envio_codigo_rastreio` - Quando código de rastreamento é adicionado
* `envio_nota_fiscal` - Quando nota fiscal é emitida
* `envio_preco_produtos` - Quando preços são atualizados
* `atualizacao_situacao_pedido` - Quando situação do pedido muda
* `cotacao_fretes` - Para cálculos de frete em tempo real

## Retorno

| Campo                                     | Tipo     | Tamanho | Ocorrência  | Descrição                                 |
| ----------------------------------------- | -------- | ------- | ----------- | ----------------------------------------- |
| retorno                                   | object   | -       | obrigatório | Elemento raiz do retorno                  |
| retorno.status\_processamento             | int      | -       | obrigatório | Conforme tabela "Status de Processamento" |
| retorno.status                            | string   | -       | obrigatório | "OK" ou "Erro"                            |
| retorno.codigo\_erro                      | int      | -       | condicional | Conforme tabela "Códigos de erro"         |
| retorno.erros\[]                          | list     | -       | condicional | Lista dos erros encontrados \[0..n]       |
| retorno.erros\[].erro                     | string   | -       | condicional | Descrição do erro                         |
| retorno.webhooks\[]                       | list     | -       | condicional | Lista de webhooks configurados            |
| retorno.webhooks\[].webhook.id            | int      | -       | condicional | ID do webhook                             |
| retorno.webhooks\[].webhook.evento        | string   | 50      | condicional | Tipo de evento                            |
| retorno.webhooks\[].webhook.url           | string   | 255     | condicional | URL de destino                            |
| retorno.webhooks\[].webhook.ativo         | string   | 1       | condicional | S ou N                                    |
| retorno.webhooks\[].webhook.data\_criacao | datetime | 19      | condicional | Data de criação (dd/mm/yyyy hh:mm:ss)     |

## Exemplo de chamada - Listar webhooks

```bash theme={null}
curl -X POST https://api.tiny.com.br/api2/webhooks.php \
  -d "token=SEU_TOKEN&formato=json&acao=listar"
```

## Exemplo de chamada - Incluir webhook

```bash theme={null}
curl -X POST https://api.tiny.com.br/api2/webhooks.php \
  -d "token=SEU_TOKEN&formato=json&acao=incluir&evento=atualizacao_estoque&url=https://seusite.com.br/webhook&ativo=S"
```

## Exemplos de retorno

### Sucesso - Listar webhooks

```json theme={null}
{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "webhooks": [
      {
        "webhook": {
          "id": 12345,
          "evento": "atualizacao_estoque",
          "url": "https://seusite.com.br/webhook",
          "ativo": "S",
          "data_criacao": "15/05/2024 10:30:00"
        }
      },
      {
        "webhook": {
          "id": 12346,
          "evento": "envio_nota_fiscal",
          "url": "https://seusite.com.br/webhook/nfe",
          "ativo": "S",
          "data_criacao": "16/05/2024 14:20:00"
        }
      }
    ]
  }
}
```

### Sucesso - Incluir webhook

```json theme={null}
{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "registro": {
      "id": 12347
    }
  }
}
```

### Erro - URL inválida

```json theme={null}
{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 6,
    "erros": [
      {
        "erro": "URL inválida"
      }
    ]
  }
}
```

## Observações

* A URL do webhook deve ser acessível publicamente via HTTPS
* O sistema enviará uma requisição POST com dados JSON para a URL configurada
* Seu endpoint deve responder com HTTP 200 para confirmar o recebimento
* Em caso de falha, o sistema tentará reenviar até 3 vezes
* Configure um timeout adequado em seu servidor (recomendado: 30 segundos)