Manual de Integração — Webhooks (API do Concentrador)

Guia para sistemas que querem ser notificados por webhook quando eventos ocorrem no SuperConcentrador — tanto de cadastros quanto de movimentações, caixas, sangrias e suprimentos.

Base dos endpoints: /api/v1/integracoes/webhooks. Todas as chamadas exigem autenticação (JWT ou api-key de PDV), como o restante da API do Concentrador.

Atualmente estão disponíveis vinte e oito eventos para cadastrar uma URL e ser notificado quando o evento for acionado.

1. Funcionamento geral e cadastro de URL

São três endpoints responsáveis pelo gerenciamento dos Webhooks.

GET — `/api/v1/integracoes/webhooks/cadastros`

Recupera as informações dos cadastros de URL configuradas para os Webhooks. Caso nenhuma URL exista, o endpoint ainda retorna todos os tipos disponíveis, porém o campo urlNotificacao estará com o valor null.

PUT — `/api/v1/integracoes/webhooks/cadastros`

Atualiza as URLs para os tipos de evento. No corpo da requisição é necessário somente a relação de tipo e urlNotificacao, para os que se deseja alterar — mesmo que seja para remover a URL (enviando urlNotificacao: null). Os tipos não enviados são ignorados (permanecem como estão). Apenas tipos que já existem na base são atualizados.

[
  { "tipo": "produto.criado",      "urlNotificacao": "https://meuerp.com/hooks/concentrador" },
  { "tipo": "movimento.finalizado", "urlNotificacao": "https://meuerp.com/hooks/vendas" },
  { "tipo": "produto.atualizado",  "urlNotificacao": null }
]

⚠️ Atenção ao nome do campo: é urlNotificacao (não url). Enviar url no corpo não cadastra a URL.

Os cadastros das URLs podem ser feitos via interface WEB do Concentrador também: basta realizar o Login e, no menu, abrir o grupo Integrações e depois clicar em Webhooks.

2. Tipos de evento disponíveis

caixa.criado

Evento acionado na primeira vez que o caixa for criado no SuperConcentrador, que acontece no momento em que a primeira venda do caixa é sincronizada.

caixa.fechado

Acionado no momento em que o caixa é sincronizado após seu encerramento; a única informação diferente no registro quando consultado será o campo dataFechamento, que estará preenchido.

desconto.criado

Faz parte do padrão dos demais cadastros: acionado quando o registro for criado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

desconto.atualizado

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

filial.criada

Faz parte do padrão dos demais cadastros. Em particular, esse evento será acionado somente uma vez no caso da Filial, pois o Concentrador, assim que possuir uma filial cadastrada, as demais operações na mesma deverão ser somente de atualização.

filial.atualizada

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

filialcertificado.atualizado

Acionado particularmente quando um certificado for atualizado pela interface WEB do Concentrador; a diferença no registro da Filial poderá estar em 2 campos: certificadoDigital e senhaCertificado.

finalizadora.criada

Faz parte do padrão dos demais cadastros: acionado quando o registro for criado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

finalizadora.atualizada

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

grupousuario.criado

Faz parte do padrão dos demais cadastros: acionado quando o registro for criado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

grupousuario.atualizado

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

movimento.criado

Acionado no momento de sincronização de um movimento pelo PDV, na primeira vez em que ele chega ao Concentrador. Nesse momento ele já terá um dos estados de finalização possíveis: FINALIZADO, ERRO_SEFAZ, OFFLINE, CANCELADO ou EXCLUIDO.
No caso do EXCLUIDO, são casos em que a venda não foi efetivada — somente iniciada, mas cancelada antes de sua finalização.
Este evento dispara para todo movimento sincronizado, independente do estado. Para ser notificado somente das vendas efetivadas, use o movimento.finalizado.

movimento.cancelado

Acionado para movimentos com estado CANCELADO: tanto os que já chegam cancelados na sincronização, quanto os que já haviam sido sincronizados como FINALIZADO e, após isso, foram CANCELADOS.
As diferenças de informação quando consultado serão os campos idUsuarioExclusao e dataExclusao preenchidos, o estado CANCELADO e, na parte dos XMLs, a existência do XML de tipoMovimento CANCELAMENTO.

