Webhooks API 2.0
Você pode utilizar os webhooks para receber notificações de eventos que acontecem no Tiny. Ao se inscrever em um webhook, o Tiny notificará sua aplicação no momento em que um evento ocorrer.
Pré-requisitos
- Ser uma plataforma de e-commerce ou hub de integração
- Ter sua conta homologada pelo Tiny
Fluxo
-
Após criar sua conta no Tiny, envie um e-mail para integracao@tiny.com.br informando que deseja utilizar o serviço de webhooks, enviando o cpf/cnpj de sua conta de testes. Os passos para o processo de desenvolvimento da integração via webhook serão enviados por e-mail.
Ao finalizar o desenvolvimento de sua integração, entre em contato com o e-mail integracao@tiny.com.br para que seja realizado o processo de homologação e disponibilização da estrutura de webhooks aos usuários Tiny que integram com sua plataforma.
Atualizações de estoque
Informa ao integrador qualquer modificação de estoque ocorrida no Tiny para produtos mapeados com a plataforma configurada.
Configurações
Acesse Menu → Configurações → Aba E-commerce → Integrações e selecione sua integração de testes.
Acesse a aba Configurações e informe os valores desejados nos campos da seção Regras de estoque.
Acesse a aba Webhook e informe a URL em que deseja receber as notificações no campo URL de notificações do estoque.
Após a homologação da plataforma, as opções disponíveis para o usuário configurar serão as mesmas da integração de testes. O estoque será enviado ao webhook conforme as configurações selecionadas pelo usuário.
Payload enviado
| Elemento | Tipo | Tamanho | Ocorrência | Descrição | Exemplo |
|---|---|---|---|---|---|
| cnpj | string | - | obrigatório | CNPJ/CPF da conta Tiny que está enviando o payload | 48404755000188 |
| idEcommerce | int | - | obrigatório | Identificador do e-commerce em que o webhook foi configurado | - |
| tipo | string | - | obrigatório | Identificador do tipo do webhook | estoque |
| versao | string | - | obrigatório | Versão do Webhook | 1.0.0 |
| dados | object | - | obrigatório | Elemento utilizado para representar os dados enviados pelo webhook | - |
| dados.tipoEstoque | string | - | obrigatório | Tipo do estoque | "F" = Físico; "D" = Disponível |
| dados.saldo | int | - | obrigatório | Novo saldo em estoque do produto | - |
| dados.idProduto | int | - | obrigatório | Identificador do produto no Tiny | - |
| dados.sku | string | - | obrigatório | SKU do produto no Tiny | - |
| dados.skuMapeamento | string | - | obrigatório | SKU do produto no mapeamento com o e-commerce do campo idEcommerce | - |
| dados.skuMapeamentoPai | string | - | obrigatório | SKU do produto pai no mapeamento com o e-commerce do campo idEcommerce | - |
Confirmação de recebimento
Para confirmar o recebimento da notificação na URL configurada, o webhook deverá retornar o status HTTP 200. Caso o sistema integrado não retorne o status de recebimento, o payload será enviado novamente.
O Tiny enviará o payload ao integrador até, no máximo, 15 vezes, com delay progressivo, aumentando em 5 minutos a cada tentativa.
Envio de produtos
Envia ao integrador os dados do produto cadastrado no Tiny, no momento da ação do seller de enviar produtos para o e-commerce. Cada produto é enviado individualmente.
Configurações
Acesse Menu → Configurações → Aba E-commerce → Integrações e selecione sua integração de testes.
Acesse a aba Configurações e informe os valores desejados nos campos da seção Sincronização de produtos.
Acesse a aba Webhook e informe a URL em que deseja receber as notificações no campo URL para envio de produtos.
Após a homologação da plataforma, as opções disponíveis para o usuário configurar serão as mesmas da integração de testes. Os dados serão enviados ao webhook conforme as configurações selecionadas pelo usuário.
Payload enviado
| Elemento | Tipo | Tamanho | Ocorrência | Descrição | Exemplo |
|---|---|---|---|---|---|
| cnpj | string | - | obrigatório | CNPJ/CPF da conta Tiny que está enviando o payload | 48404755000188 |
| idEcommerce | int | - | obrigatório | Identificador do e-commerce em que o webhook foi configurado | - |
| tipo | string | - | obrigatório | Identificador do tipo do webhook | produto |
| versao | string | - | obrigatório | Versão do Webhook | 1.0.0 |
| dados | object | - | obrigatório | Elemento utilizado para representar os dados enviados pelo webhook | Baixar exemplo de payload de produto |
Confirmação de recebimento
O envio é síncrono, ou seja, o Tiny espera o retorno do integrador no momento do envio.
Para confirmar o recebimento da notificação na URL configurada, o webhook deverá retornar o status HTTP 200 e o payload exibido abaixo. Cada item no array se refere à um item do payload do envio, considerando o produto pai e suas variações.
| Elemento | Tipo | Tamanho | Ocorrência | Descrição | Exemplo |
|---|---|---|---|---|---|
| mapeamentos[] | array | - | obrigatório | Lista que engloba os itens a serem retornados | Baixar exemplo de retorno |
| mapeamentos[].mapeamento | object | - | obrigatório | Elemento utilizado para representar o retorno relacionado a um mapeamento | - |
| mapeamentos[].mapeamento.idMapeamento | int | - | obrigatório | Identificador do produto/variação no Tiny | - |
| mapeamentos[].mapeamento.skuMapeamento | int | - | obrigatório | Identificador do produto na plataforma do integrador, utilizado para criar o mapeamento no Tiny | - |
| mapeamentos[].mapeamento.error | string | - | opcional | Erro retornado pelo integrador a ser exibido para o usuário | - |
Caso o sistema integrado não retorne o status de recebimento, o payload será enviado novamente. São realizadas no máximo 2 tentativas de envio. Qualquer código de retorno fora da faixa HTTP 200 é considerado como erro e o mapeamento para o produto é rejeitado pelo Tiny.
Envio de Código de Rastreio
Envia o código de rastreio cadastrado em um pedido para o e-commerce.
Configurações
Acesse Menu → Configurações → Aba E-commerce → Integrações e selecione sua integração de testes.
Acesse a aba Notificações e informe a URL em que deseja receber as notificações no campo URL para envio do rastreio.
Após a homologação da plataforma, as opções disponíveis para o usuário configurar serão as mesmas da integração de testes. Os dados serão enviados ao webhook conforme as configurações selecionadas pelo usuário.
Payload enviado
| Elemento | Tipo | Tamanho | Ocorrência | Descrição | Exemplo |
|---|---|---|---|---|---|
| cnpj | string | - | obrigatório | CNPJ/CPF da conta Tiny que está enviando o payload | 48404755000188 |
| idEcommerce | int | - | obrigatório | Identificador do e-commerce em que o webhook foi configurado | - |
| tipo | string | - | obrigatório | Identificador do tipo do webhook | rastreio |
| versao | string | - | obrigatório | Versão do Webhook | 1.0.0 |
| dados | object | - | obrigatório | Elemento utilizado para representar os dados enviados pelo webhook | - |
| dados.idEntregaEcommerce | int | - | opcional | Identificador da entrega no e-commerce | - |
| dados.idVendaTiny | int | - | obrigatório | Identificador da venda no Tiny | - |
| dados.idNotaFiscalTiny | int | - | obrigatório | Identificador da nota fiscal no Tiny | - |
| dados.idPedidoEcommerce | string | - | obrigatório | Identificador do pedido no e-commerce | - |
| dados.codigoRastreio | string | - | obrigatório | Código de rastreio do pedido | - |
| dados.urlRastreio | string | - | opcional | URL de rastreio do pedido | https://exemplo.com/rastreio?r=111222333 |
| dados.transportadora | string | - | opcional | Nome da transportadora | Transportadora LTDA |
| dados.formaEnvio | string | - | obrigatório | Descrição da forma de envio | Correios |
| dados.formaFrete | string | - | opcional | Descrição da forma de frete | SEDEX |
Confirmação de recebimento
O envio é síncrono, ou seja, o Tiny espera o retorno do integrador no momento do envio.
Para confirmar o recebimento da notificação na URL configurada, o webhook deverá retornar o status HTTP 200 e o payload exibido abaixo.
| Elemento | Tipo | Tamanho | Ocorrência | Descrição | Exemplo |
|---|---|---|---|---|---|
| idEntregaEcommerce | int | - | opcional | Identificador da entrega no e-commerce | - |
Caso o sistema integrado não retorne o status de recebimento, o payload será enviado novamente. São realizadas no máximo 2 tentativas de envio. Qualquer código de retorno fora da faixa HTTP 200 é considerado como erro e o envio do rastreio é rejeitado pelo Tiny.
Envio de nota fiscal
Envia ao integrador os dados da nota fiscal de um pedido.
Configurações
Acesse Menu → Configurações → Aba E-commerce → Integrações e selecione sua integração de testes.
Acesse a aba Notificações e informe a URL em que deseja receber as notificações no campo URL para envio da nota fiscal.
Após a homologação da plataforma, as opções disponíveis para o usuário configurar serão as mesmas da integração de testes. Os dados serão enviados ao webhook conforme as configurações selecionadas pelo usuário.
Payload enviado
| Elemento | Tipo | Tamanho | Ocorrência | Descrição | Exemplo |
|---|---|---|---|---|---|
| cnpj | string | - | obrigatório | CNPJ/CPF da conta Tiny que está enviando o payload | 48404755000188 |
| idEcommerce | int | - | obrigatório | Identificador do e-commerce em que o webhook foi configurado | - |
| tipo | string | - | obrigatório | Identificador do tipo do webhook | nota_fiscal |
| versao | string | - | obrigatório | Versão do Webhook | 1.0.0 |
| dados | object | - | obrigatório | Elemento utilizado para representar os dados enviados pelo webhook | - |
| dados.chaveAcesso | string | - | obrigatório | Chave de acesso da nota fiscal | - |
| dados.numero | int | - | obrigatório | Número da nota fiscal | - |
| dados.serie | int | - | obrigatório | Série da nota fiscal | - |
| dados.urlDanfe | string | - | obrigatório | URL de acesso do DANFE da nota fiscal | https://erp.tiny.com.br/doc.view?id=11111222223333 |
Confirmação de recebimento
O envio é síncrono, ou seja, o Tiny espera o retorno do integrador no momento do envio.
Para confirmar o recebimento da notificação na URL configurada, o webhook deverá retornar o status HTTP 200.
Caso o sistema integrado não retorne o status de recebimento, o payload será enviado novamente. São realizadas no máximo 2 tentativas de envio. Qualquer código de retorno fora da faixa HTTP 200 é considerado como erro e o envio da nota fiscal é rejeitado pelo Tiny.
Envio de preços de produtos
Envia ao integrador os dados de preços de produtos cadastrados no Tiny. Cada produto é enviado individualmente.
Configurações
Acesse Menu → Configurações → Aba E-commerce → Integrações e selecione sua integração de testes.
Acesse a aba Webhook e informe a URL em que deseja receber as notificações no campo URL para envio dos preços.
Após a homologação da plataforma, as opções disponíveis para o usuário configurar serão as mesmas da integração de testes. Os dados serão enviados ao webhook conforme as configurações selecionadas pelo usuário.
Payload enviado
| Elemento | Tipo | Tamanho | Ocorrência | Descrição | Exemplo |
|---|---|---|---|---|---|
| cnpj | string | - | obrigatório | CNPJ/CPF da conta Tiny que está enviando o payload | 48404755000188 |
| idEcommerce | int | - | obrigatório | Identificador do e-commerce em que o webhook foi configurado | - |
| tipo | string | - | obrigatório | Identificador do tipo do webhook | precos |
| versao | string | - | obrigatório | Versão do Webhook | 1.0.0 |
| dados | object | - | obrigatório | Elemento utilizado para representar os dados enviados pelo webhook | - |
| dados.idMapeamento | int | - | obrigatório | Identificação do mapeamento do produto com o e-commerce | - |
| dados.skuMapeamento | string | - | obrigatório | SKU do produto no mapeamento com o e-commerce do campo idEcommerce | - |
| dados.skuMapeamentoPai | string | - | opcional | SKU do produto pai no mapeamento com o e-commerce do campo idEcommerce | - |
| dados.nome | string | - | obrigatório | Nome do produto | - |
| dados.codigo | string | - | obrigatório | Código do produto | - |
| dados.preco | float | - | obrigatório | Preço do produto | - |
| dados.precoPromocional | float | - | opcional | Preço promocional do produto | - |
Confirmação de recebimento
O envio é síncrono, ou seja, o Tiny espera o retorno do integrador no momento do envio.
Para confirmar o recebimento da notificação na URL configurada, o webhook deverá retornar o status HTTP 200.
Caso o sistema integrado não retorne o status de recebimento, o payload será enviado novamente. São realizadas no máximo 2 tentativas de envio. Qualquer código de retorno fora da faixa HTTP 200 é considerado como erro e o mapeamento para o produto é rejeitado pelo Tiny.
