Pular para o conteúdo principal

Webhooks de Escrituração

Visão Geral​

Os webhooks de escrituração permitem que você receba notificações em tempo real sobre mudanças de status e eventos importantes relacionados ao processo de emissão de Notas Comerciais. Quando um evento ocorre, a QI Tech envia automaticamente um payload HTTP POST para a URL configurada em seu sistema.

Configuração de Webhooks​

Para receber webhooks, você precisa configurar uma URL de endpoint em seu sistema. Consulte a documentação de configuração de webhooks para mais detalhes sobre como cadastrar e gerenciar suas URLs de webhook.

Autenticação e Segurança​

Todos os webhooks enviados pela QI Tech incluem uma assinatura HMAC-SHA256 no header Signature. Esta assinatura deve ser validada em seu sistema para garantir a autenticidade e integridade dos dados recebidos. Para mais informações sobre o processo de validação, consulte a documentação de autenticação de webhooks.

Eventos Disponíveis​

Gestão de Emissores​

Cadastro Emissor Aprovado​

Enviado quando o cadastro de um emissor é aprovado pelo compliance.

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

Cadastro Emissor Reprovado​

Enviado quando o cadastro de um emissor é reprovado pelo compliance.

Event Type: issuer_management.issuer_status_change

Payload:

{
  "event_type": "issuer_management.issuer_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

Gestão de Investidores​

Cadastro Investidor Aprovado​

Enviado quando o cadastro de um investidor é aprovado pelo compliance.

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "approved"
  }
}

Cadastro Investidor Reprovado​

Enviado quando o cadastro de um investidor é reprovado pelo compliance.

Event Type: investor_management.investor_status_change

Payload:

{
  "event_type": "investor_management.investor_status_change",
  "event_datetime": "2025-07-30T15:32:00Z",
  "event_data": {
    "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "status": "reproved"
  }
}

Gestão de Operações​

Operação Aprovada​

Enviado quando uma operação é aprovada pelo compliance e está pronta para ser enviada para assinatura.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "pending_signature_submission"
  }
}

Operação Enviada para Assinatura​

Enviado quando uma operação é enviada para assinatura das partes envolvidas.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "waiting_signature"
  }
}

Operação Assinada e Emitida​

Enviado quando uma operação é assinada por todas as partes. Este evento confirma que a Nota Comercial foi emitida com sucesso.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "issued"
  }
}

Operação Cancelada​

Enviado quando uma operação é cancelada.

Event Type: commercial_paper.operation_status_change

Payload:

{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "canceled"
  }
}

Gestão de Subscrições​

Subscrição Enviada para Assinatura​

Enviado quando uma subscrição é criada e enviada para assinatura do investidor.

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "waiting_signature"
  }
}

Subscrição Assinada​

Enviado quando a subscrição é assinada por todas as partes e está aguardando o pagamento.

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "waiting_payment"
  }
}

Subscrição Finalizada​

Enviado quando a subscrição é completamente finalizada após a confirmação do pagamento.

Event Type: subscription.subscription_status_change

Payload:

{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "finished"
  }
}

Gestão de Pagamentos de Subscrição​

Comprovante de Pagamento Incluído​

Enviado quando um comprovante de pagamento é incluído e está aguardando confirmação.

Event Type: subscription_payment.subscription_payment_status_change

Payload:

{
  "event_type": "subscription_payment.subscription_payment_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1",
    "status": "waiting_confirmation"
  }
}

Comprovante de Pagamento Aprovado​

Enviado quando o comprovante de pagamento é aprovado e confirmado.

Event Type: subscription_payment.subscription_payment_status_change

Payload:

{
  "event_type": "subscription_payment.subscription_payment_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1",
    "status": "confirmed"
  }
}

Fluxo de Eventos​

Fluxo de Emissão de Nota Comercial​

  1. Cadastro do Emissor → issuer_status_change (approved/reproved)
  2. Cadastro do Investidor → investor_status_change (approved/reproved)
  3. Criação da Operação → operation_status_change (pending_signature_submission)
  4. Envio para Assinatura → operation_status_change (waiting_signature)
  5. Operação Emitida → operation_status_change (issued)

Fluxo de Subscrição​

  1. Criação da Subscrição → subscription_status_change (waiting_signature)
  2. Assinatura Concluída → subscription_status_change (waiting_payment)
  3. Inclusão do Comprovante → subscription_payment_status_change (waiting_confirmation)
  4. Pagamento Confirmado → subscription_payment_status_change (confirmed)
  5. Subscrição Finalizada → subscription_status_change (finished)

Boas Práticas​

  1. Responda rapidamente: Retorne um status HTTP 2xx o mais rápido possível para confirmar o recebimento do webhook.
  2. Processamento assíncrono: Para operações demoradas, confirme o recebimento imediatamente e processe o evento de forma assíncrona.
  3. Idempotência: Implemente lógica idempotente, pois webhooks podem ser reenviados em caso de falha de rede.
  4. Validação de assinatura: Sempre valide a assinatura HMAC antes de processar o webhook.
  5. Logs e monitoramento: Mantenha logs detalhados de todos os webhooks recebidos para auditoria e debugging.

Referências​