movimento.reenviado

Restrito a casos em que um movimento fora sincronizado com os estados OFFLINE ou ERRO_SEFAZ e, após os devidos procedimentos, é reenviado à SEFAZ e autorizado — passando ao estado FINALIZADO.
As diferenças de informação podem ser inúmeras (dependem, por exemplo, da rejeição que houve e das alterações necessárias para a autorização); recomenda-se substituir as informações por completo.

movimento.finalizado

Acionado quando uma venda é sincronizada pela primeira vez já no estado FINALIZADO. É o evento indicado para receber notificações apenas de vendas efetivadas.
Observação: um movimento que chega FINALIZADO na primeira sincronização aciona tanto o movimento.criado quanto o movimento.finalizado. Assine apenas o movimento.finalizado se quiser somente as vendas efetivadas.

pessoa.criada

Faz parte do padrão dos demais cadastros: acionado quando o registro for criado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

pessoa.atualizada

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

pessoa.excluida

Acionado quando um cadastro de Pessoa for excluído utilizando o endpoint específico para tal; nesse caso as informações diferentes serão o preenchimento dos campos dataExclusao e idUsuarioExclusao.

pontodevenda.criado

Faz parte do padrão dos demais cadastros: acionado quando o registro for criado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

pontodevenda.atualizado

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

produto.criado

Faz parte do padrão dos demais cadastros: acionado quando o registro for criado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

produto.atualizado

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.
Atualizações de Preços, Composições e Códigos Vinculados também acionam este mesmo evento, já que são dados totalmente atrelados ao Produto.

produto.excluido

Acionado quando um cadastro de Produto for excluído utilizando o endpoint específico para tal; nesse caso as informações diferentes serão o preenchimento dos campos dataExclusao e idUsuarioExclusao.

promocao.criada

Faz parte do padrão dos demais cadastros: acionado quando o registro for criado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

promocao.atualizada

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

sangriasuprimento.criada

Acionado no momento de sincronização, pelo PDV, de uma Sangria ou de um Suprimento.

usuario.criado

Faz parte do padrão dos demais cadastros: acionado quando o registro for criado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

usuario.atualizado

Faz parte do padrão das demais atualizações: acionado quando o registro for atualizado pela API, seja via integração com o ERP, ou via interface WEB do Concentrador.

3. Funcionamento das notificações

Exemplo do corpo enviado para a URL

{
    "id": "10a0263c-6605-44bc-8a96-4a1a4164d5e5",
    "tipo": "produto.atualizado",
    "payload": {
        "id": "2dfba887-78b8-43c0-900b-8cc692c2faa8"
    }
}

Assim que uma urlNotificacao for cadastrada para um tipo, ela passa a ser acionada (via POST) todas as vezes que o evento ocorrer. Os campos:

id — identificador do evento (não do registro). É estável entre o envio inicial e os reenvios do mesmo evento, podendo ser usado como chave de idempotência no receptor.
tipo — o tipo do evento acionado.
payload.id — o identificador do registro que teve o evento acionado. Use esse valor como parâmetro para consultar as informações completas do registro na API.

O cabeçalho User-Agent da requisição é SuperConcentrador-Webhook e o Content-Type é application/json.

Reenvio e Dead Letter Queue

Toda vez que o envio para a URL cadastrada não obtiver sucesso (o Concentrador considera sucesso uma resposta com status HTTP 200), o evento fica registrado para reenvio. Uma rotina do sistema, a cada dez minutos, tenta enviar novamente esses eventos, num total de três tentativas de reenvio. Esgotadas as três tentativas, não haverá novas tentativas para aquele evento.

GET — `/api/v1/integracoes/webhooks/deadLetterQueue`

Consulta a lista dos eventos que já esgotaram as tentativas de reenvio (três ou mais tentativas sem êxito). Assim que os dados são consultados e retornados, esses eventos são marcados como tratados e não voltam a aparecer em consultas futuras deste endpoint — evitando acúmulo. (Os registros não são fisicamente apagados da tabela; ficam marcados como recebidos.)