Skip to main content

​
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âmetroTipoOcorrênciaDescrição
tokenstringobrigatórioChave gerada para identificar sua empresa
formatostringobrigatórioFormato do retorno (json)
acaostringobrigatórioAção a ser executada (listar, incluir, alterar, excluir)
eventostringcondicionalTipo de evento do webhook (1)
urlstringcondicionalURL que receberá as notificações (1)
ativostringopcionalSe o webhook está ativo (S/N)
idintcondicionalID 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

CampoTipoTamanhoOcorrênciaDescrição
retornoobject-obrigatórioElemento raiz do retorno
retorno.status_processamentoint-obrigatórioConforme tabela “Status de Processamento”
retorno.statusstring-obrigatório”OK” ou “Erro”
retorno.codigo_erroint-condicionalConforme tabela “Códigos de erro”
retorno.erros[]list-condicionalLista dos erros encontrados [0..n]
retorno.erros[].errostring-condicionalDescrição do erro
retorno.webhooks[]list-condicionalLista de webhooks configurados
retorno.webhooks[].webhook.idint-condicionalID do webhook
retorno.webhooks[].webhook.eventostring50condicionalTipo de evento
retorno.webhooks[].webhook.urlstring255condicionalURL de destino
retorno.webhooks[].webhook.ativostring1condicionalS ou N
retorno.webhooks[].webhook.data_criacaodatetime19condicionalData de criação (dd/mm/yyyy hh:mm:ss)

​
Exemplo de chamada - Listar webhooks

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

​
Exemplo de chamada - Incluir webhook

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

{
  "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

{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "registro": {
      "id": 12347
    }
  }
}

​
Erro - URL inválida

{
  "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)