Skip to main content
Webhooks permitem que sua aplicação receba notificações em tempo real sobre eventos importantes da Parcele+.

Gerenciamento pela API

Os webhooks podem ser criados, consultados, editados e excluídos diretamente pela API de integração.

​
Disponibilidade dos webhooks

Legenda: 🟢 Disponível agora · 🟡 Planejado

Cliente (1)

🟡 Em roadmapA configuração pode ser cadastrada e fica salva, mas nenhum evento de cliente é enviado atualmente.

Simulação (2)

🟡 Em roadmapA configuração pode ser cadastrada e fica salva, mas nenhum evento de simulação é enviado atualmente.

Pedido (3)

🟢 DisponívelEnvia notificações para os eventos de pedido suportados.

Como funciona

Cadastrar configuração → Configuração salva → Envio conforme a disponibilidade do tipo
Cliente e Simulação ainda não enviam notificações. Os fluxos estão no roadmap, sem data de disponibilização definida.

​
Segmentação de webhooks

Ambientes e webhooks

Os webhooks são específicos para cada ambiente:
  • Webhooks criados em desenvolvimento recebem notificações apenas do ambiente de desenvolvimento
  • Webhooks criados em produção recebem notificações apenas de dados reais
Saiba mais sobre o ambiente de desenvolvimento aqui.

​
Configurar webhooks

Consulte os endpoints nesta aba Webhooks para gerenciar as configurações vinculadas ao seu parceiro.

​
Tipos de autenticação

Aceitamos três tipos de autenticação para os webhooks:

Sem autenticação (não recomendado)

Se o seu endpoint não requer autenticação, você pode optar por não usar nenhum método de autenticação. Nesse caso, as notificações serão enviadas para o seu endpoint sem nenhum cabeçalho de autenticação.

Basic

A autenticação Basic é um método de autenticação HTTP simples que envolve o envio de um nome de usuário e senha com cada requisição. Para usar a autenticação Basic, você precisará fornecer um nome de usuário e uma senha ao configurar o webhook.

Bearer JWT

A autenticação Bearer JWT é um método de autenticação que usa um token JSON Web Token (JWT) para autenticar as requisições. Para usar a autenticação Bearer JWT, você precisará fornecer um token JWT válido ao configurar o webhook.

​
Payload do webhook de Pedido

Quando um evento de Pedido suportado ocorre, o payload enviado para o endpoint é um JSON com a seguinte estrutura:

​
Verificando a assinatura

Toda notificação de webhook é assinada com HMAC-SHA256, enviada no cabeçalho X-ParceleMais-Signature, para que você possa confirmar que a requisição realmente veio da Parcele+ e não foi forjada por terceiros.

Quando a chave é gerada

A chave de assinatura (chaveAssinatura) é gerada automaticamente ao criar um webhook e retornada apenas na resposta desse momento — ela não é devolvida novamente por nenhuma outra consulta. Guarde-a com segurança. Editar o webhook (PUT /v1/webhooks/{tipo}) preserva a mesma chave.
O cabeçalho segue o formato:
  • t — timestamp Unix (segundos) de quando a notificação foi enviada.
  • v1 — assinatura HMAC-SHA256, em hexadecimal, calculada sobre a string {t}.{corpo_da_requisição} usando a chaveAssinatura como chave.
Para verificar, recalcule o HMAC com a mesma fórmula (HMACSHA256({t}.{corpo_da_requisição}, chaveAssinatura)) e compare o resultado com v1 usando uma comparação de tempo constante.
Sempre valide a assinatura contra o corpo bruto da requisição (antes de fazer JSON.parse/desserializar), pois qualquer reformatação do JSON altera o hash calculado.

​
Status enviados pelo webhook

Os valores abaixo são os status que podem ser enviados no campo enum_status do webhook de Pedido.

1 - Analysing

O pedido está sendo analisado automaticamente.

2 - Approved

O pedido foi aprovado.

3 - UnavailableBalance

Saldo indisponível para a operação.

4 - AnalysisExpired

O prazo de análise do pedido expirou.

5 - PendingPayment

Aguardando o pagamento.

6 - BiometryRefused

Biometria recusada.

8 - PaymentRefused

Pagamento recusado.

13 - SaleNotStarted

A venda ainda não foi iniciada.

14 - Canceled

O pedido foi cancelado.

15 - Billing

O pedido está em faturamento.

18 - PendingPaymentConfirmation

Aguardando confirmação do pagamento.

19 - Disbursed

O valor do pedido foi desembolsado.

20 - PendingInvoice

Nota fiscal pendente. A nota fiscal está inválida e liberada para reenvio.

​
Nota fiscal pendente

Você recebe a notificação PendingInvoice quando a nota fiscal do pedido é invalidada e liberada para reenvio. O webhook de Pedido (tipo: 3) envia o seguinte payload:
Esse status representa uma condição temporária da nota fiscal. Ele não altera o status real do pedido. Você recebe essa notificação quando a nota fiscal está inválida e não está marcada como importada. Nas consultas de pedidos, a mesma condição aparece como status.valor: 20 e status.descricao: "Nota fiscal pendente". Você pode localizar esses pedidos com status=20 em Listar pedidos. Reenvie o arquivo corrigido por Importar nota fiscal, com o mesmo pedidoId. Quando o reenvio marca a nota fiscal como importada, as consultas voltam a apresentar o status real do pedido. Isso não significa que a nota fiscal já foi validada.